iii-browser-sdk 0.25.0 → 0.25.1-alpha.2

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.
@@ -1,14 +1,307 @@
1
+ //#region src/observe-types.d.ts
2
+ /** What an observer ships to its target. Default `['input', 'output', 'caller']`. */
3
+ type Capture = 'input' | 'output' | 'error' | 'caller' | 'metadata';
4
+ /**
5
+ * An observer's lifecycle: `pending` (no host yet, waiting for the host's
6
+ * ack, or no target yet) → `active` or `error`; `suspended` while its worker
7
+ * or target is away; `disposed` at the end.
8
+ */
9
+ type ObserverState = 'pending' | 'active' | 'suspended' | 'error' | 'disposed';
10
+ /**
11
+ * A declarative filter over `input`, `output`, `error`, `caller` and
12
+ * `metadata`, with explicit operators only:
13
+ * `{ 'input.amount': { $gte: 500 } }`. See the filter language reference.
14
+ */
15
+ type Filter = Record<string, unknown>;
16
+ /** The right side of `iii.observe`: a registered function. */
17
+ type Target = string | {
18
+ function_id: string;
19
+ namespace?: string;
20
+ };
21
+ /** A state reason or an error: a machine-readable code and a message. */
22
+ type ObserveReason = {
23
+ code: string;
24
+ message: string;
25
+ };
26
+ /**
27
+ * Who started an invocation: the worker (`worker_id` / `worker_name`, stamped
28
+ * by the engine), and the function and invocation the call was made from.
29
+ */
30
+ interface Caller {
31
+ /** Absent on activations, whose caller is the engine (`worker_name: 'iii-engine'`). */
32
+ worker_id?: string;
33
+ worker_name?: string;
34
+ /** The handler the call was made from; absent for top-level calls. */
35
+ function_id?: string;
36
+ invocation_id?: string;
37
+ /** The caller of that handler, one level only. */
38
+ parent?: Omit<Caller, 'parent'>;
39
+ }
40
+ /**
41
+ * A caller as the SDK knows it: every field may be missing (a top-level call
42
+ * has no function; a call made before `WorkerRegistered` has no worker id).
43
+ */
44
+ type CallerInfo = Partial<Omit<Caller, 'parent'>> & {
45
+ parent?: Partial<Omit<Caller, 'parent'>>;
46
+ };
47
+ /**
48
+ * What an observer's target receives when iii delivers with
49
+ * `deliver: 'envelope'` (the default). Fields not in the observer's
50
+ * `capture` are absent.
51
+ */
52
+ interface Observed<I = unknown, O = unknown> {
53
+ observer_id: string;
54
+ activation_id: string;
55
+ function_id: string;
56
+ namespace: string;
57
+ invocation_id: string;
58
+ status: 'success' | 'error';
59
+ input?: I;
60
+ output?: O;
61
+ error?: {
62
+ code: string;
63
+ message: string;
64
+ };
65
+ caller?: Caller;
66
+ metadata?: Record<string, unknown>;
67
+ started_at_ms: number;
68
+ duration_ms: number;
69
+ }
70
+ /** The left side of `iii.observe`: what is observed. */
71
+ interface ObserveSource {
72
+ /** The observed function. */
73
+ function_id: string;
74
+ /** Defaults to this worker's namespace (`engine::*` and `configuration::*` resolve to `default`). */
75
+ namespace?: string;
76
+ /**
77
+ * For the worker that hosts the function: what to set up and which calls
78
+ * to deliver (a table, a cron expression, a route). The engine validates
79
+ * them against the function's `args_format`.
80
+ */
81
+ args?: Record<string, unknown>;
82
+ /** Which calls reach the target, by `input`, `output`, `error`, `caller` and `metadata`; `{}` (or absent) = every call. */
83
+ filters?: Filter;
84
+ /** Which outcomes reach the target; default `'success'`. */
85
+ on?: 'success' | 'error' | 'complete';
86
+ /** What the envelope carries; default `['input', 'output', 'caller']`. */
87
+ capture?: Capture[];
88
+ /**
89
+ * What the target receives when iii delivers: the {@link Observed} envelope
90
+ * (default), the call's `input`, or its `output`.
91
+ */
92
+ deliver?: 'envelope' | 'input' | 'output';
93
+ }
94
+ /** The observer itself: its id, policy and metadata. */
95
+ interface ObserverOptions {
96
+ /**
97
+ * Default: a random UUID, stable across replays. The handle holds it until
98
+ * it is disposed: an `observe` of an id a handle of this client holds
99
+ * throws an {@link ObserveRejection} with code `OBSERVER_ID_CONFLICT` and
100
+ * sends nothing.
101
+ */
102
+ id?: string;
103
+ /** The observer is disposed after this many activations (`MAX_FIRES`). Default: unlimited. */
104
+ max_fires?: number;
105
+ /** The observer is disposed this many milliseconds after it is created (`EXPIRED`). Default: never. */
106
+ expires_in_ms?: number;
107
+ /**
108
+ * Activations running at once; further ones queue, then drop as `OVERFLOW`.
109
+ * Default: the engine's `observers.default_max_in_flight` (64).
110
+ */
111
+ max_in_flight?: number;
112
+ /** Delivered as the metadata sidecar of every activation. */
113
+ metadata?: Record<string, unknown>;
114
+ }
115
+ /** What `iii.observe` returns, synchronously. */
116
+ interface ObserverHandle {
117
+ readonly id: string;
118
+ readonly state: ObserverState;
119
+ /** Why the observer is in its state (`error`, `suspended`, `disposed`). */
120
+ readonly reason?: ObserveReason;
121
+ /**
122
+ * Resolves when the observer is `active`; rejects with an
123
+ * {@link ObserveRejection} carrying the code when it turns `error` or
124
+ * `disposed` first.
125
+ */
126
+ ready(): Promise<void>;
127
+ /**
128
+ * Calls `listener` on every state change, in order; returns the
129
+ * unsubscribe function. Listeners are called asynchronously (never on the
130
+ * connection's read path), so they may call the client.
131
+ */
132
+ onStateChange(listener: (state: ObserverState, reason?: ObserveReason) => void): () => void;
133
+ /**
134
+ * Removes the observer (`unobserve`). It is not replayed on reconnect.
135
+ * After the engine refused the `observe`, it sends nothing. It resolves at
136
+ * once in every case and awaits no answer from the engine, also when it is
137
+ * called before the answer to the `observe` arrives.
138
+ */
139
+ dispose(): Promise<void>;
140
+ }
141
+ /**
142
+ * One call of a function, as its host delivers it: what the handler was
143
+ * called with and what it returned (or threw). Observers observe `output`,
144
+ * the handler's return value.
145
+ */
146
+ interface Call<I = unknown, O = unknown> {
147
+ function_id: string;
148
+ invocation_id: string;
149
+ status: 'success' | 'error';
150
+ input: I;
151
+ /** The handler's return value: what observers observe. */
152
+ output?: O;
153
+ /** What the handler threw. */
154
+ error?: {
155
+ code: string;
156
+ message: string;
157
+ stacktrace?: string;
158
+ };
159
+ /** Who made the call; absent for a call made outside any handler. */
160
+ caller?: Caller;
161
+ metadata?: Record<string, unknown>;
162
+ }
163
+ /**
164
+ * An observer as the worker that hosts its function sees it (the hooks,
165
+ * `FunctionRef.observers()`): its args, filters, target, capture and `on`.
166
+ * Who observes, the observer's metadata and its policy stay with the engine.
167
+ */
168
+ interface Observer {
169
+ readonly id: string;
170
+ /** The observed function (one this worker hosts). */
171
+ readonly function_id: string;
172
+ /** The observer's args, validated against the function's `args_format` by the engine. */
173
+ readonly args: Record<string, unknown>;
174
+ /** The observer's filters, normalized. */
175
+ readonly filters: Filter;
176
+ /** The target function id. */
177
+ readonly target: string;
178
+ readonly on: 'success' | 'error' | 'complete';
179
+ readonly capture: Capture[];
180
+ /**
181
+ * Whether `call` reaches this observer: its `on` accepts the call's
182
+ * `status` (absent reads as `'success'`) and its filters match the call.
183
+ */
184
+ matches(call: Partial<Call>): boolean;
185
+ /**
186
+ * Resolves once the SDK has acked the observer. A call made after it
187
+ * resolves reaches an active observer, so a provider sends an observer its
188
+ * initial state from here: a call through it
189
+ * (`iii.call({ observer: obs, payload })`), which runs its target alone
190
+ * with the payload as given. Rejects with an
191
+ * {@link ObserveRejection} when the observer is rejected first.
192
+ *
193
+ * @example
194
+ * ```typescript
195
+ * iii.onObserverAdded('tmux::on-changed', (obs) => {
196
+ * void obs
197
+ * .accepted()
198
+ * .then(() =>
199
+ * iii.call({
200
+ * observer: obs,
201
+ * payload: stateFor(obs.args),
202
+ * action: CallAction.Void(),
203
+ * }),
204
+ * )
205
+ * .catch(() => {
206
+ * // a rejected observer gets nothing
207
+ * })
208
+ * })
209
+ * ```
210
+ */
211
+ accepted(): Promise<void>;
212
+ /**
213
+ * Late rejection of an active observer (e.g. after a config reload). It
214
+ * stops receiving calls at once, its `onObserverRemoved` hooks run, and it
215
+ * stays rejected across reconnects until the engine adds it again.
216
+ */
217
+ reject(code: string, message: string): void;
218
+ }
219
+ /**
220
+ * Runs when an observer of a function is added, before the SDK acks it.
221
+ * Throw to reject the observer: an {@link ObserveRejection} sets the code,
222
+ * anything else is `OBSERVE_REJECTED`; after 30 s it is rejected with
223
+ * `OWNER_TIMEOUT`.
224
+ */
225
+ type AddedHook = (obs: Observer) => void | Promise<void>;
226
+ /** Runs once for every accepted observer when it is removed. An error it throws is logged. */
227
+ type RemovedHook = (obs: Observer) => void | Promise<void>;
228
+ /** A match key, or several: an observer wants a call when they share one. */
229
+ type Key = string | readonly string[];
230
+ /** `onObservationMatch` as a predicate: whether this observer wants this call. */
231
+ type MatchPredicate<I = unknown, O = unknown> = (obs: Observer, call: Call<I, O>) => boolean;
232
+ /**
233
+ * `onObservationMatch` as keys: an observer wants a call when they share a key,
234
+ * and the SDK keeps an index instead of asking every observer.
235
+ */
236
+ interface MatchKeys<I = unknown, O = unknown> {
237
+ /** What this observer listens for, computed once when it is accepted. */
238
+ observer: (obs: Observer) => Key;
239
+ /** What this call is. */
240
+ call: (call: Call<I, O>) => Key;
241
+ }
242
+ /**
243
+ * Which observers want each call of a function (`onObservationMatch`). By
244
+ * default every observer wants every call. A predicate is asked once per
245
+ * observation: for every call, once for each active observer (a throw
246
+ * counts as no match for that observer). Keys are computed
247
+ * once per observer, when it is accepted, and once per call. The observers'
248
+ * `on`, filters, policy and `deliver` still apply. Setting it to `null`
249
+ * removes it: every observer gets every call again.
250
+ */
251
+ type MatchHook<I = unknown, O = unknown> = MatchPredicate<I, O> | MatchKeys<I, O>;
252
+ /**
253
+ * Delivers each call of a function itself (`onObservationDeliver`): it receives
254
+ * the call and the observers that matched it (a snapshot taken when the call
255
+ * started), and what it returns (or throws) is what the caller gets back. A
256
+ * thrown {@link ObserveRejection}, or the error of a call it made, reaches the
257
+ * caller with its code; any other error as `invocation_failed`. iii delivers
258
+ * nothing for that function; the hook calls through observers
259
+ * (`worker.call({ observer, payload })`) and applies their filters with
260
+ * `obs.matches(call)`. It runs inside the function's invocation, so the calls
261
+ * it makes have that invocation as their caller.
262
+ *
263
+ * Browsers have no `AsyncLocalStorage`: the hook runs in the invocation's
264
+ * scope up to its first `await`. A call it makes after one still has the
265
+ * invocation as its caller while that invocation is the only one running on
266
+ * the page; to be sure, read `iii.currentInvocation()` first and re-enter it
267
+ * with `iii.withInvocation(inv, fn)`. A call through an observer is routed to
268
+ * the observer's target either way.
269
+ */
270
+ type DeliverHook<I = unknown, O = unknown, R = O> = (call: Call<I, O>, observers: readonly Observer[]) => R | Promise<R>;
271
+ /**
272
+ * The invocation the current code runs in, in every handler, remote or
273
+ * local (`iii.currentInvocation()`).
274
+ *
275
+ * Browsers have no `AsyncLocalStorage`, so the SDK knows it only while the
276
+ * handler runs synchronously: up to its first `await`. To keep it across an
277
+ * `await`, read it first and re-enter it with `iii.withInvocation(inv, fn)`.
278
+ */
279
+ interface InvocationContext {
280
+ function_id: string;
281
+ invocation_id: string;
282
+ caller?: CallerInfo;
283
+ /** Set when this invocation is the activation of an observer's target. */
284
+ activation?: {
285
+ observer_id: string;
286
+ activation_id?: string;
287
+ };
288
+ observe_depth: number;
289
+ /**
290
+ * The W3C `traceparent` the invocation arrived with (or was called with,
291
+ * for a local call). Calls made inside the handler forward it. Browser SDK
292
+ * only: there is no OpenTelemetry context to carry it.
293
+ */
294
+ traceparent?: string;
295
+ /** The W3C `baggage` that came with `traceparent`. */
296
+ baggage?: string;
297
+ }
298
+ //#endregion
1
299
  //#region src/iii-types.d.ts
2
300
  declare enum MessageType {
3
301
  RegisterFunction = "registerfunction",
4
302
  UnregisterFunction = "unregisterfunction",
5
303
  InvokeFunction = "invokefunction",
6
304
  InvocationResult = "invocationresult",
7
- RegisterTriggerType = "registertriggertype",
8
- RegisterTrigger = "registertrigger",
9
- UnregisterTrigger = "unregistertrigger",
10
- UnregisterTriggerType = "unregistertriggertype",
11
- TriggerRegistrationResult = "triggerregistrationresult",
12
305
  RegistrationRejected = "registrationrejected",
13
306
  WorkerRegistered = "workerregistered",
14
307
  Reattach = "reattach",
@@ -20,17 +313,17 @@ declare enum MessageType {
20
313
  ObserveResult = "observeresult",
21
314
  /** Engine → observing worker: an observer's lifecycle transition. */
22
315
  ObserverStateChanged = "observerstatechanged",
23
- /** Engine → owner: the `registerfunction` ack, with the function's full observer set. */
316
+ /** Engine → host: the `registerfunction` ack, with the function's full observer set. */
24
317
  FunctionRegistered = "functionregistered",
25
- /** Engine → owner: one observer attached to a function this connection hosts. */
318
+ /** Engine → host: one observer attached to a function this connection hosts. */
26
319
  ObserverAdded = "observeradded",
27
- /** Engine → owner: one observer detached. */
320
+ /** Engine → host: one observer detached. */
28
321
  ObserverRemoved = "observerremoved",
29
- /** Owner → engine: accept (or reject) an added observer. */
322
+ /** Host → engine: accept (or reject) an added observer. */
30
323
  ObserverAck = "observerack",
31
- /** Owner → engine: matched local invocations and `obs.emit` events, batched. */
324
+ /** Host → engine: the calls of its functions that observers matched, batched. */
32
325
  InvocationsObserved = "invocationsobserved",
33
- /** Owner → engine: periodic counts of local invocations and report drops. */
326
+ /** Host → engine: periodic counts of local invocations and report drops. */
34
327
  LocalInvocationStats = "localinvocationstats"
35
328
  }
36
329
  /**
@@ -38,36 +331,6 @@ declare enum MessageType {
38
331
  * know instead of failing the frame.
39
332
  */
40
333
  type OpenEnum<T extends string> = T | (string & {});
41
- /** `RegisterFunction.observe`: the part of the observe hooks that travels. Callbacks never do. */
42
- type ObserveDescriptorWire = {
43
- /** `auto` (default) or `owner`. */delivery?: OpenEnum<'auto' | 'owner'>; /** Owner only: validates the observers' `args` in the engine (`INVALID_ARGS`). */
44
- args_format?: RegisterFunctionFormat; /** Phase 5 shim: accept old `registertrigger { trigger_type }` for this type. */
45
- legacy_trigger_type?: string; /** Default `true`; `false` makes every `observe` on it fail with `NOT_OBSERVABLE`. */
46
- allow?: boolean;
47
- };
48
- /** @deprecated Trigger types are replaced by functions with an observe descriptor (`RegisterFunctionMessage.observe`). */
49
- type RegisterTriggerTypeMessage = {
50
- message_type: MessageType.RegisterTriggerType; /** Unique identifier for the trigger type (e.g. `state`, `durable:subscriber`). */
51
- id: string; /** Human-readable description of what this trigger type does. */
52
- description: string;
53
- };
54
- /** @deprecated Replaced by the `observe` message (`iii.observe`). */
55
- type RegisterTriggerMessage = {
56
- /** Wire discriminator; always `MessageType.RegisterTrigger`. */message_type: MessageType.RegisterTrigger; /** Unique trigger identifier, generated by the SDK during registration. */
57
- id: string; /** Identifier of the registered trigger type this trigger uses (e.g. `storage::object-created`, `http`). */
58
- type: string; /** ID of the function this trigger invokes when it fires. */
59
- function_id: string; /** Trigger-type-specific configuration, matching the shape the trigger type expects. */
60
- config: unknown;
61
- /**
62
- * Namespace the trigger's target function resolves in.
63
- *
64
- * Omitting it does not bind in the engine's default: `registerTrigger` fills
65
- * it from this worker's namespace, because the function a trigger names is
66
- * one this worker registered, and that landed in the worker's namespace. Name
67
- * another namespace, `default` included, to bind elsewhere.
68
- */
69
- namespace?: string;
70
- };
71
334
  type RegisterFunctionFormat = {
72
335
  /**
73
336
  * The name of the parameter
@@ -102,32 +365,56 @@ type RegisterFunctionMessage = {
102
365
  */
103
366
  id: string;
104
367
  /**
105
- * The description of the function
368
+ * Human-readable summary of the function, listed by discovery
369
+ * (`engine::functions::list`).
106
370
  */
107
371
  description?: string;
108
372
  /**
109
- * The request format of the function
373
+ * JSON Schema of the call's input.
110
374
  */
111
375
  request_format?: RegisterFunctionFormat;
112
376
  /**
113
- * The response format of the function
377
+ * JSON Schema of the handler's return value: what the function's observers
378
+ * observe.
114
379
  */
115
380
  response_format?: RegisterFunctionFormat;
381
+ /**
382
+ * Arbitrary metadata attached to the function, stored with it and listed by
383
+ * discovery (`engine::functions::list`). It is distinct from the per-call
384
+ * metadata a handler receives.
385
+ */
116
386
  metadata?: Record<string, unknown>;
117
387
  /**
118
- * The observe descriptor: how observers of this function are delivered.
119
- * Only these four fields travel; the hooks stay in the SDK.
388
+ * JSON Schema of the `args` an observer of this function passes. The
389
+ * engine validates every observer's args against it (`INVALID_ARGS`)
390
+ * before the added hooks run, and refuses a schema that is not valid
391
+ * (`INVALID_ARGS_FORMAT`). A function without it takes no args.
392
+ */
393
+ args_format?: RegisterFunctionFormat;
394
+ /**
395
+ * Only this worker may call the function: the engine answers a call from
396
+ * any other connection with `FORBIDDEN`, and refuses the function as an
397
+ * observer's target. Any worker may observe it, and its observers receive
398
+ * every call this worker makes. For event sources, whose calls from
399
+ * anywhere else would be forged events. This worker's own calls pass the
400
+ * input and the result by reference: the handler and hooks treat both as
401
+ * read-only. Default `false`; sent only when `true`.
402
+ */
403
+ private?: boolean;
404
+ /**
405
+ * `false`: nobody may observe the function (`NOT_OBSERVABLE`), for one
406
+ * whose payloads carry credentials. Default `true`; sent only when `false`.
120
407
  */
121
- observe?: ObserveDescriptorWire;
408
+ observable?: boolean;
122
409
  };
123
410
  /**
124
- * Routing action for {@link TriggerRequest}. Determines how the engine
411
+ * Routing action for {@link CallRequest}. Determines how the engine
125
412
  * handles the invocation.
126
413
  *
127
414
  * - `enqueue`: Routes through a named queue for async processing.
128
415
  * - `void`: Fire-and-forget, no response.
129
416
  */
130
- type TriggerAction = {
417
+ type CallAction = {
131
418
  type: 'enqueue';
132
419
  queue: string;
133
420
  } | {
@@ -160,9 +447,7 @@ type AuthResult = {
160
447
  */
161
448
  namespaces?: Record<string, string[]>; /** Additional function IDs to allow beyond the `expose_functions` config, in the `default` namespace only. Put per-namespace grants in `namespaces`. Defaults to `[]` if omitted. */
162
449
  allowed_functions?: string[]; /** Function IDs to deny even if they match `expose_functions`. Takes precedence over allowed. Defaults to `[]` if omitted. */
163
- forbidden_functions?: string[]; /** Trigger type IDs the worker may register triggers for. When omitted, all types are allowed. */
164
- allowed_trigger_types?: string[]; /** Whether the worker may register new trigger types. Defaults to `false` if omitted. */
165
- allow_trigger_type_registration?: boolean; /** Whether the worker may register new functions. Defaults to `true` if omitted. */
450
+ forbidden_functions?: string[]; /** Whether the worker may register new functions. Defaults to `true` if omitted. */
166
451
  allow_function_registration?: boolean; /** Arbitrary context forwarded to the middleware function on every invocation. Defaults to `{}` if omitted. */
167
452
  context?: Record<string, unknown>; /** Optional prefix applied to all function IDs registered by this worker. */
168
453
  function_registration_prefix?: string;
@@ -175,7 +460,7 @@ type AuthResult = {
175
460
  type MiddlewareFunctionInput = {
176
461
  /** ID of the function being invoked. */function_id: string; /** Payload sent by the caller. */
177
462
  payload: Record<string, unknown>; /** Routing action, if any. */
178
- action?: TriggerAction; /** Auth context returned by the auth function for this session. */
463
+ action?: CallAction; /** Auth context returned by the auth function for this session. */
179
464
  context: Record<string, unknown>;
180
465
  /**
181
466
  * Target namespace the invoke addressed; forward the call here to stay in the
@@ -183,56 +468,6 @@ type MiddlewareFunctionInput = {
183
468
  */
184
469
  namespace?: string;
185
470
  };
186
- /**
187
- * Input passed to the `on_trigger_type_registration_function_id` hook
188
- * when a worker attempts to register a new trigger type through the RBAC port.
189
- * Return an {@link OnTriggerTypeRegistrationResult} with the (possibly mapped)
190
- * fields, or throw to deny the registration.
191
- */
192
- type OnTriggerTypeRegistrationInput = {
193
- /** ID of the trigger type being registered. */trigger_type_id: string; /** Human-readable description of the trigger type. */
194
- description: string; /** Auth context from `AuthResult.context` for this session. */
195
- context: Record<string, unknown>;
196
- };
197
- /**
198
- * Result returned from the `on_trigger_type_registration_function_id` hook.
199
- * All fields are optional; omitted fields keep the original value from the
200
- * registration request.
201
- */
202
- type OnTriggerTypeRegistrationResult = {
203
- /** Mapped trigger type ID. */trigger_type_id?: string; /** Mapped description. */
204
- description?: string;
205
- };
206
- /**
207
- * Input passed to the `on_trigger_registration_function_id` hook
208
- * when a worker attempts to register a trigger through the RBAC port.
209
- * Return an {@link OnTriggerRegistrationResult} with the (possibly mapped)
210
- * fields, or throw to deny the registration.
211
- */
212
- type OnTriggerRegistrationInput = {
213
- /** ID of the trigger being registered. */trigger_id: string; /** Trigger type identifier. */
214
- trigger_type: string; /** ID of the function this trigger is bound to. */
215
- function_id: string; /** Trigger-specific configuration. */
216
- config: unknown;
217
- /**
218
- * Namespace the trigger's target resolves in (explicit, or `default` when
219
- * absent). The same id can exist in several namespaces, so the hook needs this
220
- * to authorize per target namespace.
221
- */
222
- namespace?: string; /** Auth context from `AuthResult.context` for this session. */
223
- context: Record<string, unknown>;
224
- };
225
- /**
226
- * Result returned from the `on_trigger_registration_function_id` hook.
227
- * All fields are optional; omitted fields keep the original value from the
228
- * registration request.
229
- */
230
- type OnTriggerRegistrationResult = {
231
- /** Mapped trigger ID. */trigger_id?: string; /** Mapped trigger type. */
232
- trigger_type?: string; /** Mapped function ID. */
233
- function_id?: string; /** Mapped trigger configuration. */
234
- config?: unknown;
235
- };
236
471
  /**
237
472
  * Input passed to the `on_function_registration_function_id` hook
238
473
  * when a worker attempts to register a function through the RBAC port.
@@ -247,7 +482,10 @@ type OnFunctionRegistrationInput = {
247
482
  * Namespace the function registers in. The same id can exist in several
248
483
  * namespaces, so the hook needs this to authorize per namespace.
249
484
  */
250
- namespace?: string; /** Auth context from `AuthResult.context` for this session. */
485
+ namespace?: string; /** Only the registering worker may call the function; always sent. */
486
+ private: boolean; /** `false`: nobody may observe the function; always sent. */
487
+ observable: boolean; /** JSON Schema of the args its observers pass; sent when the registration sets it. */
488
+ args_format?: Record<string, unknown>; /** Auth context from `AuthResult.context` for this session. */
251
489
  context: Record<string, unknown>;
252
490
  };
253
491
  /**
@@ -258,29 +496,34 @@ type OnFunctionRegistrationInput = {
258
496
  type OnFunctionRegistrationResult = {
259
497
  /** Mapped function ID. */function_id?: string; /** Mapped description. */
260
498
  description?: string; /** Mapped metadata. */
261
- metadata?: Record<string, unknown>;
499
+ metadata?: Record<string, unknown>; /** Replaces the registration's `private`. */
500
+ private?: boolean; /** Replaces the registration's `observable`. */
501
+ observable?: boolean; /** Replaces the registration's `args_format`. */
502
+ args_format?: Record<string, unknown>;
262
503
  };
263
504
  /**
264
- * Result returned when a function is invoked with `TriggerAction.Enqueue`.
505
+ * Result returned when a function is called with `CallAction.Enqueue`.
265
506
  */
266
507
  type EnqueueResult = {
267
508
  /** Unique receipt ID for the enqueued message. */messageReceiptId: string;
268
509
  };
269
510
  /**
270
- * Request object passed to {@link ISdk.trigger}.
511
+ * Request object passed to {@link ISdk.call}: a function by id, or the target
512
+ * of an observer.
271
513
  *
272
514
  * @typeParam TInput - Type of the payload.
273
515
  */
274
- type TriggerRequest<TInput = unknown> = {
275
- /** ID of the function to invoke. */function_id: string; /** Input data passed to the function. */
276
- payload: TInput; /** Sets how the trigger is routed. Omit for a synchronous request/response. Specify for a specific routing scheme (e.g. `TriggerAction.Enqueue()`, `TriggerAction.Void()`). */
277
- action?: TriggerAction; /** Override the default invocation timeout, in milliseconds. */
516
+ type CallRequest<TInput = unknown> = {
517
+ /** ID of the function to invoke. */function_id: string;
518
+ observer?: never; /** Input data passed to the function. */
519
+ payload: TInput; /** Sets how the call is routed. Omit for a synchronous request/response. Specify for a specific routing scheme (e.g. `CallAction.Enqueue()`, `CallAction.Void()`). */
520
+ action?: CallAction; /** Override the default invocation timeout, in milliseconds. */
278
521
  timeoutMs?: number; /** Namespace to route this invocation to. Omit to inherit this worker's; say `default` to reach the engine's from a namespaced worker. */
279
522
  namespace?: string;
280
523
  /**
281
- * Per-invocation metadata (any JSON). Travels beside the payload: the
524
+ * Per-invocation metadata (any JSON value). Travels beside the payload: the
282
525
  * handler receives it as its second argument, and observer filters read it
283
- * as `metadata.*`.
526
+ * as `metadata.*`. `null` is the same as no metadata.
284
527
  */
285
528
  metadata?: unknown;
286
529
  /**
@@ -298,7 +541,26 @@ type TriggerRequest<TInput = unknown> = {
298
541
  * engine. Tests use it, and so do callers that rely on engine-side effects.
299
542
  */
300
543
  dispatch?: 'auto' | 'remote';
544
+ } | {
545
+ /**
546
+ * An observer of a function this worker hosts: the call runs the
547
+ * observer's target, with the observer's policy, metadata and loop
548
+ * guard. Only the host of the observed function may call through it
549
+ * (`NOT_FUNCTION_OWNER`).
550
+ */
551
+ observer: Observer;
552
+ function_id?: never; /** Input data passed to the target, as given (the observer's filters are not applied). */
553
+ payload: TInput; /** `CallAction.Void()` for fire-and-forget. Omit for a synchronous request/response. */
554
+ action?: CallAction; /** Override the default invocation timeout, in milliseconds. */
555
+ timeoutMs?: number;
556
+ /**
557
+ * A call through an observer takes no metadata: its target receives the
558
+ * observer's registration metadata. `call` refuses one that names it.
559
+ */
560
+ metadata?: never;
301
561
  };
562
+ /** @deprecated Use {@link CallRequest}, the same type. */
563
+ type TriggerRequest<TInput = unknown> = CallRequest<TInput>;
302
564
  /**
303
565
  * Serializable reference to one end of a streaming channel. Can be included
304
566
  * in invocation payloads to pass channel endpoints between workers.
@@ -381,6 +643,7 @@ declare class ChannelWriter {
381
643
  declare class ChannelReader {
382
644
  private ws;
383
645
  private connected;
646
+ private closedByCaller;
384
647
  private readonly messageCallbacks;
385
648
  private readonly binaryCallbacks;
386
649
  private readonly url;
@@ -390,7 +653,12 @@ declare class ChannelReader {
390
653
  onMessage(callback: (msg: string) => void): void;
391
654
  /** Register a callback to receive binary data from the channel. */
392
655
  onBinary(callback: (data: Uint8Array) => void): void;
393
- /** Read all binary data from the channel until it closes. */
656
+ /**
657
+ * Read all binary data from the channel until it closes.
658
+ *
659
+ * Rejects with an `Error` carrying the close `code` and `reason` when the
660
+ * channel ends abnormally (the writer aborted or the connection was lost).
661
+ */
394
662
  readAll(): Promise<Uint8Array>;
395
663
  /** Close the channel reader. */
396
664
  close(): void;
@@ -426,14 +694,13 @@ type InvocationErrorInit = {
426
694
  };
427
695
  /**
428
696
  * An error the SDK raises itself for an invocation, with a machine-readable
429
- * `code`: observe delivery errors (`NOT_OWNER_DELIVERED`,
430
- * `OBSERVER_NOT_ACTIVE`, `FILTERS_NOT_MATCHED`) and an invalid observe
431
- * descriptor (`INVALID_OBSERVE_DESCRIPTOR`). Mirrors the Node SDK.
697
+ * `code`: `LOCAL_DEPTH_EXCEEDED` (a local call nested too deep while the
698
+ * socket is closed) and `payload_too_large`. Mirrors the Node SDK.
432
699
  *
433
- * A call the engine answers with an error still rejects with the engine's
434
- * error body (`{ code, message, stacktrace? }`), as in earlier releases, and
435
- * so does a locally dispatched call whose handler throws: both paths reject
436
- * with the same value.
700
+ * A call the engine answers with an error rejects with the engine's error
701
+ * body (`{ code, message, stacktrace? }`), and so does a locally dispatched
702
+ * call whose handler or deliver hook throws: both paths reject with the same
703
+ * value.
437
704
  */
438
705
  declare class InvocationError extends Error {
439
706
  readonly code: string;
@@ -449,11 +716,11 @@ declare class InvocationError extends Error {
449
716
  *
450
717
  * @example
451
718
  * ```typescript
452
- * onObserverAdded(obs) {
719
+ * iii.onObserverAdded('cron::on-tick', (obs) => {
453
720
  * if (!isValidCron(obs.args.expression)) {
454
721
  * throw new ObserveRejection('INVALID_CRON_EXPRESSION', 'invalid day-of-week field')
455
722
  * }
456
- * }
723
+ * })
457
724
  * ```
458
725
  */
459
726
  declare class ObserveRejection extends Error {
@@ -465,29 +732,26 @@ declare class ObserveRejection extends Error {
465
732
  /**
466
733
  * Constants for the III module.
467
734
  */
468
- /**
469
- * Engine function paths for internal operations.
470
- *
471
- * Naming note: `LIST_TRIGGERS` / `INFO_TRIGGERS` cover trigger TYPES
472
- * (templates). `LIST_REGISTERED_TRIGGERS` / `INFO_REGISTERED_TRIGGERS`
473
- * cover trigger INSTANCES (subscriber rows). The old
474
- * `engine::trigger-types::list` builtin has been removed and is now
475
- * served by `engine::triggers::list`.
476
- */
735
+ /** Engine function paths for internal operations. */
477
736
  declare const EngineFunctions: {
478
737
  readonly LIST_FUNCTIONS: "engine::functions::list";
479
738
  readonly INFO_FUNCTIONS: "engine::functions::info";
480
739
  readonly LIST_WORKERS: "engine::workers::list";
481
740
  readonly INFO_WORKERS: "engine::workers::info";
482
- readonly LIST_TRIGGERS: "engine::triggers::list";
483
- readonly INFO_TRIGGERS: "engine::triggers::info";
484
- readonly LIST_REGISTERED_TRIGGERS: "engine::registered-triggers::list";
485
- readonly INFO_REGISTERED_TRIGGERS: "engine::registered-triggers::info";
486
741
  readonly REGISTER_WORKER: "engine::workers::register";
487
742
  };
488
- /** Engine trigger types */
489
- declare const EngineTriggers: {
490
- readonly FUNCTIONS_AVAILABLE: "engine::functions-available";
743
+ /**
744
+ * The event sources the engine hosts: private functions whose handler
745
+ * returns the event, observed with `iii.observe(EngineSources.X, target)`.
746
+ * None takes args; filter on the event (`input`) instead.
747
+ */
748
+ declare const EngineSources: {
749
+ /** A function was registered or unregistered; each row carries `observer_count`. */readonly FUNCTIONS_CHANGED: "engine::on-functions-changed"; /** A worker connected or left. */
750
+ readonly WORKERS_CHANGED: "engine::on-workers-changed"; /** An observer changed state: `{ observer_id, function_id, target, state, reason? }`. */
751
+ readonly OBSERVERS_CHANGED: "engine::on-observers-changed"; /** A log record. */
752
+ readonly LOG: "observability::on-log"; /** A finished span. */
753
+ readonly SPAN: "observability::on-span"; /** The engine's configuration was reloaded. */
754
+ readonly CONFIGURATION_UPDATED: "configuration::on-updated";
491
755
  };
492
756
  /** Connection state for the III WebSocket */
493
757
  type IIIConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'failed';
@@ -505,306 +769,12 @@ interface IIIReconnectionConfig {
505
769
  maxRetries: number;
506
770
  }
507
771
  //#endregion
508
- //#region src/observe-types.d.ts
509
- /** What an observer ships to its target. Default `['input', 'output', 'caller']`. */
510
- type Capture = 'input' | 'output' | 'error' | 'caller' | 'metadata';
772
+ //#region src/types.d.ts
511
773
  /**
512
- * An observer's lifecycle: `pending` (no owner yet, waiting for the owner's
513
- * ack, or no target yet) → `active` or `error`; `suspended` while its worker
514
- * or target is away; `disposed` at the end.
515
- */
516
- type ObserverState = 'pending' | 'active' | 'suspended' | 'error' | 'disposed';
517
- /**
518
- * A declarative filter over `input`, `output`, `error`, `caller` and
519
- * `metadata`, with explicit operators only:
520
- * `{ 'input.amount': { $gte: 500 } }`. See the filter language reference.
521
- */
522
- type Filter = Record<string, unknown>;
523
- /** The right side of `iii.observe`: a registered function. */
524
- type Target = string | {
525
- function_id: string;
526
- namespace?: string;
527
- };
528
- /** A state reason or an error: a machine-readable code and a message. */
529
- type ObserveReason = {
530
- code: string;
531
- message: string;
532
- };
533
- /**
534
- * Who started an invocation: the worker (`worker_id` / `worker_name`, stamped
535
- * by the engine), and the function and invocation the call was made from.
536
- */
537
- interface Caller {
538
- /** Absent on activations, whose caller is the engine (`worker_name: 'iii-engine'`). */
539
- worker_id?: string;
540
- worker_name?: string;
541
- /** The handler the call was made from; absent for top-level calls. */
542
- function_id?: string;
543
- invocation_id?: string;
544
- /** The caller of that handler, one level only. */
545
- parent?: Omit<Caller, 'parent'>;
546
- }
547
- /**
548
- * A caller as the SDK knows it: every field may be missing (a top-level call
549
- * has no function; a call made before `WorkerRegistered` has no worker id).
550
- */
551
- type CallerInfo = Partial<Omit<Caller, 'parent'>> & {
552
- parent?: Partial<Omit<Caller, 'parent'>>;
553
- };
554
- /**
555
- * What the target of an auto observer (or of `obs.emit`) receives with
556
- * `deliver: 'envelope'` (the default). Fields not in the observer's
557
- * `capture` are absent.
558
- */
559
- interface Observed<I = unknown, O = unknown> {
560
- observer_id: string;
561
- activation_id: string;
562
- function_id: string;
563
- namespace: string;
564
- invocation_id: string;
565
- status: 'success' | 'error';
566
- input?: I;
567
- output?: O;
568
- error?: {
569
- code: string;
570
- message: string;
571
- };
572
- caller?: Caller;
573
- metadata?: Record<string, unknown>;
574
- started_at_ms: number;
575
- duration_ms: number;
576
- }
577
- /** The left side of `iii.observe`: what is observed. */
578
- interface ObserveSource {
579
- /** The observed function. */
580
- function_id: string;
581
- /** Defaults to this worker's namespace (`engine::*` resolves to `default`). */
582
- namespace?: string;
583
- /** Owner-delivered functions only: for the owner; validated against its `args_format`. */
584
- args?: Record<string, unknown>;
585
- /** Which events reach the target; `{}` (or absent) = every event. */
586
- filters?: Filter;
587
- /** Auto only; default `'success'`. */
588
- on?: 'success' | 'error' | 'complete';
589
- /** Auto and `obs.emit`; default `['input', 'output', 'caller']`. */
590
- capture?: Capture[];
591
- /** Auto and `obs.emit`; default `'envelope'`. */
592
- deliver?: 'envelope' | 'input' | 'output';
593
- }
594
- /** The observer itself: its id, policy and metadata. */
595
- interface ObserverOptions {
596
- /** Default: a random UUID, stable across replays. */
597
- id?: string;
598
- /** The observer is disposed after this many activations (`MAX_FIRES`). Default: unlimited. */
599
- max_fires?: number;
600
- /** The observer is disposed this many milliseconds after it is created (`EXPIRED`). Default: never. */
601
- expires_in_ms?: number;
602
- /**
603
- * Activations running at once; further ones queue, then drop as `OVERFLOW`.
604
- * Default: the engine's `observers.default_max_in_flight` (64).
605
- */
606
- max_in_flight?: number;
607
- /** Delivered as the metadata sidecar of every activation. */
608
- metadata?: Record<string, unknown>;
609
- }
610
- /** What `iii.observe` returns, synchronously. */
611
- interface ObserverHandle {
612
- readonly id: string;
613
- readonly state: ObserverState;
614
- /** Why the observer is in its state (`error`, `suspended`, `disposed`). */
615
- readonly reason?: ObserveReason;
616
- /**
617
- * Resolves when the observer is `active`; rejects with an
618
- * {@link ObserveRejection} carrying the code when it turns `error` or
619
- * `disposed` first.
620
- */
621
- ready(): Promise<void>;
622
- /**
623
- * Calls `listener` on every state change, in order; returns the
624
- * unsubscribe function. Listeners are called asynchronously (never on the
625
- * connection's read path), so they may call the client.
626
- */
627
- onStateChange(listener: (state: ObserverState, reason?: ObserveReason) => void): () => void;
628
- /** Removes the observer (`unobserve`). It is not replayed on reconnect. */
629
- dispose(): Promise<void>;
630
- }
631
- /** The document an observer's filters read (filters.md §1). */
632
- type ObserveDoc = {
633
- input?: unknown;
634
- output?: unknown;
635
- error?: unknown;
636
- caller?: CallerInfo;
637
- metadata?: unknown;
638
- };
639
- /**
640
- * An observer as the function's owner sees it (`onObserverAdded`,
641
- * `FunctionRef.observers()`): its args, filters, target, capture and `on`.
642
- * Never its metadata, policy or the observing worker.
643
- */
644
- interface Observer {
645
- readonly id: string;
646
- /** The observed function (the one this worker hosts). */
647
- readonly function_id: string;
648
- /** The observer's args, validated against `args_format` by the engine. */
649
- readonly args: Record<string, unknown>;
650
- /** The observer's filters, normalized; the SDK applies them in `emit` / `call`. */
651
- readonly filters: Filter;
652
- /** The target function id. */
653
- readonly target: string;
654
- readonly capture: Capture[];
655
- /** Auto only. */
656
- readonly on: 'success' | 'error' | 'complete';
657
- /** Set when the engine's legacy shim created the observer from an old `registerTrigger`. */
658
- readonly legacy?: {
659
- trigger_type: string;
660
- config: unknown;
661
- };
662
- /** Evaluates the observer's filters on a document. */
663
- matches(doc: ObserveDoc): boolean;
664
- /**
665
- * Owner delivery, fire-and-forget: hands `event` to this observer. Returns
666
- * `false` and sends nothing when its filters reject the event or the
667
- * observer is no longer active (removed or rejected meanwhile). Throws
668
- * `NOT_OWNER_DELIVERED` on an auto function.
669
- */
670
- emit(event: unknown): boolean;
671
- /**
672
- * Owner delivery, request/response: invokes the target with `payload` and
673
- * resolves with its result. Rejects with `FILTERS_NOT_MATCHED` (nothing is
674
- * sent) when the filters reject the payload, and with `OBSERVER_NOT_ACTIVE`
675
- * when the observer is no longer active.
676
- */
677
- call<R = unknown>(payload: unknown, opts?: {
678
- timeoutMs?: number;
679
- metadata?: never;
680
- }): Promise<R>;
681
- /**
682
- * Late rejection of an active observer (e.g. after a config reload). It
683
- * stops receiving events at once, and stays rejected across reconnects
684
- * until the engine adds it again.
685
- */
686
- reject(code: string, message: string): void;
687
- }
688
- /**
689
- * The `observe` option of `registerFunction`: how the function's observers
690
- * are delivered, and the callbacks that run when one is added or removed.
691
- *
692
- * The callbacks of one function run one at a time, in revision order, with
693
- * one exception: a callback still running after 30 s is treated as failed
694
- * (`OWNER_TIMEOUT`) and the next one starts, so a hung callback cannot stall
695
- * its function forever. It may then overlap with the callbacks after it, and
696
- * if a timed-out `onObserverAdded` completes later, `onObserverRemoved` runs
697
- * for that observer.
698
- */
699
- interface ObserveHooks {
700
- /**
701
- * `auto` (default): every invocation is offered to every observer.
702
- * `owner`: the handler hands each event to the observers it belongs to,
703
- * with `obs.emit` / `obs.call`.
704
- */
705
- delivery?: 'auto' | 'owner';
706
- /** Owner only: JSON Schema of the observers' `args` (the engine answers `INVALID_ARGS`). */
707
- args_format?: RegisterFunctionFormat;
708
- /** Accept old `registerTrigger({ type })` calls for this trigger type. */
709
- legacy_trigger_type?: string;
710
- /** Default `true`; `false` refuses every observer (`NOT_OBSERVABLE`). */
711
- allow?: boolean;
712
- /**
713
- * Runs once per added observer, before the SDK acks it. Throw to reject it
714
- * (an {@link ObserveRejection} sets the code, anything else is
715
- * `OBSERVE_REJECTED`); after 30 s it is rejected with `OWNER_TIMEOUT`.
716
- */
717
- onObserverAdded?(obs: Observer): void | Promise<void>;
718
- /** Runs once per removed observer. Cannot fail: errors are logged. */
719
- onObserverRemoved?(obs: Observer): void | Promise<void>;
720
- }
721
- /**
722
- * The invocation the current code runs in, in every handler, remote or
723
- * local (`iii.currentInvocation()`).
724
- *
725
- * Browsers have no `AsyncLocalStorage`, so the SDK knows it only while the
726
- * handler runs synchronously: up to its first `await`. To keep it across an
727
- * `await`, read it first and re-enter it with `iii.withInvocation(inv, fn)`.
728
- */
729
- interface InvocationContext {
730
- function_id: string;
731
- invocation_id: string;
732
- caller?: CallerInfo;
733
- /** Set when this invocation is the activation of an observer's target. */
734
- activation?: {
735
- observer_id: string;
736
- activation_id?: string;
737
- };
738
- observe_depth: number;
739
- /**
740
- * The W3C `traceparent` the invocation arrived with (or was triggered with,
741
- * for a local call). Calls made inside the handler forward it. Browser SDK
742
- * only: there is no OpenTelemetry context to carry it.
743
- */
744
- traceparent?: string;
745
- /** The W3C `baggage` that came with `traceparent`. */
746
- baggage?: string;
747
- }
748
- //#endregion
749
- //#region src/triggers.d.ts
750
- /**
751
- * Configuration passed to a trigger handler when a trigger instance is
752
- * registered or unregistered.
753
- *
754
- * @deprecated Replaced by the `Observer` an `onObserverAdded` hook
755
- * receives (`{ id, args, filters, target }`). Migration guide:
756
- * https://iii.dev/docs/upgrading/from-0-24-x
757
- *
758
- * @typeParam TConfig - Type of the trigger-specific configuration.
759
- */
760
- type TriggerConfig<TConfig> = {
761
- /** Trigger instance ID. */id: string; /** Function to invoke when the trigger fires. */
762
- function_id: string; /** Trigger-specific configuration. */
763
- config: TConfig;
764
- /**
765
- * Namespace the trigger's target `function_id` resolves in. A provider that
766
- * stores this config and later fires the target must pass this namespace, or
767
- * it fires in `default`.
768
- *
769
- * Omitted, it is filled in with the registering worker's namespace. A trigger
770
- * names a function, and a worker's functions land in the worker's namespace,
771
- * so defaulting anywhere else registers a trigger that resolves nothing. Name
772
- * another namespace, `default` included, to target one.
773
- */
774
- namespace?: string;
775
- };
776
- /**
777
- * Handler interface for custom trigger types. Passed to
778
- * `ISdk.registerTriggerType`.
779
- *
780
- * @deprecated Replaced by `ObserveHooks` (`onObserverAdded` /
781
- * `onObserverRemoved`) on `registerFunction`. Migration guide:
782
- * https://iii.dev/docs/upgrading/from-0-24-x
783
- *
784
- * @typeParam TConfig - Type of the trigger-specific configuration.
785
- *
786
- * @example
787
- * ```typescript
788
- * const handler: TriggerHandler<{ interval: number }> = {
789
- * async registerTrigger({ id, function_id, config }) {
790
- * // Set up periodic invocation
791
- * },
792
- * async unregisterTrigger({ id, function_id, config }) {
793
- * // Clean up
794
- * },
795
- * }
796
- * ```
797
- */
798
- type TriggerHandler<TConfig> = {
799
- /** Called when a trigger instance is registered. */registerTrigger(config: TriggerConfig<TConfig>): Promise<void>; /** Called when a trigger instance is unregistered. */
800
- unregisterTrigger(config: TriggerConfig<TConfig>): Promise<void>;
801
- };
802
- //#endregion
803
- //#region src/types.d.ts
804
- /**
805
- * Async function handler for a registered function. Receives the invocation
806
- * payload and its metadata (`TriggerRequest.metadata` of the call, or an
807
- * observer's metadata sidecar on an activation) and returns the result.
774
+ * Handler of a registered function. Receives the invocation payload and its
775
+ * metadata (`CallRequest.metadata` of the call, or an observer's metadata
776
+ * sidecar on an activation) and returns the result (or a promise of it). The
777
+ * return value is what the function's observers observe.
808
778
  *
809
779
  * @typeParam TInput - Type of the invocation payload.
810
780
  * @typeParam TOutput - Type of the return value.
@@ -815,22 +785,15 @@ type TriggerHandler<TConfig> = {
815
785
  * async (data) => ({ message: `Hello, ${data.name}!` })
816
786
  * ```
817
787
  */
818
- type RemoteFunctionHandler<TInput = any, TOutput = any> = (data: TInput, metadata?: unknown) => Promise<TOutput>;
819
- /** @deprecated Use `iii.observe(source, target, options)` and its {@link ObserveSource}. */
820
- type RegisterTriggerInput = Omit<RegisterTriggerMessage, 'message_type' | 'id'>;
788
+ type RemoteFunctionHandler<TInput = any, TOutput = any> = (data: TInput, metadata?: unknown) => TOutput | Promise<TOutput>;
821
789
  type RegisterFunctionInput = Omit<RegisterFunctionMessage, 'message_type'>;
822
790
  /**
823
- * Options of {@link ISdk.registerFunction}: description, request/response
824
- * formats, metadata, and the observe hooks.
791
+ * Options of {@link ISdk.registerFunction}: what describes the function to
792
+ * the engine (description, formats, metadata, `args_format`, `private`,
793
+ * `observable`), and what the SDK does with it (`localDispatch`).
794
+ * What the worker does when the function is observed is set with hooks.
825
795
  */
826
- type RegisterFunctionOptions = Omit<RegisterFunctionMessage, 'message_type' | 'id' | 'observe'> & {
827
- /**
828
- * Makes the function observable on its own terms: owner delivery
829
- * (`delivery: 'owner'`, `args_format`), and callbacks when an observer is
830
- * added or removed. Without it the function is still observable (auto
831
- * delivery, no args).
832
- */
833
- observe?: ObserveHooks;
796
+ type RegisterFunctionOptions = Omit<RegisterFunctionMessage, 'message_type' | 'id'> & {
834
797
  /**
835
798
  * Calls this worker makes to its own function run in-process once the
836
799
  * engine confirmed it (default `true`). Set `false` for a handler that must
@@ -838,40 +801,36 @@ type RegisterFunctionOptions = Omit<RegisterFunctionMessage, 'message_type' | 'i
838
801
  */
839
802
  localDispatch?: boolean;
840
803
  };
841
- /** @deprecated Register a function with an observe descriptor instead. */
842
- type RegisterTriggerTypeInput = Omit<RegisterTriggerTypeMessage, 'message_type'>;
843
804
  interface ISdk {
844
805
  /**
845
- * Registers a new trigger. A trigger is a way to invoke a function when a certain event occurs.
806
+ * Registers a new function with a local handler that runs in the browser
807
+ * session. HTTP invocation configs are a Node.js SDK feature. The handler's
808
+ * return value is what the function's observers observe; an event source's
809
+ * handler returns the event it is called with.
846
810
  *
847
- * @deprecated Use {@link ISdk.observe} instead: `iii.observe({ function_id, args, filters }, target, { metadata })`.
848
- * Logs a warning once per page. The http, cron, queue, state, stream, pubsub and database workers
849
- * still publish trigger types: keep using `registerTrigger` for them until they ship source functions.
850
- * Migration guide: https://iii.dev/docs/upgrading/from-0-24-x
851
- * <!-- docs:expand-params -->
852
- * @param trigger - The trigger to register
853
- * @returns A trigger object that can be used to unregister the trigger
811
+ * Every call of the function, local or routed, runs the handler and then
812
+ * goes to the observers that want it (`onObservationMatch`; by default all of
813
+ * them): the function's `onObservationDeliver` hook delivers it, or iii does,
814
+ * to those whose `on` and filters match. iii evaluates `on` and filters
815
+ * where the call is: the engine for a call it routes to this worker, and
816
+ * the SDK for a call this worker makes to its own function in-process,
817
+ * through an index of the filters' equality conditions. What the worker
818
+ * does when the function is observed is set with the hooks (`onObserverAdded`,
819
+ * `onObserverRemoved`, `onObservationMatch`, `onObservationDeliver`), by id or on
820
+ * the returned {@link FunctionRef}. The SDK acks no observer before this
821
+ * call returns, so a hook set by id before it, chained on its result, or
822
+ * set later in the same synchronous block runs for every observer.
854
823
  *
855
- * @example
856
- * ```typescript
857
- * const trigger = worker.registerTrigger({
858
- * type: 'cron',
859
- * function_id: 'my-service::process-batch',
860
- * config: { expression: '0 *\/5 * * * * *' },
861
- * })
824
+ * A function that sets `args_format`, `private: true`, `observable: false`,
825
+ * an `onObservationMatch` hook or an `onObservationDeliver` hook needs an engine
826
+ * with `observe.v2`: it is registered once the connection's engine
827
+ * advertised it, and against an older engine it stays unregistered (logged
828
+ * once, `UNSUPPORTED`).
862
829
  *
863
- * // Later, remove the trigger
864
- * trigger.unregister()
865
- * ```
866
- */
867
- registerTrigger(trigger: RegisterTriggerInput): Trigger;
868
- /**
869
- * Registers a new function with a local async handler that runs in the
870
- * browser session. HTTP invocation configs are a Node.js SDK feature.
871
830
  * @param functionId - Unique function identifier
872
- * @param handler - Async handler executed when the function is invoked
873
- * @param options - Optional function registration options (description, request/response formats, metadata)
874
- * @returns A handle that can be used to unregister the function
831
+ * @param handler - Handler executed when the function is invoked
832
+ * @param options - Optional {@link RegisterFunctionOptions}: description, request/response formats, metadata, `args_format`, `private`, `observable`, `localDispatch`
833
+ * @returns A {@link FunctionRef}: the hook methods with the id filled in, and `unregister()`
875
834
  *
876
835
  * @example
877
836
  * ```typescript
@@ -882,22 +841,30 @@ interface ISdk {
882
841
  * { description: 'Returns a greeting' },
883
842
  * )
884
843
  *
844
+ * // An event source: observed by everyone, called only by this page, set up
845
+ * // for each observer by its args
846
+ * worker
847
+ * .registerFunction('ui::on-click', (click: Click) => click, { args_format: ClickArgs, private: true })
848
+ * .onObserverAdded((obs) => targets.retain(obs.args.selector as string))
849
+ * .onObserverRemoved((obs) => targets.release(obs.args.selector as string))
850
+ *
885
851
  * // Later, remove the function
886
852
  * ref.unregister()
887
853
  * ```
888
854
  */
889
- registerFunction(functionId: string, handler: RemoteFunctionHandler, options?: RegisterFunctionOptions): FunctionRef;
855
+ registerFunction<I = any, O = any>(functionId: string, handler: RemoteFunctionHandler<I, O>, options?: RegisterFunctionOptions): FunctionRef<I, O>;
890
856
  /**
891
- * Invokes a function using a request object.
857
+ * Invokes a function: by id, or the target of an observer of a function
858
+ * this worker hosts (`{ observer, payload }`).
892
859
  * <!-- docs:expand-params -->
893
860
  *
894
- * @param request - The trigger request containing function_id, payload, and optional action/timeout
861
+ * @param request - The call request: `function_id` (or `observer`), `payload`, and optional action/timeout
895
862
  * @returns The result of the function
896
863
  *
897
864
  * @example
898
865
  * ```typescript
899
866
  * // Synchronous invocation
900
- * const result = await worker.trigger<{ name: string }, { message: string }>({
867
+ * const result = await worker.call<{ name: string }, { message: string }>({
901
868
  * function_id: 'greet',
902
869
  * payload: { name: 'World' },
903
870
  * timeoutMs: 5000,
@@ -905,30 +872,43 @@ interface ISdk {
905
872
  * console.log(result.message) // "Hello, World!"
906
873
  *
907
874
  * // Fire-and-forget
908
- * await worker.trigger({
875
+ * await worker.call({
909
876
  * function_id: 'send-email',
910
877
  * payload: { to: 'user@example.com' },
911
- * action: TriggerAction.Void(),
878
+ * action: CallAction.Void(),
912
879
  * })
913
880
  *
914
881
  * // Enqueue for async processing (the queue must be declared in the
915
882
  * // queue worker's queue_configs)
916
- * const receipt = await worker.trigger({
883
+ * const receipt = await worker.call({
917
884
  * function_id: 'process-order',
918
885
  * payload: { orderId: '123' },
919
- * action: TriggerAction.Enqueue({ queue: 'orders' }),
886
+ * action: CallAction.Enqueue({ queue: 'orders' }),
920
887
  * })
888
+ *
889
+ * // Through an observer, in the function's deliver hook: runs its target,
890
+ * // with its policy and metadata
891
+ * const response = await worker.call({ observer: route.obs, payload: request })
921
892
  * ```
922
893
  */
923
- trigger<TInput = unknown, TOutput = any>(request: TriggerRequest<TInput>): Promise<TOutput>;
894
+ call<TInput = unknown, TOutput = any>(request: CallRequest<TInput>): Promise<TOutput>;
895
+ /**
896
+ * Invokes a function using a request object.
897
+ *
898
+ * @deprecated Use {@link ISdk.call}, the same function.
899
+ */
900
+ trigger<TInput = unknown, TOutput = any>(request: CallRequest<TInput>): Promise<TOutput>;
924
901
  /**
925
- * Observes a function: every event of `source` that passes its `filters`
926
- * invokes `target`, a registered function. Returns synchronously (also
927
- * before the connection is up); the observer is replayed with the same id
928
- * on reconnect. Errors show up as state `error` and reject `ready()`;
929
- * against an engine without observe that is `UNSUPPORTED`.
902
+ * Observes a function: every call of `source` that passes its `filters`
903
+ * runs `target`, a registered function. Returns synchronously (also before
904
+ * the connection is up); the observer is replayed with the same id on
905
+ * reconnect. Errors show up as state `error` and reject `ready()`; against
906
+ * an engine without observe that is `UNSUPPORTED`. An `error` answer to its
907
+ * `observe` is the engine's refusal, the handle's final answer: the engine
908
+ * holds no observer for it, it is not replayed, and its `dispose()` sends
909
+ * nothing.
930
910
  *
931
- * @param source - What is observed: `function_id`, `args` (owner-delivered functions only), `filters`, `on`, `capture`, `deliver`.
911
+ * @param source - What is observed: a function id, or `function_id`, `args` (read by the worker that hosts the function), `filters`, `on`, `capture`, `deliver`.
932
912
  * @param target - The function to invoke.
933
913
  * @param options - `id`, `max_fires`, `expires_in_ms`, `max_in_flight`, `metadata`.
934
914
  *
@@ -936,6 +916,10 @@ interface ISdk {
936
916
  * ```typescript
937
917
  * worker.registerFunction('ui::order-shipped', async ({ input }: Observed) => toast(input))
938
918
  *
919
+ * // every successful call of orders::ship
920
+ * worker.observe('orders::ship', 'ui::order-shipped')
921
+ *
922
+ * // only this customer's
939
923
  * const shipped = worker.observe(
940
924
  * { function_id: 'orders::ship', filters: { 'input.customer_id': { $eq: customerId } } },
941
925
  * 'ui::order-shipped',
@@ -943,10 +927,104 @@ interface ISdk {
943
927
  * await shipped.ready()
944
928
  * ```
945
929
  */
946
- observe(source: ObserveSource, target: Target, options?: ObserverOptions): ObserverHandle;
930
+ observe(source: string | ObserveSource, target: Target, options?: ObserverOptions): ObserverHandle;
931
+ /**
932
+ * Runs `hook` when an observer of any function this worker hosts is added,
933
+ * before the SDK acks it; with a function id, for that function only. When
934
+ * both are set, the worker's runs first. Throw to reject the observer.
935
+ * `null` removes the hook. Hooks set by id stay in place across
936
+ * `unregister()` and a later registration of the same id.
937
+ *
938
+ * A hook set while the function already has active observers runs for each
939
+ * of them at once (a throw late-rejects that observer), and the SDK logs a
940
+ * warning.
941
+ *
942
+ * @example
943
+ * ```typescript
944
+ * // every function this page hosts: keep the event stream open while anything is observed
945
+ * worker.onObserverAdded(async () => { await events.retain() })
946
+ * // one function, by id
947
+ * worker.onObserverAdded('ui::on-click', (obs) => targets.retain(obs.args.selector as string))
948
+ * ```
949
+ */
950
+ onObserverAdded(hook: AddedHook | null): ISdk;
951
+ onObserverAdded(functionId: string, hook: AddedHook | null): ISdk;
952
+ /**
953
+ * Runs `hook` once for every accepted observer when it is removed (on
954
+ * `unobserve`, disposal, unregister, late rejection); with a function id,
955
+ * for that function only. When both are set, the function's runs first. An
956
+ * error it throws is logged. `null` removes the hook.
957
+ */
958
+ onObserverRemoved(hook: RemovedHook | null): ISdk;
959
+ onObserverRemoved(functionId: string, hook: RemovedHook | null): ISdk;
960
+ /**
961
+ * Says which observers want each call of a function. By default every
962
+ * observer wants every call. A predicate `(obs, call) => boolean` is asked
963
+ * once per observation (for every call, once for each active observer);
964
+ * `{ observer, call }` key functions are computed once per observer, when
965
+ * it is accepted, and once per call, and an
966
+ * observer wants a call when they share a key (the SDK keeps an index). The
967
+ * observers' `on`, filters, policy and `deliver` still apply. A hook set
968
+ * while observers are active rebuilds the index from them. `null` removes
969
+ * the hook, predicate or keys: every observer gets every call again.
970
+ *
971
+ * A function with a match hook needs an engine with `observe.v2`: against
972
+ * an older one it stays unregistered, and the SDK logs `UNSUPPORTED` once.
973
+ *
974
+ * @example
975
+ * ```typescript
976
+ * // an observer of selector X gets the clicks on X
977
+ * worker.onObservationMatch('ui::on-click', (obs, call) => obs.args.selector === call.input.selector)
978
+ *
979
+ * // many observers: keys, one lookup per key
980
+ * worker.onObservationMatch('ui::on-click', {
981
+ * observer: (obs) => obs.args.selector as string,
982
+ * call: (call) => call.input.selector,
983
+ * })
984
+ * ```
985
+ */
986
+ onObservationMatch<I = any, O = any>(functionId: string, hook: MatchPredicate<I, O> | null): ISdk;
987
+ onObservationMatch<I = any, O = any>(functionId: string, hook: MatchKeys<I, O>): ISdk;
988
+ onObservationMatch<I = any, O = any>(functionId: string, hook: MatchHook<I, O> | null): ISdk;
947
989
  /**
948
- * The invocation the calling code runs in (remote or local handler), or
949
- * `undefined` outside any handler.
990
+ * Delivers each call of a function itself: `hook` receives the call and the
991
+ * observers that matched it (a snapshot taken when the call started), and
992
+ * what it returns (or throws) is what the caller gets back. iii delivers
993
+ * nothing for that function: the hook calls through observers and applies
994
+ * their filters with `obs.matches(call)`. Without it, iii delivers every
995
+ * call to the matching observers whose `on` and filters accept it, and the
996
+ * caller gets the handler's result. `null` removes the hook.
997
+ *
998
+ * A function with a deliver hook needs an engine with `observe.v2`: against
999
+ * an older one it stays unregistered, and the SDK logs `UNSUPPORTED` once.
1000
+ *
1001
+ * The hook runs in the function's invocation: up to its first `await` in
1002
+ * its scope, and after it as the invocation the page falls back to while it
1003
+ * is the only one running (see {@link ISdk.withInvocation}).
1004
+ *
1005
+ * @example
1006
+ * ```typescript
1007
+ * worker.onObservationDeliver('ui::on-command', async (call) => {
1008
+ * const handler = commands.match(call.input)
1009
+ * if (!handler) return { handled: false }
1010
+ * if (!handler.obs.matches(call)) return { handled: false }
1011
+ * return worker.call({ observer: handler.obs, payload: call.input })
1012
+ * })
1013
+ * ```
1014
+ */
1015
+ onObservationDeliver<I = any, O = any, R = O>(functionId: string, hook: DeliverHook<I, O, R> | null): ISdk;
1016
+ /** The active observers of a function this worker hosts (empty for any other). */
1017
+ observers(functionId: string): readonly Observer[];
1018
+ /**
1019
+ * Whether a call of a function this worker hosts would reach anyone.
1020
+ * Without a call: any active observer. With a call, on a function matched
1021
+ * by keys: an observer filed under one of the call's keys. On any other
1022
+ * function the call is not read.
1023
+ */
1024
+ isObserved(functionId: string, call?: Partial<Call>): boolean;
1025
+ /**
1026
+ * The invocation the calling code runs in (remote or local handler, or the
1027
+ * function's deliver hook), or `undefined` outside any handler.
950
1028
  *
951
1029
  * Browsers have no `AsyncLocalStorage`: the SDK knows the invocation while
952
1030
  * the handler runs synchronously, up to its first `await`; after it this
@@ -960,9 +1038,8 @@ interface ISdk {
960
1038
  * whose target awaits before calling back. With several invocations
961
1039
  * running this over-counts, and a legitimate chain may stop early. They
962
1040
  * carry a `caller` and `traceparent` only when that is unambiguous (one
963
- * invocation is running, and it is an observe activation); otherwise none.
964
- * They never get an invocation's metadata: `obs.emit` / `obs.call` filters
965
- * on `metadata.*` see it only inside a real scope. An invocation that never
1041
+ * invocation is running, and it is an observe activation or its function's
1042
+ * deliver hook is running); otherwise none. An invocation that never
966
1043
  * settles stops counting as running after 10 minutes (a local call: at its
967
1044
  * timeout). Local calls nest the same way: a self-recursion that awaits
968
1045
  * before each call goes through the engine past 64 levels, while calls
@@ -978,7 +1055,7 @@ interface ISdk {
978
1055
  * worker.registerFunction('ui::checkout', async (cart) => {
979
1056
  * const inv = worker.currentInvocation() // { function_id, invocation_id, caller, observe_depth, ... }
980
1057
  * const quote = await fetchQuote(cart)
981
- * return worker.withInvocation(inv, () => worker.trigger({ function_id: 'orders::create', payload: quote }))
1058
+ * return worker.withInvocation(inv, () => worker.call({ function_id: 'orders::create', payload: quote }))
982
1059
  * })
983
1060
  * ```
984
1061
  */
@@ -986,11 +1063,11 @@ interface ISdk {
986
1063
  /**
987
1064
  * Runs `fn` inside `invocation` (what {@link ISdk.currentInvocation}
988
1065
  * returned), and returns what `fn` returns. Calls `fn` makes before its own
989
- * first `await` (`trigger`, `obs.emit`, `obs.call`, `currentInvocation`)
990
- * belong to that invocation: they carry its caller, `observe_depth` and
991
- * `traceparent`. When `fn` returns a promise, the invocation counts as
992
- * running until it settles, so `fn`'s code after an `await` gets the
993
- * fallback below. `undefined` runs `fn` outside any invocation.
1066
+ * first `await` (`call`, `currentInvocation`) belong to that invocation:
1067
+ * they carry its caller, `observe_depth` and `traceparent`. When `fn`
1068
+ * returns a promise, the invocation counts as running until it settles, so
1069
+ * `fn`'s code after an `await` gets the fallback below. `undefined` runs
1070
+ * `fn` outside any invocation.
994
1071
  *
995
1072
  * Code after an `await`, outside `withInvocation`, runs outside any
996
1073
  * invocation, but its calls are not treated as new chains: they carry the
@@ -999,9 +1076,8 @@ interface ISdk {
999
1076
  * whose target awaits before calling back. With several invocations
1000
1077
  * running this over-counts, and a legitimate chain may stop early. They
1001
1078
  * carry a `caller` and `traceparent` only when that is unambiguous (one
1002
- * invocation is running, and it is an observe activation); otherwise none.
1003
- * They never get an invocation's metadata: `obs.emit` / `obs.call` filters
1004
- * on `metadata.*` see it only inside a real scope. An invocation that never
1079
+ * invocation is running, and it is an observe activation or its function's
1080
+ * deliver hook is running); otherwise none. An invocation that never
1005
1081
  * settles stops counting as running after 10 minutes (a local call: at its
1006
1082
  * timeout). Local calls nest the same way: a self-recursion that awaits
1007
1083
  * before each call goes through the engine past 64 levels, while calls
@@ -1013,48 +1089,6 @@ interface ISdk {
1013
1089
  * `LOCAL_DEPTH_EXCEEDED` (a runaway recursion must not freeze the page).
1014
1090
  */
1015
1091
  withInvocation<T>(invocation: InvocationContext | undefined, fn: () => T): T;
1016
- /**
1017
- * Registers a new trigger type. A trigger type is a way to invoke a function when a certain event occurs.
1018
- *
1019
- * @deprecated Register a function with an observe descriptor instead:
1020
- * `registerFunction(id, handler, { observe: { delivery: 'owner', onObserverAdded, onObserverRemoved } })`.
1021
- * Logs a warning once per page. Migration guide: https://iii.dev/docs/upgrading/from-0-24-x
1022
- * @param triggerType - The trigger type to register
1023
- * @param handler - The handler for the trigger type
1024
- * @returns A trigger type object that can be used to unregister the trigger type
1025
- *
1026
- * @example
1027
- * ```typescript
1028
- * type CronConfig = { expression: string }
1029
- *
1030
- * worker.registerTriggerType<CronConfig>(
1031
- * { id: 'cron', description: 'Fires on a cron schedule' },
1032
- * {
1033
- * async registerTrigger({ id, function_id, config }) {
1034
- * startCronJob(id, config.expression, () =>
1035
- * worker.trigger({ function_id, payload: {} }),
1036
- * )
1037
- * },
1038
- * async unregisterTrigger({ id }) {
1039
- * stopCronJob(id)
1040
- * },
1041
- * },
1042
- * )
1043
- * ```
1044
- */
1045
- registerTriggerType<TConfig>(triggerType: RegisterTriggerTypeInput, handler: TriggerHandler<TConfig>): TriggerTypeRef<TConfig>;
1046
- /**
1047
- * Unregisters a trigger type.
1048
- *
1049
- * @deprecated Trigger types are replaced by functions with an observe descriptor.
1050
- * @param triggerType - The trigger type to unregister
1051
- *
1052
- * @example
1053
- * ```typescript
1054
- * worker.unregisterTriggerType({ id: 'cron', description: 'Fires on a cron schedule' })
1055
- * ```
1056
- */
1057
- unregisterTriggerType(triggerType: RegisterTriggerTypeInput): void;
1058
1092
  /**
1059
1093
  * Gracefully shutdown the iii, cleaning up all resources.
1060
1094
  *
@@ -1091,84 +1125,44 @@ interface ISdk {
1091
1125
  getFatalError(): RegistrationRejectedError | undefined;
1092
1126
  }
1093
1127
  /**
1094
- * Handle returned by {@link ISdk.registerTrigger}. Use `unregister()` to
1095
- * remove the trigger from the engine.
1096
- *
1097
- * @deprecated `registerTrigger` is replaced by `iii.observe`, which returns an {@link ObserverHandle}.
1098
- */
1099
- type Trigger = {
1100
- /** Removes this trigger from the engine. */unregister(): void;
1101
- };
1102
- /**
1103
- * Handle returned by {@link ISdk.registerFunction}. Contains the function's
1104
- * `id` and an `unregister()` method.
1105
- */
1106
- type FunctionRef = {
1107
- /** The unique function identifier. */id: string; /** Removes this function from the engine. */
1108
- unregister: () => void;
1109
- /**
1110
- * Whether any observer is active on this function (one load, for the emit
1111
- * fast path: skip building an event nobody receives).
1112
- */
1113
- isObserved: () => boolean; /** The active observers, as this owner sees them. */
1114
- observers: () => readonly Observer[];
1115
- };
1116
- /**
1117
- * Typed handle returned by {@link ISdk.registerTriggerType}.
1118
- *
1119
- * @deprecated Trigger types are replaced by functions with an observe
1120
- * descriptor, and these helpers by `iii.observe`. Migration guide:
1121
- * https://iii.dev/docs/upgrading/from-0-24-x
1122
- *
1123
- * Provides convenience methods to register triggers and functions scoped
1124
- * to this trigger type, so callers don't need to repeat the `type` field.
1125
- *
1126
- * @typeParam TConfig - Trigger-specific configuration type.
1128
+ * Handle returned by {@link ISdk.registerFunction}: the client's hook
1129
+ * methods with the function id filled in. Each method returns the handle, so
1130
+ * calls chain.
1127
1131
  *
1128
1132
  * @example
1129
1133
  * ```typescript
1130
- * type CronConfig = { expression: string }
1131
- *
1132
- * const cron = worker.registerTriggerType<CronConfig>(
1133
- * { id: 'cron', description: 'Fires on a cron schedule' },
1134
- * cronHandler,
1135
- * )
1136
- *
1137
- * // Register a trigger; type is inferred as CronConfig
1138
- * cron.registerTrigger('my::fn', { expression: '0 *\/5 * * * * *' })
1139
- *
1140
- * // Register a function and bind a trigger in one call
1141
- * cron.registerFunction(
1142
- * 'my::fn',
1143
- * async (data) => { return { ok: true } },
1144
- * { expression: '0 *\/5 * * * * *' },
1145
- * )
1134
+ * worker.registerFunction('ui::on-click', (click: Click) => click, { private: true })
1135
+ * .onObserverAdded((obs) => targets.retain(obs.args.selector as string))
1136
+ * .onObserverRemoved((obs) => targets.release(obs.args.selector as string))
1146
1137
  * ```
1147
1138
  */
1148
- type TriggerTypeRef<TConfig = unknown> = {
1149
- /** The trigger type identifier. */id: string;
1150
- /**
1151
- * Register a trigger bound to this trigger type.
1152
- *
1153
- * @param functionId - The function to invoke when the trigger fires.
1154
- * @param config - Trigger-specific configuration.
1155
- * @returns A {@link Trigger} handle with an `unregister()` method.
1156
- */
1157
- registerTrigger(functionId: string, config: TConfig): Trigger;
1139
+ interface FunctionRef<I = any, O = any> {
1140
+ /** The unique function identifier. */
1141
+ readonly id: string;
1142
+ /** {@link ISdk.onObserverAdded} for this function. */
1143
+ onObserverAdded(hook: AddedHook | null): FunctionRef<I, O>;
1144
+ /** {@link ISdk.onObserverRemoved} for this function. */
1145
+ onObserverRemoved(hook: RemovedHook | null): FunctionRef<I, O>;
1146
+ /** {@link ISdk.onObservationMatch} for this function. */
1147
+ onObservationMatch(hook: MatchPredicate<I, O> | null): FunctionRef<I, O>;
1148
+ onObservationMatch(hook: MatchKeys<I, O>): FunctionRef<I, O>;
1149
+ onObservationMatch(hook: MatchHook<I, O> | null): FunctionRef<I, O>;
1150
+ /** {@link ISdk.onObservationDeliver} for this function. */
1151
+ onObservationDeliver<R = O>(hook: DeliverHook<I, O, R> | null): FunctionRef<I, O>;
1158
1152
  /**
1159
- * Register a function and immediately bind it to this trigger type.
1160
- *
1161
- * @param functionId - Unique function identifier.
1162
- * @param handler - Local function handler.
1163
- * @param config - Trigger-specific configuration.
1164
- * @returns A {@link FunctionRef} handle.
1153
+ * The active observers of this registration, as this host sees them (none
1154
+ * once the function is unregistered, also after the id is registered again).
1165
1155
  */
1166
- registerFunction(functionId: string, handler: RemoteFunctionHandler, config: TConfig): FunctionRef;
1156
+ observers(): readonly Observer[];
1167
1157
  /**
1168
- * Unregister this trigger type from the engine.
1158
+ * {@link ISdk.isObserved} for this registration: skip building an event
1159
+ * nobody receives. Without a call it is one load of this registration's
1160
+ * active set.
1169
1161
  */
1162
+ isObserved(call?: Partial<Call<I>>): boolean;
1163
+ /** Removes this function from the engine. Its hooks stay in place for a later registration of the id. */
1170
1164
  unregister(): void;
1171
- };
1165
+ }
1172
1166
  /**
1173
1167
  * A streaming channel pair for worker-to-worker data transfer. Created via
1174
1168
  * the `createChannel` helper from `iii-browser-sdk/helpers`.
@@ -1180,7 +1174,7 @@ type Channel = {
1180
1174
  readerRef: StreamChannelRef;
1181
1175
  };
1182
1176
  /**
1183
- * Incoming HTTP request received by a function registered with an HTTP trigger.
1177
+ * The HTTP request an `http::on-request` route's target receives.
1184
1178
  *
1185
1179
  * @typeParam TBody - Type of the parsed request body.
1186
1180
  */
@@ -1192,7 +1186,7 @@ type ApiRequest<TBody = unknown> = {
1192
1186
  method: string;
1193
1187
  };
1194
1188
  /**
1195
- * Structured API response returned from HTTP function handlers.
1189
+ * The response an `http::on-request` route's target returns.
1196
1190
  *
1197
1191
  * @typeParam TStatus - HTTP status code literal type.
1198
1192
  * @typeParam TBody - Type of the response body.
@@ -1212,5 +1206,5 @@ type ApiResponse<TStatus extends number = number, TBody = string | Record<string
1212
1206
  body?: TBody;
1213
1207
  };
1214
1208
  //#endregion
1215
- export { OnTriggerTypeRegistrationInput as $, EngineFunctions as A, ChannelItem as B, ObserveSource as C, ObserverOptions as D, ObserverHandle as E, InvocationErrorInit as F, EnqueueResult as G, ChannelWriter as H, ObserveRejection as I, ObserveDescriptorWire as J, MessageType as K, RegistrationRejectedError as L, IIIConnectionState as M, IIIReconnectionConfig as N, ObserverState as O, InvocationError as P, OnTriggerRegistrationResult as Q, RegistrationRejectedInit as R, ObserveReason as S, Observer as T, AuthInput as U, ChannelReader as V, AuthResult as W, OnFunctionRegistrationResult as X, OnFunctionRegistrationInput as Y, OnTriggerRegistrationInput as Z, Capture as _, ISdk as a, RegisterTriggerTypeMessage as at, ObserveDoc as b, RegisterTriggerInput as c, Trigger as d, OnTriggerTypeRegistrationResult as et, TriggerTypeRef as f, CallerInfo as g, Caller as h, FunctionRef as i, RegisterTriggerMessage as it, EngineTriggers as j, Target as k, RegisterTriggerTypeInput as l, TriggerHandler as m, ApiResponse as n, RegisterFunctionFormat as nt, RegisterFunctionInput as o, StreamChannelRef as ot, TriggerConfig as p, MiddlewareFunctionInput as q, Channel as r, RegisterFunctionMessage as rt, RegisterFunctionOptions as s, TriggerRequest as st, ApiRequest as t, OpenEnum as tt, RemoteFunctionHandler as u, Filter as v, Observed as w, ObserveHooks as x, InvocationContext as y, ChannelDirection as z };
1216
- //# sourceMappingURL=types-BGYN2Z4E.d.cts.map
1209
+ export { ObserverState as $, OpenEnum as A, DeliverHook as B, AuthResult as C, MiddlewareFunctionInput as D, MessageType as E, AddedHook as F, MatchKeys as G, InvocationContext as H, Call as I, ObserveSource as J, MatchPredicate as K, Caller as L, RegisterFunctionMessage as M, StreamChannelRef as N, OnFunctionRegistrationInput as O, TriggerRequest as P, ObserverOptions as Q, CallerInfo as R, AuthInput as S, EnqueueResult as T, Key as U, Filter as V, MatchHook as W, Observer as X, Observed as Y, ObserverHandle as Z, RegistrationRejectedInit as _, ISdk as a, ChannelReader as b, RemoteFunctionHandler as c, IIIConnectionState as d, RemovedHook as et, IIIReconnectionConfig as f, RegistrationRejectedError as g, ObserveRejection as h, FunctionRef as i, RegisterFunctionFormat as j, OnFunctionRegistrationResult as k, EngineFunctions as l, InvocationErrorInit as m, ApiResponse as n, RegisterFunctionInput as o, InvocationError as p, ObserveReason as q, Channel as r, RegisterFunctionOptions as s, ApiRequest as t, Target as tt, EngineSources as u, ChannelDirection as v, CallRequest as w, ChannelWriter as x, ChannelItem as y, Capture as z };
1210
+ //# sourceMappingURL=types-Bf5tgTLe.d.cts.map