iii-browser-sdk 0.26.0-rc.3 → 0.26.0-rc.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -13
- package/dist/helpers.d.cts +1 -1
- package/dist/helpers.d.mts +1 -1
- package/dist/index.cjs +17 -60
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1 -1
- package/dist/index.d.cts.map +1 -1
- package/dist/index.d.mts +1 -1
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +17 -60
- package/dist/index.mjs.map +1 -1
- package/dist/{types-DqyCQ8JS.d.mts → types-BkZuClyZ.d.cts} +25 -33
- package/dist/{types-DqyCQ8JS.d.mts.map → types-BkZuClyZ.d.cts.map} +1 -1
- package/dist/{types-KMHoWM6-.d.cts → types-LkiBp7wP.d.mts} +25 -33
- package/dist/{types-KMHoWM6-.d.cts.map → types-LkiBp7wP.d.mts.map} +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -56,7 +56,7 @@ const users = await iii.call({
|
|
|
56
56
|
| Call (fire-and-forget) | `iii.call({ function_id, payload, action: CallAction.Void() })` | Call without waiting |
|
|
57
57
|
| Call (enqueue) | `iii.call({ function_id, payload, action: CallAction.Enqueue({ queue }) })` | Route the call through a named queue |
|
|
58
58
|
| Observe | `iii.observe('fn::id' \| { function_id, args?, filters? }, target, options?)` | Call `target` on every matching call of a function |
|
|
59
|
-
| Observer hooks | `onObserverAdded`, `onObserverRemoved`, `
|
|
59
|
+
| Observer hooks | `onObserverAdded`, `onObserverRemoved`, `onObservationMatch`, `onObservationDeliver` | Change what observing a function this page hosts means |
|
|
60
60
|
| Call through an observer | `await iii.call({ observer, payload })` | Run an observer's target from a deliver hook |
|
|
61
61
|
| Current invocation | `iii.currentInvocation()` / `iii.withInvocation(inv, fn)` | The invocation the running handler serves (caller, activation) |
|
|
62
62
|
| Create channel | `createChannel(iii)` (from `iii-browser-sdk/helpers`) | Create a streaming channel pair (writer + reader) |
|
|
@@ -164,12 +164,12 @@ hooks, each overriding a default:
|
|
|
164
164
|
| ------------------------------------ | ------------------------------------------------------------------------------------- |
|
|
165
165
|
| `onObserverAdded(obs)` | accept the observer |
|
|
166
166
|
| `onObserverRemoved(obs)` | stop delivering to it and forget it |
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
167
|
+
| `onObservationMatch(obs, call)` | every observer wants every call |
|
|
168
|
+
| `onObservationDeliver(call, observers)` | run every matching observer whose filters match the call; return the handler's value |
|
|
169
169
|
|
|
170
170
|
`onObserverAdded` and `onObserverRemoved` can be set for every function the
|
|
171
171
|
page hosts, or for one function by id or on its `FunctionRef`.
|
|
172
|
-
`
|
|
172
|
+
`onObservationMatch` and `onObservationDeliver` are set per function. Each method
|
|
173
173
|
returns its receiver, and `null` removes a hook.
|
|
174
174
|
|
|
175
175
|
An event source returns the event it is called with. `args_format` describes
|
|
@@ -193,7 +193,7 @@ iii
|
|
|
193
193
|
})
|
|
194
194
|
.onObserverRemoved((obs) => clicks.release(obs.args.selector as string))
|
|
195
195
|
// each click reaches the observers of its selector
|
|
196
|
-
.
|
|
196
|
+
.onObservationMatch((obs, call) => obs.args.selector === call.input.selector)
|
|
197
197
|
|
|
198
198
|
// a backend worker observes it
|
|
199
199
|
// iii.observe({ function_id: 'ui::on-click', args: { selector: '#buy' } }, 'analytics::track-click')
|
|
@@ -203,7 +203,7 @@ With many observers, match by keys instead: the SDK keeps an index, one
|
|
|
203
203
|
lookup per key whatever the number of observers.
|
|
204
204
|
|
|
205
205
|
```typescript
|
|
206
|
-
iii.
|
|
206
|
+
iii.onObservationMatch('ui::on-click', {
|
|
207
207
|
observer: (obs) => obs.args.selector as string, // what this observer listens for
|
|
208
208
|
call: (call) => call.input.selector, // what this call is
|
|
209
209
|
})
|
|
@@ -219,7 +219,7 @@ gets back. It applies the observers' filters with `obs.matches(call)` and
|
|
|
219
219
|
runs their targets with a call through the observer:
|
|
220
220
|
|
|
221
221
|
```typescript
|
|
222
|
-
iii.
|
|
222
|
+
iii.onObservationDeliver('ui::on-command', async (call) => {
|
|
223
223
|
const handler = commands.match(call.input)
|
|
224
224
|
if (!handler) return { handled: false }
|
|
225
225
|
if (!handler.obs.matches(call)) return { handled: false }
|
|
@@ -250,7 +250,7 @@ iii.onObserverAdded('ui::on-click', (obs) => {
|
|
|
250
250
|
// a rejected observer gets nothing
|
|
251
251
|
})
|
|
252
252
|
})
|
|
253
|
-
iii.
|
|
253
|
+
iii.onObservationMatch('ui::on-click', (obs, call) =>
|
|
254
254
|
call.metadata?.for_observer ? call.metadata.for_observer === obs.id : obs.args.selector === call.input.selector,
|
|
255
255
|
)
|
|
256
256
|
```
|
|
@@ -258,12 +258,8 @@ iii.onObserverMatch('ui::on-click', (obs, call) =>
|
|
|
258
258
|
With keys, file each observer under `for_observer:<id>` as well, and give such
|
|
259
259
|
a call that one key.
|
|
260
260
|
|
|
261
|
-
With `standby: true`, a second page that registers a function another
|
|
262
|
-
connection already hosts waits and takes it over (with its observers) when that
|
|
263
|
-
one leaves.
|
|
264
|
-
|
|
265
261
|
A function that sets `args_format`, `private: true`, `observable: false`, an
|
|
266
|
-
`
|
|
262
|
+
`onObservationMatch` hook or an `onObservationDeliver` hook needs an engine that
|
|
267
263
|
advertises `observe.v2`; against an older engine it stays unregistered, and the
|
|
268
264
|
SDK logs `UNSUPPORTED` once for it.
|
|
269
265
|
|
package/dist/helpers.d.cts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { N as StreamChannelRef, a as ISdk, r as Channel, v as ChannelDirection, y as ChannelItem } from "./types-
|
|
1
|
+
import { N as StreamChannelRef, a as ISdk, r as Channel, v as ChannelDirection, y as ChannelItem } from "./types-BkZuClyZ.cjs";
|
|
2
2
|
import { IStream } from "./stream.cjs";
|
|
3
3
|
|
|
4
4
|
//#region src/utils.d.ts
|
package/dist/helpers.d.mts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { N as StreamChannelRef, a as ISdk, r as Channel, v as ChannelDirection, y as ChannelItem } from "./types-
|
|
1
|
+
import { N as StreamChannelRef, a as ISdk, r as Channel, v as ChannelDirection, y as ChannelItem } from "./types-LkiBp7wP.mjs";
|
|
2
2
|
import { IStream } from "./stream.mjs";
|
|
3
3
|
|
|
4
4
|
//#region src/utils.d.ts
|
package/dist/index.cjs
CHANGED
|
@@ -1136,7 +1136,7 @@ const FEATURE_OBSERVE_V1 = "observe.v1";
|
|
|
1136
1136
|
/**
|
|
1137
1137
|
* The host delivers the calls of its functions (routed ones included), and
|
|
1138
1138
|
* functions may set `args_format`, `private`, `observable: false` and
|
|
1139
|
-
* `
|
|
1139
|
+
* `onObservationDeliver`. Includes `observe.v1`.
|
|
1140
1140
|
*/
|
|
1141
1141
|
const FEATURE_OBSERVE_V2 = "observe.v2";
|
|
1142
1142
|
const FEATURE_LOCAL_DISPATCH_V1 = "local-dispatch.v1";
|
|
@@ -1574,7 +1574,7 @@ var FunctionObservers = class {
|
|
|
1574
1574
|
return false;
|
|
1575
1575
|
}
|
|
1576
1576
|
/**
|
|
1577
|
-
* The observers of the call's snapshot that want `call` (`
|
|
1577
|
+
* The observers of the call's snapshot that want `call` (`onObservationMatch`):
|
|
1578
1578
|
* all of `snapshot` without a match hook, those of it the predicate accepts,
|
|
1579
1579
|
* or those filed under one of the call's keys that joined the active set no
|
|
1580
1580
|
* later than `activations` (the count when the call started), each once. A
|
|
@@ -1601,7 +1601,7 @@ var FunctionObservers = class {
|
|
|
1601
1601
|
}
|
|
1602
1602
|
return [...found];
|
|
1603
1603
|
}
|
|
1604
|
-
/** The function has a match hook (`
|
|
1604
|
+
/** The function has a match hook (`onObservationMatch`) now. */
|
|
1605
1605
|
hasMatchHook() {
|
|
1606
1606
|
return this.host.hooks(this.functionId).match !== void 0;
|
|
1607
1607
|
}
|
|
@@ -1734,7 +1734,7 @@ var FunctionObservers = class {
|
|
|
1734
1734
|
matchFailed(error) {
|
|
1735
1735
|
if (this.matchFailureLogged) return;
|
|
1736
1736
|
this.matchFailureLogged = true;
|
|
1737
|
-
this.host.logError(`
|
|
1737
|
+
this.host.logError(`onObservationMatch of ${this.functionId} threw; the call matches no observer`, error);
|
|
1738
1738
|
}
|
|
1739
1739
|
/**
|
|
1740
1740
|
* Stops delivery at once, then removes every observer through the hook
|
|
@@ -2048,8 +2048,8 @@ var FunctionObservers = class {
|
|
|
2048
2048
|
};
|
|
2049
2049
|
/**
|
|
2050
2050
|
* The delivery of one call (v2 §4.4–§4.6, decisions 20, 36, 38, 45, 55): the
|
|
2051
|
-
* observers are matched (`
|
|
2052
|
-
* `
|
|
2051
|
+
* observers are matched (`onObservationMatch`), then the function's
|
|
2052
|
+
* `onObservationDeliver` delivers the call itself, or iii delivers it to the
|
|
2053
2053
|
* matched observers whose `on` and filters accept it. For a local call the
|
|
2054
2054
|
* host evaluates `on` and filters and reports the observers delivered in
|
|
2055
2055
|
* one report item. For a routed call the engine evaluates them: the answer
|
|
@@ -2845,8 +2845,6 @@ const FUNCTION_NAMESPACE_CONFLICT = "FUNCTION_NAMESPACE_CONFLICT";
|
|
|
2845
2845
|
* support what it declares. The connection stays open -- non-fatal.
|
|
2846
2846
|
*/
|
|
2847
2847
|
const FUNCTION_REJECTIONS = new Set(["INVALID_ARGS_FORMAT", "UNSUPPORTED"]);
|
|
2848
|
-
/** A standby function retries its registration this often (decision 21), ±20 %. */
|
|
2849
|
-
const STANDBY_RETRY_MS = 1e3;
|
|
2850
2848
|
/** Why `call` refuses a call through an observer that names metadata (v2 §4.6, decision 53); the same in every SDK. */
|
|
2851
2849
|
const OBSERVER_CALL_METADATA = "a call through an observer takes no metadata; its target receives the observer's metadata";
|
|
2852
2850
|
/** Short random suffix; `crypto.randomUUID` is unavailable on insecure origins. */
|
|
@@ -2917,12 +2915,11 @@ var Sdk = class {
|
|
|
2917
2915
|
this.hooksInactiveWarned = /* @__PURE__ */ new Set();
|
|
2918
2916
|
this.unsupportedWarned = /* @__PURE__ */ new Set();
|
|
2919
2917
|
this.unregisteredHooksWarned = /* @__PURE__ */ new Set();
|
|
2920
|
-
this.standbyTimers = /* @__PURE__ */ new Map();
|
|
2921
2918
|
this.observeQueue = [];
|
|
2922
2919
|
this.registerFunction = (functionId, handler, options) => {
|
|
2923
2920
|
if (!functionId || functionId.trim() === "") throw new Error("id is required");
|
|
2924
2921
|
if (this.functions.has(functionId)) throw new Error(`function id already registered: ${functionId}`);
|
|
2925
|
-
const {
|
|
2922
|
+
const { localDispatch, private: isPrivate, observable, ...wireOptions } = options ?? {};
|
|
2926
2923
|
const fullMessage = this.snapshotRegistration({
|
|
2927
2924
|
...wireOptions,
|
|
2928
2925
|
...isPrivate === true ? { private: true } : {},
|
|
@@ -2935,7 +2932,6 @@ var Sdk = class {
|
|
|
2935
2932
|
const fn = {
|
|
2936
2933
|
message: fullMessage,
|
|
2937
2934
|
observe,
|
|
2938
|
-
standby: standby === true,
|
|
2939
2935
|
handler: async (input, metadata) => {
|
|
2940
2936
|
return await handler(input, metadata);
|
|
2941
2937
|
}
|
|
@@ -2956,12 +2952,12 @@ var Sdk = class {
|
|
|
2956
2952
|
this.onObserverRemoved(functionId, hook);
|
|
2957
2953
|
return ref;
|
|
2958
2954
|
},
|
|
2959
|
-
|
|
2960
|
-
this.
|
|
2955
|
+
onObservationMatch: (hook) => {
|
|
2956
|
+
this.onObservationMatch(functionId, hook);
|
|
2961
2957
|
return ref;
|
|
2962
2958
|
},
|
|
2963
|
-
|
|
2964
|
-
this.
|
|
2959
|
+
onObservationDeliver: (hook) => {
|
|
2960
|
+
this.onObservationDeliver(functionId, hook);
|
|
2965
2961
|
return ref;
|
|
2966
2962
|
},
|
|
2967
2963
|
observers: () => observe.observers(),
|
|
@@ -2970,7 +2966,6 @@ var Sdk = class {
|
|
|
2970
2966
|
if (this.functions.get(functionId) !== fn) return;
|
|
2971
2967
|
this.sendMessage("unregisterfunction", { id: functionId }, true);
|
|
2972
2968
|
this.functions.delete(functionId);
|
|
2973
|
-
this.stopStandby(functionId);
|
|
2974
2969
|
observe.dispose();
|
|
2975
2970
|
}
|
|
2976
2971
|
};
|
|
@@ -2986,11 +2981,11 @@ var Sdk = class {
|
|
|
2986
2981
|
else this.setWorkerHook("removed", a);
|
|
2987
2982
|
return this;
|
|
2988
2983
|
};
|
|
2989
|
-
this.
|
|
2984
|
+
this.onObservationMatch = (functionId, hook) => {
|
|
2990
2985
|
this.setFunctionHook(functionId, "match", hook);
|
|
2991
2986
|
return this;
|
|
2992
2987
|
};
|
|
2993
|
-
this.
|
|
2988
|
+
this.onObservationDeliver = (functionId, hook) => {
|
|
2994
2989
|
this.setFunctionHook(functionId, "deliver", hook);
|
|
2995
2990
|
return this;
|
|
2996
2991
|
};
|
|
@@ -3116,7 +3111,6 @@ var Sdk = class {
|
|
|
3116
3111
|
}
|
|
3117
3112
|
this.reporter.stop();
|
|
3118
3113
|
this.clearReconnectTimeout();
|
|
3119
|
-
for (const functionId of [...this.standbyTimers.keys()]) this.stopStandby(functionId);
|
|
3120
3114
|
for (const [_id, invocation] of this.invocations) {
|
|
3121
3115
|
if (invocation.timeout) clearTimeout(invocation.timeout);
|
|
3122
3116
|
invocation.reject(/* @__PURE__ */ new Error("iii is shutting down"));
|
|
@@ -3255,7 +3249,7 @@ var Sdk = class {
|
|
|
3255
3249
|
warnUnsupported(functionId) {
|
|
3256
3250
|
if (this.unsupportedWarned.has(functionId)) return;
|
|
3257
3251
|
this.unsupportedWarned.add(functionId);
|
|
3258
|
-
this.logWarn(`UNSUPPORTED: function "${functionId}" needs observe.v2 (args_format, private, observable: false,
|
|
3252
|
+
this.logWarn(`UNSUPPORTED: function "${functionId}" needs observe.v2 (args_format, private, observable: false, onObservationMatch or onObservationDeliver), which this engine does not advertise; it stays unregistered until the worker connects to an engine with observe.v2.`);
|
|
3259
3253
|
}
|
|
3260
3254
|
/** The hooks that apply to one function now: the worker's, and those set for its id. */
|
|
3261
3255
|
hooksOf(functionId) {
|
|
@@ -3636,7 +3630,6 @@ var Sdk = class {
|
|
|
3636
3630
|
this.ws = void 0;
|
|
3637
3631
|
this.registeredOnConnection = false;
|
|
3638
3632
|
this.observesSent.clear();
|
|
3639
|
-
for (const functionId of [...this.standbyTimers.keys()]) this.stopStandby(functionId);
|
|
3640
3633
|
if (this.isShuttingDown) return;
|
|
3641
3634
|
this.setConnectionState("disconnected");
|
|
3642
3635
|
this.scheduleReconnect();
|
|
@@ -3940,11 +3933,7 @@ var Sdk = class {
|
|
|
3940
3933
|
} else if (msgType === "functionregistered") {
|
|
3941
3934
|
const msg = decodeFunctionRegistered(message);
|
|
3942
3935
|
const fn = this.functions.get(msg.id);
|
|
3943
|
-
if (fn && fn.sentEpoch === this.connectionEpoch)
|
|
3944
|
-
this.stopStandby(msg.id);
|
|
3945
|
-
fn.standingBy = false;
|
|
3946
|
-
fn.observe.onFunctionRegistered(msg, this.connectionEpoch);
|
|
3947
|
-
}
|
|
3936
|
+
if (fn && fn.sentEpoch === this.connectionEpoch) fn.observe.onFunctionRegistered(msg, this.connectionEpoch);
|
|
3948
3937
|
} else if (msgType === "observeradded") {
|
|
3949
3938
|
const msg = decodeObserverAdded(message);
|
|
3950
3939
|
const fn = this.functions.get(msg.function_id);
|
|
@@ -4054,8 +4043,7 @@ var Sdk = class {
|
|
|
4054
4043
|
* - {@link FUNCTION_NAMESPACE_CONFLICT}: another live worker in this
|
|
4055
4044
|
* namespace already exports this one function id. Only that registration
|
|
4056
4045
|
* is refused; the connection stays open and the worker keeps serving its
|
|
4057
|
-
* other functions.
|
|
4058
|
-
* the id is free.
|
|
4046
|
+
* other functions.
|
|
4059
4047
|
* - {@link FUNCTION_REJECTIONS} on one function: only that function is
|
|
4060
4048
|
* refused. Logged; the worker keeps serving.
|
|
4061
4049
|
* - {@link WORKER_NAMESPACE_CONFLICT}, or any other code: terminal — stop and
|
|
@@ -4064,12 +4052,7 @@ var Sdk = class {
|
|
|
4064
4052
|
*/
|
|
4065
4053
|
onRegistrationRejected(init) {
|
|
4066
4054
|
if (init.code === FUNCTION_NAMESPACE_CONFLICT) {
|
|
4067
|
-
|
|
4068
|
-
fn?.observe.onRegistrationRejected(this.connectionEpoch);
|
|
4069
|
-
if (fn?.standby && init.function_id !== void 0) {
|
|
4070
|
-
this.standBy(init.function_id, fn, init.owner_worker_id);
|
|
4071
|
-
return;
|
|
4072
|
-
}
|
|
4055
|
+
(init.function_id !== void 0 ? this.functions.get(init.function_id) : void 0)?.observe.onRegistrationRejected(this.connectionEpoch);
|
|
4073
4056
|
this.logWarn(`Function registration rejected: function "${init.function_id ?? "<unknown>"}" in namespace "${init.namespace}" is already exported by worker ${init.owner_worker_id}. Staying connected and serving the rest.`);
|
|
4074
4057
|
return;
|
|
4075
4058
|
}
|
|
@@ -4092,32 +4075,6 @@ var Sdk = class {
|
|
|
4092
4075
|
this.setConnectionState("failed");
|
|
4093
4076
|
this.ws?.close();
|
|
4094
4077
|
}
|
|
4095
|
-
/**
|
|
4096
|
-
* A `standby` function whose id another connection hosts (decision 21): its
|
|
4097
|
-
* registration is retried every second (±20 %) until the engine accepts it
|
|
4098
|
-
* (`functionregistered`, whose observers then run their hooks here) or the
|
|
4099
|
-
* function is unregistered.
|
|
4100
|
-
*/
|
|
4101
|
-
standBy(functionId, fn, owner) {
|
|
4102
|
-
if (this.standbyTimers.has(functionId)) return;
|
|
4103
|
-
if (!fn.standingBy) this.logInfo(`Function "${functionId}" is hosted by worker ${owner}; standing by to take it over when it leaves.`);
|
|
4104
|
-
fn.standingBy = true;
|
|
4105
|
-
const delay = Math.floor(STANDBY_RETRY_MS * (.8 + .4 * Math.random()));
|
|
4106
|
-
const timer = setTimeout(() => {
|
|
4107
|
-
this.standbyTimers.delete(functionId);
|
|
4108
|
-
if (this.functions.get(functionId) !== fn || !this.mayRegister(functionId, fn)) return;
|
|
4109
|
-
this.replayRegistration("registerfunction", fn.message);
|
|
4110
|
-
fn.sentEpoch = this.connectionEpoch;
|
|
4111
|
-
}, delay);
|
|
4112
|
-
require_utils.unrefTimer(timer);
|
|
4113
|
-
this.standbyTimers.set(functionId, timer);
|
|
4114
|
-
}
|
|
4115
|
-
stopStandby(functionId) {
|
|
4116
|
-
const timer = this.standbyTimers.get(functionId);
|
|
4117
|
-
if (!timer) return;
|
|
4118
|
-
clearTimeout(timer);
|
|
4119
|
-
this.standbyTimers.delete(functionId);
|
|
4120
|
-
}
|
|
4121
4078
|
};
|
|
4122
4079
|
/**
|
|
4123
4080
|
* Factory object that constructs routing actions for {@link ISdk.call}.
|