iii-browser-sdk 0.26.0-rc.3 → 0.26.0-rc.4

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 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`, `onObserverMatch`, `onObserverDeliver` | Change what observing a function this page hosts means |
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
- | `onObserverMatch(obs, call)` | every observer wants every call |
168
- | `onObserverDeliver(call, observers)` | run every matching observer whose filters match the call; return the handler's value |
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
- `onObserverMatch` and `onObserverDeliver` are set per function. Each method
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
- .onObserverMatch((obs, call) => obs.args.selector === call.input.selector)
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.onObserverMatch('ui::on-click', {
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.onObserverDeliver('ui::on-command', async (call) => {
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.onObserverMatch('ui::on-click', (obs, call) =>
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
- `onObserverMatch` hook or an `onObserverDeliver` hook needs an engine that
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
 
@@ -1,4 +1,4 @@
1
- import { N as StreamChannelRef, a as ISdk, r as Channel, v as ChannelDirection, y as ChannelItem } from "./types-KMHoWM6-.cjs";
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
@@ -1,4 +1,4 @@
1
- import { N as StreamChannelRef, a as ISdk, r as Channel, v as ChannelDirection, y as ChannelItem } from "./types-DqyCQ8JS.mjs";
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
- * `onObserverDeliver`. Includes `observe.v1`.
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` (`onObserverMatch`):
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 (`onObserverMatch`) now. */
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(`onObserverMatch of ${this.functionId} threw; the call matches no observer`, error);
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 (`onObserverMatch`), then the function's
2052
- * `onObserverDeliver` delivers the call itself, or iii delivers it to the
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 { standby, localDispatch, private: isPrivate, observable, ...wireOptions } = options ?? {};
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
- onObserverMatch: (hook) => {
2960
- this.onObserverMatch(functionId, hook);
2955
+ onObservationMatch: (hook) => {
2956
+ this.onObservationMatch(functionId, hook);
2961
2957
  return ref;
2962
2958
  },
2963
- onObserverDeliver: (hook) => {
2964
- this.onObserverDeliver(functionId, hook);
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.onObserverMatch = (functionId, hook) => {
2984
+ this.onObservationMatch = (functionId, hook) => {
2990
2985
  this.setFunctionHook(functionId, "match", hook);
2991
2986
  return this;
2992
2987
  };
2993
- this.onObserverDeliver = (functionId, hook) => {
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, onObserverMatch or onObserverDeliver), which this engine does not advertise; it stays unregistered until the worker connects to an engine with observe.v2.`);
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. A `standby` function retries its registration until
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
- const fn = init.function_id !== void 0 ? this.functions.get(init.function_id) : void 0;
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}.