Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 | 3x 3x 10x 16x 34x 34x 34x 34x 34x 34x 4x 30x 16x 30x 30x 30x 4x 4x 4x 3x 4x 6x 5x 5x 6x 9x 16x 16x 16x 16x 16x 2x 2x 16x 34x 22x 22x 22x 14x 14x | import { AppCtx } from '@tao.js/core';
/** @typedef {import('./wire').NetworkSurface} NetworkSurface */
// for backwards compatibility
const MAX_SAFE_INTEGER = Math.pow(2, 53) - 1;
let transponderId = 0;
function newTransponderId() {
// Stryker disable next-line ArithmeticOperator,UpdateOperator: counter monotonicity/modulo wraparound at MAX_SAFE_INTEGER is untestable without exhausting the counter
return (transponderId = ++transponderId % MAX_SAFE_INTEGER);
}
function transponderControl(transponderId, signal) {
return { transponderId, signal };
}
/**
* A trigram in short (`t`/`a`/`o`) or long (`term`/`action`/`orient`) keys;
* long-form keys win.
*
* @typedef {Object} Trigram
* @property {string} [t] - term (short key)
* @property {string} [term] - term (long key)
* @property {string} [a] - action (short key)
* @property {string} [action] - action (long key)
* @property {string} [o] - orient (short key)
* @property {string} [orient] - orient (long key)
*/
/**
* Allows use of Promises with a Network by returning a Promise from a signalling method
* that will only resolve based on one of the handlers attached to the wrapped Network
* being called.
*
* It is not recommended to attach a Transponder to your primary Network or Kernel as this will
* resolve Promises with the first AppCon handled (unless that is the desired behavior).
*
* It is recommended to attach a Transponder to one of the other `utils` classes that filter
* or have a subset of the handlers of your primary Network like a Channel.
*
* Implemented as an `onDispatch` decoration on the wrapped surface (a raw
* Network/Kernel network, or a Channel's private network via
* `Channel.decorate`), self-filtered on `envelope.cascade.transponderId`.
* The transponder tag rides the cascade scope of the envelope, so it
* survives every hop of a chain (see ENVELOPE-SPEC.md); resolve-once is
* enforced by stamping `signalled` on the shared cascade reference.
*
* @export
* @class Transponder
*/
export default class Transponder {
/**
*Creates an instance of Transponder.
*
* Surface resolution follows the utils convention
* (`typeof network.enter === 'function' ? network : network._network`):
* pass anything exposing the envelope gate directly (a `Network`, or a
* `Channel` — whose `enter`/`decorate` scope this Transponder to the
* channel), or a Kernel-shaped wrapper exposing `_network`. The resolved
* surface must support `enter` and `decorate`.
*
* @param {NetworkSurface} network - the surface to wrap with a `Transponder`
* @param {(string|function(number): (string|number))} [id] - pass either a desired Transponder ID value as a `string` or a `function` that will be used to generate a Transponder ID
* the `function` will be called with a new Transponder ID integer value to help ensure uniqueness
* @param {number} [timeoutMs=0] - a timeout to be used when awaiting `Promises`
* - `0` - no timeout will be used
* - `> 0` - timeout will be used to `reject` the `Promise` if it is not signaled in time
* - use this to prevent unexpected behaviors
* - negative and non-numeric values clamp to `0`
* @param {PromiseConstructor} [promise=Promise] - a `Promise` constructor to be used when creating promises
* by a signalling method.
* @param {boolean} [debug=false] - pass true to console.log internal activity
* @throws {Error} when the resolved surface lacks envelope support
* (`enter` + `decorate`) - upgrade `@tao.js/core`
* @memberof Transponder
*/
constructor(network, id, timeoutMs = 0, promise = Promise, debug = false) {
this._debug = debug;
this._transponderId =
typeof id === 'function'
? id(newTransponderId())
: id || newTransponderId();
const inTO = +timeoutMs || 0;
// Stryker disable next-line EqualityOperator: equivalent - `inTO || 0` above already coerces -0/NaN to 0, so for every remaining value `inTO > 0` and `inTO >= 0` pick the same branch (0 stays 0 either way)
this._timeoutMs = inTO > 0 ? inTO : 0;
this._network =
typeof network.enter === 'function' ? network : network._network;
if (
!this._network ||
typeof this._network.enter !== 'function' ||
typeof this._network.decorate !== 'function'
) {
throw new Error(
'Transponder requires a @tao.js/core version with envelope support - upgrade @tao.js/core',
);
}
this._decoration = {
// Stryker disable next-line StringLiteral: decoration name is a diagnostic label with no observable behavior
name: `transponder:${this._transponderId}`,
onDispatch: (ac, envelope) =>
this.handleSignalAppCon(ac, envelope.cascade),
};
this._undecorate = this._network.decorate(this._decoration);
this._promise = promise;
this._cloneWithId = typeof id === 'function' ? id : undefined;
}
/**
* Clones a Transponder on the same wrapped surface with the same timeout,
* Promise constructor and debug settings. The clone registers its own
* decoration under its own Transponder ID.
*
* @param {(string|function(number): (string|number))} [cloneId] - used as the cloned
* `Transponder`'s ID, same as the `id` param to the constructor;
* falls back to the constructor's `id` generator when one was given
* @returns {Transponder} the cloned Transponder
* @memberof Transponder
*/
clone(cloneId) {
const clone = new Transponder(
this._network,
cloneId || this._cloneWithId,
this._timeoutMs,
this._promise,
this._debug,
);
return clone;
}
/**
* Attaches the `Transponder` to the `Network` it wraps by enabling the signalling to any
* `Promises` that are created using one of the signalling methods.
*
* This is the inverse operation of the {@linkcode detach()} method and used to undo that
* operation.
*
* `attach()` is unnecessary unless {@linkcode detach()} has been called as a newly
* constructed `Transponder` is always attached to the `Network` it wraps.
*
* @see {@link detach}
*
* @returns {Transponder} this
* @memberof Transponder
*/
attach() {
// Stryker disable next-line ConditionalExpression: guard keeps attach idempotent; double-decorating would only duplicate a first-wins signal
if (!this._undecorate) {
this._undecorate = this._network.decorate(this._decoration);
}
return this;
}
/**
* Detaches the `Transponder` from the `Network` it wraps by disabling the signaling to any
* `Promises` that are created using one of the signalling methods.
*
* Detach is temporary and can be reestablished using the {@link attach()} method.
*
* @see {@link attach()}
*
* @returns {Transponder} this
* @memberof Transponder
*/
detach() {
if (this._undecorate) {
this._undecorate();
this._undecorate = null;
}
return this;
}
/**
* Builds an AppCtx from a trigram + datagram (long-form keys win) and
* signals it via {@linkcode setAppCtx}.
*
* @param {Trigram} trigram
* @param {*} data - datagram(s) for the signal
* @param {Object} [opts] - as {@linkcode setAppCtx}
* @param {(Object|null)} [opts.chain] - prior chain state to continue
* @returns {Promise<AppCtx>} as {@linkcode setAppCtx}
* @memberof Transponder
*/
setCtx({ t, term, a, action, o, orient }, data, opts) {
return this.setAppCtx(
new AppCtx(term || t, action || a, orient || o, data),
opts,
);
}
/**
* Enters the AppCtx on the wrapped surface with this Transponder's
* `{ transponderId, signal }` cascade tag — the cascade (control) object
* is one shared reference for the whole cascade, so the tag survives
* every hop of a chain.
*
* Resolution semantics: the Promise resolves with the first AppCon the
* Transponder's decoration observes dispatching for this cascade — the
* first handled AppCon of the cascade. Attached to a bare Network/Kernel
* that is the entered AppCtx itself; attached to a Channel (the
* decoration observes the channel's private network) it is the first
* descendant mirrored onto the channel — the entry hop itself is not
* mirrored. Resolve-once: the first signal stamps `signalled` on the
* shared cascade, so later dispatches of the same cascade never signal
* again and the Promise settles at most once.
*
* @param {AppCtx} ac
* @param {Object} [opts]
* @param {(Object|null)} [opts.chain] - prior chain state to continue (e.g. a
* remote trace received over a transport — ENVELOPE-SPEC.md §9)
* @returns {Promise<AppCtx>} resolves with the first handled AppCon of the
* cascade; rejects with the string `reached timeout of: <ms>ms`
* when a `timeoutMs` was configured and no signal arrived in time
* @memberof Transponder
*/
setAppCtx(ac, { chain = null } = {}) {
const transponderId = this._transponderId;
const timeoutMs = this._timeoutMs;
const promise = this._promise;
return new promise((resolve, reject) => {
if (timeoutMs) {
setTimeout(() => {
reject(`reached timeout of: ${timeoutMs}ms`);
}, timeoutMs);
}
this._network.enter(ac, {
cascade: transponderControl(transponderId, resolve),
chain,
});
});
}
/**
* `onDispatch` decoration callback: signals the awaiting Promise with the
* first dispatched AppCon of a matching cascade. Self-filtered on
* `control.transponderId`; resolve-once is enforced by stamping
* `signalled` on the shared cascade control.
*
* @param {AppCtx} ac
* @param {Object} control - the envelope's cascade scope
* (`{ transponderId, signal, signalled }`)
* @returns {void}
* @memberof Transponder
*/
handleSignalAppCon = (ac, control) => {
// Stryker disable all: optional debug logging
this._debug &&
console.log(
`transponder{${this._transponderId}}::handleSignalFirstAppCon::ac:`,
ac.unwrapCtx(),
);
this._debug &&
console.log(
`transponder{${
this._transponderId
}}::handleSignalFirstAppCon::control:`,
control,
);
// Stryker restore all
// first matching handler will signal the listener
if (
control.transponderId === this._transponderId &&
control.signal &&
!control.signalled
) {
control.signalled = true;
control.signal(ac);
}
};
}
|