iii-browser-sdk 0.26.0-rc.2 → 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. */
@@ -2895,6 +2893,8 @@ function resolveNamespace(optionNamespace) {
2895
2893
  if (optionNamespace !== void 0 && optionNamespace.trim() === "") throw new Error(`namespace is empty: options.namespace was set to ${JSON.stringify(optionNamespace)}. Give it a name, or leave it unset to register in \`default\`.`);
2896
2894
  return optionNamespace;
2897
2895
  }
2896
+ /** The upgrade guide the removed 0.25 trigger APIs point to. */
2897
+ const UPGRADE_GUIDE = "https://iii.dev/docs/upgrading/from-0-25-x";
2898
2898
  var Sdk = class {
2899
2899
  constructor(address, options) {
2900
2900
  this.address = address;
@@ -2915,12 +2915,11 @@ var Sdk = class {
2915
2915
  this.hooksInactiveWarned = /* @__PURE__ */ new Set();
2916
2916
  this.unsupportedWarned = /* @__PURE__ */ new Set();
2917
2917
  this.unregisteredHooksWarned = /* @__PURE__ */ new Set();
2918
- this.standbyTimers = /* @__PURE__ */ new Map();
2919
2918
  this.observeQueue = [];
2920
2919
  this.registerFunction = (functionId, handler, options) => {
2921
2920
  if (!functionId || functionId.trim() === "") throw new Error("id is required");
2922
2921
  if (this.functions.has(functionId)) throw new Error(`function id already registered: ${functionId}`);
2923
- const { standby, localDispatch, private: isPrivate, observable, ...wireOptions } = options ?? {};
2922
+ const { localDispatch, private: isPrivate, observable, ...wireOptions } = options ?? {};
2924
2923
  const fullMessage = this.snapshotRegistration({
2925
2924
  ...wireOptions,
2926
2925
  ...isPrivate === true ? { private: true } : {},
@@ -2933,7 +2932,6 @@ var Sdk = class {
2933
2932
  const fn = {
2934
2933
  message: fullMessage,
2935
2934
  observe,
2936
- standby: standby === true,
2937
2935
  handler: async (input, metadata) => {
2938
2936
  return await handler(input, metadata);
2939
2937
  }
@@ -2954,12 +2952,12 @@ var Sdk = class {
2954
2952
  this.onObserverRemoved(functionId, hook);
2955
2953
  return ref;
2956
2954
  },
2957
- onObserverMatch: (hook) => {
2958
- this.onObserverMatch(functionId, hook);
2955
+ onObservationMatch: (hook) => {
2956
+ this.onObservationMatch(functionId, hook);
2959
2957
  return ref;
2960
2958
  },
2961
- onObserverDeliver: (hook) => {
2962
- this.onObserverDeliver(functionId, hook);
2959
+ onObservationDeliver: (hook) => {
2960
+ this.onObservationDeliver(functionId, hook);
2963
2961
  return ref;
2964
2962
  },
2965
2963
  observers: () => observe.observers(),
@@ -2968,7 +2966,6 @@ var Sdk = class {
2968
2966
  if (this.functions.get(functionId) !== fn) return;
2969
2967
  this.sendMessage("unregisterfunction", { id: functionId }, true);
2970
2968
  this.functions.delete(functionId);
2971
- this.stopStandby(functionId);
2972
2969
  observe.dispose();
2973
2970
  }
2974
2971
  };
@@ -2984,11 +2981,11 @@ var Sdk = class {
2984
2981
  else this.setWorkerHook("removed", a);
2985
2982
  return this;
2986
2983
  };
2987
- this.onObserverMatch = (functionId, hook) => {
2984
+ this.onObservationMatch = (functionId, hook) => {
2988
2985
  this.setFunctionHook(functionId, "match", hook);
2989
2986
  return this;
2990
2987
  };
2991
- this.onObserverDeliver = (functionId, hook) => {
2988
+ this.onObservationDeliver = (functionId, hook) => {
2992
2989
  this.setFunctionHook(functionId, "deliver", hook);
2993
2990
  return this;
2994
2991
  };
@@ -3087,6 +3084,15 @@ var Sdk = class {
3087
3084
  return this.invokeRemote(req, namespace);
3088
3085
  };
3089
3086
  this.trigger = this.call;
3087
+ this.registerTrigger = () => {
3088
+ throw new Error(`registerTrigger was removed in iii 0.26.0: bind functions with iii.observe(source, target). registerTrigger({ type: 'cron', function_id, config }) becomes iii.observe({ function_id: 'cron::on-tick', args: config }, function_id). Every trigger type's function is in the migration guide: ${UPGRADE_GUIDE}`);
3089
+ };
3090
+ this.registerTriggerType = () => {
3091
+ throw new Error(`registerTriggerType was removed in iii 0.26.0: a trigger type is now a function that consumers observe. Register it with registerFunction('<worker>::on-<event>', (event) => event, { args_format, private: true }), move the TriggerHandler to onObserverAdded and onObserverRemoved, and call the function once per event. Migration guide: ${UPGRADE_GUIDE}#move-a-trigger-type-to-an-observable-function`);
3092
+ };
3093
+ this.unregisterTriggerType = () => {
3094
+ throw new Error(`unregisterTriggerType was removed in iii 0.26.0: a trigger type is now a function. Unregister it with the FunctionRef that registerFunction returns: functionRef.unregister(). Migration guide: ${UPGRADE_GUIDE}#move-a-trigger-type-to-an-observable-function`);
3095
+ };
3090
3096
  this.__helpers_create_stream = (streamName, stream) => {
3091
3097
  this.registerFunction(`stream::get(${streamName})`, stream.get.bind(stream));
3092
3098
  this.registerFunction(`stream::set(${streamName})`, stream.set.bind(stream));
@@ -3105,7 +3111,6 @@ var Sdk = class {
3105
3111
  }
3106
3112
  this.reporter.stop();
3107
3113
  this.clearReconnectTimeout();
3108
- for (const functionId of [...this.standbyTimers.keys()]) this.stopStandby(functionId);
3109
3114
  for (const [_id, invocation] of this.invocations) {
3110
3115
  if (invocation.timeout) clearTimeout(invocation.timeout);
3111
3116
  invocation.reject(/* @__PURE__ */ new Error("iii is shutting down"));
@@ -3244,7 +3249,7 @@ var Sdk = class {
3244
3249
  warnUnsupported(functionId) {
3245
3250
  if (this.unsupportedWarned.has(functionId)) return;
3246
3251
  this.unsupportedWarned.add(functionId);
3247
- 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.`);
3248
3253
  }
3249
3254
  /** The hooks that apply to one function now: the worker's, and those set for its id. */
3250
3255
  hooksOf(functionId) {
@@ -3625,7 +3630,6 @@ var Sdk = class {
3625
3630
  this.ws = void 0;
3626
3631
  this.registeredOnConnection = false;
3627
3632
  this.observesSent.clear();
3628
- for (const functionId of [...this.standbyTimers.keys()]) this.stopStandby(functionId);
3629
3633
  if (this.isShuttingDown) return;
3630
3634
  this.setConnectionState("disconnected");
3631
3635
  this.scheduleReconnect();
@@ -3929,11 +3933,7 @@ var Sdk = class {
3929
3933
  } else if (msgType === "functionregistered") {
3930
3934
  const msg = decodeFunctionRegistered(message);
3931
3935
  const fn = this.functions.get(msg.id);
3932
- if (fn && fn.sentEpoch === this.connectionEpoch) {
3933
- this.stopStandby(msg.id);
3934
- fn.standingBy = false;
3935
- fn.observe.onFunctionRegistered(msg, this.connectionEpoch);
3936
- }
3936
+ if (fn && fn.sentEpoch === this.connectionEpoch) fn.observe.onFunctionRegistered(msg, this.connectionEpoch);
3937
3937
  } else if (msgType === "observeradded") {
3938
3938
  const msg = decodeObserverAdded(message);
3939
3939
  const fn = this.functions.get(msg.function_id);
@@ -4043,8 +4043,7 @@ var Sdk = class {
4043
4043
  * - {@link FUNCTION_NAMESPACE_CONFLICT}: another live worker in this
4044
4044
  * namespace already exports this one function id. Only that registration
4045
4045
  * is refused; the connection stays open and the worker keeps serving its
4046
- * other functions. A `standby` function retries its registration until
4047
- * the id is free.
4046
+ * other functions.
4048
4047
  * - {@link FUNCTION_REJECTIONS} on one function: only that function is
4049
4048
  * refused. Logged; the worker keeps serving.
4050
4049
  * - {@link WORKER_NAMESPACE_CONFLICT}, or any other code: terminal — stop and
@@ -4053,12 +4052,7 @@ var Sdk = class {
4053
4052
  */
4054
4053
  onRegistrationRejected(init) {
4055
4054
  if (init.code === FUNCTION_NAMESPACE_CONFLICT) {
4056
- const fn = init.function_id !== void 0 ? this.functions.get(init.function_id) : void 0;
4057
- fn?.observe.onRegistrationRejected(this.connectionEpoch);
4058
- if (fn?.standby && init.function_id !== void 0) {
4059
- this.standBy(init.function_id, fn, init.owner_worker_id);
4060
- return;
4061
- }
4055
+ (init.function_id !== void 0 ? this.functions.get(init.function_id) : void 0)?.observe.onRegistrationRejected(this.connectionEpoch);
4062
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.`);
4063
4057
  return;
4064
4058
  }
@@ -4081,32 +4075,6 @@ var Sdk = class {
4081
4075
  this.setConnectionState("failed");
4082
4076
  this.ws?.close();
4083
4077
  }
4084
- /**
4085
- * A `standby` function whose id another connection hosts (decision 21): its
4086
- * registration is retried every second (±20 %) until the engine accepts it
4087
- * (`functionregistered`, whose observers then run their hooks here) or the
4088
- * function is unregistered.
4089
- */
4090
- standBy(functionId, fn, owner) {
4091
- if (this.standbyTimers.has(functionId)) return;
4092
- if (!fn.standingBy) this.logInfo(`Function "${functionId}" is hosted by worker ${owner}; standing by to take it over when it leaves.`);
4093
- fn.standingBy = true;
4094
- const delay = Math.floor(STANDBY_RETRY_MS * (.8 + .4 * Math.random()));
4095
- const timer = setTimeout(() => {
4096
- this.standbyTimers.delete(functionId);
4097
- if (this.functions.get(functionId) !== fn || !this.mayRegister(functionId, fn)) return;
4098
- this.replayRegistration("registerfunction", fn.message);
4099
- fn.sentEpoch = this.connectionEpoch;
4100
- }, delay);
4101
- require_utils.unrefTimer(timer);
4102
- this.standbyTimers.set(functionId, timer);
4103
- }
4104
- stopStandby(functionId) {
4105
- const timer = this.standbyTimers.get(functionId);
4106
- if (!timer) return;
4107
- clearTimeout(timer);
4108
- this.standbyTimers.delete(functionId);
4109
- }
4110
4078
  };
4111
4079
  /**
4112
4080
  * Factory object that constructs routing actions for {@link ISdk.call}.