@toa.io/extensions.realtime 1.0.0-alpha.28 → 1.0.0-alpha.282

package/CHANGELOG.md

@@ -0,0 +1,323 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [1.0.0-alpha.282](https://github.com/toa-io/toa/compare/v1.0.0-alpha.281...v1.0.0-alpha.282) (2026-09-03)
+
+### Bug Fixes
+
+* **boot:** declare host, and build extensions with it in the step definitions ([915d957](https://github.com/toa-io/toa/commit/915d9571823358f8fca6fe19ef3aabd1b62e5605))
+
+### Features
+
+* **core:** a Host for extensions ([6315eac](https://github.com/toa-io/toa/commit/6315eac1e9fb05be472272de06385c54ad5934ce))
+
+
+# [1.0.0-alpha.278](https://github.com/toa-io/toa/compare/v1.0.0-alpha.277...v1.0.0-alpha.278) (2026-09-03)
+
+**Note:** Version bump only for package @toa.io/extensions.realtime
+
+
+
+
+
+# [1.0.0-alpha.277](https://github.com/toa-io/toa/compare/v1.0.0-alpha.276...v1.0.0-alpha.277) (2026-09-03)
+
+### Bug Fixes
+
+* drop the build output that landed beside the sources ([a724f69](https://github.com/toa-io/toa/commit/a724f6921190e5c9d945e33c6035bb12d832e5c8))
+* settle what the module loader made asynchronous ([d4ab9df](https://github.com/toa-io/toa/commit/d4ab9dfb09e382da311dba08f52214e7645f4a6c))
+* what the loader resolves, and what it will not ([1b8a02f](https://github.com/toa-io/toa/commit/1b8a02ff0a5e0f18ee62e3f71bc81116f86f9af1))
+
+
+# [1.0.0-alpha.274](https://github.com/toa-io/toa/compare/v1.0.0-alpha.273...v1.0.0-alpha.274) (2026-09-02)
+
+
+* Configuration is served by a component, followed live, and kept per epoch (#1017) ([b05997d](https://github.com/toa-io/toa/commit/b05997d3adb784f238a222cb46878b23859339a2)), closes [#1017](https://github.com/toa-io/toa/issues/1017)
+
+
+### BREAKING CHANGES
+
+* a secret configuration value is an object, not a string;
+read it with `unwrap()`.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+
+* test(configuration): wait for the second round rather than assume it
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+
+* refactor(configuration)!: read a secret with its own unwrap
+
+Component code depends on no Toa package, so a secret is read as
+`context.configuration.apiKey.unwrap()` and the helper in `@toa.io/generic`
+goes. A value a component reads as a secret is therefore given as a reference:
+`identity.basic` no longer defaults `pepper` to `''`, the development context
+and the feature harness give the token keys, the federation client secret and
+the signing key as references, and the harness has a step for the secrets a
+scenario refers to. CONTRIBUTING states the rule.
+* `identity.basic` `pepper` has no default; a value read as a
+secret must be given as a `$NAME` reference.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+
+* feat(configuration): list the configurations
+
+`configuration.values.list` returns every component's configuration for its
+deployed epoch, by component name, and `GET /configuration/values/` serves it
+behind `system:configuration:get`.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+
+* fix(exposition): write a value in YAML the way its toJSON says
+
+A redacted secret in a reply was dumped as an empty object; it is written as
+`<REDACTED>`, as JSON and msgpack already write it.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+
+* test(configuration): a secret is an object, and stays redacted in a reply
+
+A component with `{ a: 1, b: $SECRET_B }` returns its configuration as
+`{ a: 1, b: '<REDACTED>' }` and the secret itself through `unwrap()`. The reply
+step also accepts a reply as a caller across a process boundary receives it,
+since a call within the process hands the object over as it is.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+
+* chore(schemas): bump the dependencies
+
+ajv 8.18.0 to 8.20.0, ajv-formats 2.1.1 to 3.0.1, better-ajv-errors 1.2.0
+to 2.0.3, fast-glob 3.2.12 to 3.3.3 and js-yaml 4.3.1 to 5.4.1 — the version
+exposition already uses. The three majors keep the CommonJS entry points this
+library calls: ajv-formats as a function, better-ajv-errors as .default, and
+js-yaml's load.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(configuration)!: serve the schema with the value
+
+GET /configuration/values/:component/ answers { configuration, schema, epoch }
+where it answered with the configuration alone, and list carries the schema of
+every component. Nothing reads a configuration without needing to know what it
+is checked against, and the schema was only ever on the values service.
+
+An epoch the deployment does not know has no schema; the value stored for it
+is still returned.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(configuration): publish a configuration UI
+
+The values service serves a page at /.configuration on port 8003, out of the
+directory ui builds: the configured components, a screen per component showing
+what it holds now, and a dialog creating the next one. Reading needs
+system:configuration:get and creating needs system:configuration:create.
+
+A configuration is immutable, so the dialog opens on the current value and what
+is left out of it is left out of the component. The editor takes YAML, the
+schema is applied before anything is sent, and a secret is a reference the page
+never shows.
+
+The page is always published: the annotation is the per-component values map
+and has nowhere to carry a switch.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(introspection): link a component to its configuration
+
+A card carrying @toa.io/extensions.configuration reads that extension as a link
+to the configuration UI rather than as a name, and configuration joins the
+namespaces the runtime provides, so its components band under System.
+
+Deployed, both pages sit behind the same ingress and the path alone is right;
+locally each console has its own port.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(introspection): scroll the map, zoom with a modifier
+
+The map was grabbed to move and zoomed with a bare wheel, which is neither what
+a page does nor what the wheel does anywhere else. A plain scroll now pans on
+both axes and the wheel scales only with the modifier held — a trackpad pinch
+arrives as one of those on every platform.
+
+A card's own scrollable box keeps its wheel, in both paths.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* refactor(introspection): centre the filter in the header
+
+The sides take equal space, which is what leaves the filter between them.
+Neither side may shrink under what it holds, or the tabs run out from under
+their side and across the filter, and the filter across the sign-out button;
+the title gives way instead.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* fix(configuration): connect the UI to the values service
+
+The page was declared as a dependency from inside `open`, and a connector connects
+what it depends on before `open` runs — so the server was constructed and never
+listened. Nothing caught it: the UI feature builds the server itself.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(configuration)!: reserve resources in the annotation
+
+The values service deploys like any other and must state what it may take, but the
+annotation is a map of component ids and had nowhere to put it — so `toa env` failed
+for every context using configuration unless it declared a context-wide `resources`.
+
+`resources` is now the service's own, read the way `introspection` and `realtime` read
+theirs. A component actually named `resources` is written `default.resources`, which is
+what its id is anyway.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(configuration): follow the system colour scheme
+
+The dark tokens were behind a `.dark` class nothing sets, and the `dark:` variant was
+pointed at that class too — so a component's own dark styling never applied either.
+Both now key off `prefers-color-scheme`, and `color-scheme` hands the native chrome
+the same answer.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(introspection): follow the system colour scheme
+
+The dark tokens were behind a `.dark` class nothing sets, and the `dark:` variant was
+pointed at that class too — so a component's own dark styling never applied either.
+Both now key off `prefers-color-scheme`, and `color-scheme` hands the native chrome
+the same answer.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(configuration): present a change as an edit of what is there
+
+A configuration is immutable and creating one replaces the whole of it, but the dialog
+opens on the current value and the page never shows an older one — so what the reader
+does is edit. The words follow: Edit rather than New, Update rather than Create, and
+the paragraph explaining the model goes, along with the field's label, which the title
+above it already said.
+
+The editor also stayed as wide as its longest line — `field-sizing: content` sizes to
+content, and no `max-width` clamps that — so a long value painted outside the dialog.
+It is fixed now, the dialog takes the width the screen has rather than a fixed step,
+and the band held for errors no longer leaves a gap when there are none.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(configuration): mark a component that keeps a secret
+
+A key after the name on the row, wherever the configuration holds a reference, however
+deep. The predicate reads the same lines the value screen renders, so the two cannot
+disagree about what counts as a secret.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(configuration): lead back to the list from the title
+
+Every address ends in a slash, so the way up is the address itself on the list and one
+level above it on a component's screen — which holds wherever the page is mounted.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+
+
+
+
+# [1.0.0-alpha.273](https://github.com/toa-io/toa/compare/v1.0.0-alpha.272...v1.0.0-alpha.273) (2026-09-02)
+
+
+### Bug Fixes
+
+* **exposition:** green the feature suite ([67c25ad](https://github.com/toa-io/toa/commit/67c25ad627db3b3779b09405c5a3c319ecd47722))
+* **realtime:** green the feature suite ([6b4650b](https://github.com/toa-io/toa/commit/6b4650bad9e1d53dabd0b7775966694bdb05f236))
+
+
+
+
+
+# [1.0.0-alpha.272](https://github.com/toa-io/toa/compare/v1.0.0-alpha.271...v1.0.0-alpha.272) (2026-09-01)
+
+**Note:** Version bump only for package @toa.io/extensions.realtime
+
+
+
+
+
+# [1.0.0-alpha.270](https://github.com/toa-io/toa/compare/v1.0.0-alpha.269...v1.0.0-alpha.270) (2026-08-31)
+
+**Note:** Version bump only for package @toa.io/extensions.realtime
+
+
+
+
+
+# [1.0.0-alpha.266](https://github.com/toa-io/toa/compare/v1.0.0-alpha.265...v1.0.0-alpha.266) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/extensions.realtime
+
+
+
+
+
+# [1.0.0-alpha.265](https://github.com/toa-io/toa/compare/v1.0.0-alpha.264...v1.0.0-alpha.265) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/extensions.realtime
+
+
+
+
+
+# [1.0.0-alpha.264](https://github.com/toa-io/toa/compare/v1.0.0-alpha.263...v1.0.0-alpha.264) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/extensions.realtime
+
+
+
+
+
+# [1.0.0-alpha.263](https://github.com/toa-io/toa/compare/v1.0.0-alpha.262...v1.0.0-alpha.263) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/extensions.realtime
+
+
+
+
+
+# [1.0.0-alpha.262](https://github.com/toa-io/toa/compare/v1.0.0-alpha.261...v1.0.0-alpha.262) (2026-08-28)
+
+
+### Features
+
+* **core:** identify the origin of a call with `request.source` ([9da6b66](https://github.com/toa-io/toa/commit/9da6b66df852690351a1e82c7b8cc176fd89774a))
+
+
+
+
+
+# [1.0.0-alpha.259](https://github.com/toa-io/toa/compare/v1.0.0-alpha.258...v1.0.0-alpha.259) (2026-08-24)
+
+**Note:** Version bump only for package @toa.io/extensions.realtime
+
+
+
+
+
+# [1.0.0-alpha.257](https://github.com/toa-io/toa/compare/v1.0.0-alpha.256...v1.0.0-alpha.257) (2026-08-24)
+
+**Note:** Version bump only for package @toa.io/extensions.realtime
+
+
+
+
+
+# [1.0.0-alpha.256](https://github.com/toa-io/toa/compare/v1.0.0-alpha.255...v1.0.0-alpha.256) (2026-08-23)
+
+
+### Features
+
+* add toa mono and discover components at components/* ([787a111](https://github.com/toa-io/toa/commit/787a111c8f83e56ebc734801c97106c585d034ea))

package/components/realtime.streams/manifest.toa.yaml

@@ -0,0 +1,44 @@
+namespace: realtime
+name: streams
+
+operations:
+  create:
+    input:
+      properties:
+        key:
+          type: string
+        token:
+          type: string
+      type: object
+  push:
+    bindings: ~ # only for internal use
+    input:
+      properties:
+        data: {}
+        key:
+          type: string
+        event:
+          type: string
+      type: object
+      required:
+        - key
+        - event
+
+configuration:
+  schema:
+    properties:
+      maxlen:
+        type: number
+        default: 1000
+      expire:
+        type: number
+        default: 300
+    type: object
+
+state: ~
+stash: ~
+
+exposition:
+  /:key:
+    auth:id: key
+    GET: create

package/components/{streams → realtime.streams}/operations/create.d.ts

@@ -1,14 +1,17 @@
-/// <reference types="node" />
 import { type Readable } from 'node:stream';
 import { type Operation } from '@toa.io/types';
-import { type Context } from './types';
+import { type Context } from './lib/types.js';
 export declare class Effect implements Operation {
     private readonly streams;
+    private stash;
+    private logs;
     mount(context: Context): void;
-    execute(input: Input, context: Context): Promise<Readable>;
+    unmount(): void;
+    execute(input: Input): Promise<Readable>;
     private createStream;
 }
 interface Input {
     key: string;
+    token?: string;
 }
 export {};

package/components/realtime.streams/operations/create.js

@@ -0,0 +1,65 @@
+import { Stream, Stash } from './lib/index.js';
+export class Effect {
+    streams = new Map();
+    stash;
+    logs;
+    mount(context) {
+        context.state.streams = this.streams;
+        context.state.stash = new Stash(context.stash, context.configuration, context.logs);
+        this.logs = context.logs;
+        this.stash = context.state.stash;
+    }
+    unmount() {
+        this.logs.info('Destroying streams', { count: this.streams.size });
+        // closed, not destroyed: destroying a stream that is still piped to a response
+        // makes end-of-stream report a premature close, which reaches no one and takes
+        // the process down.
+        for (const stream of this.streams.values())
+            stream.close();
+    }
+    async execute(input) {
+        const key = input.key;
+        if (!this.streams.has(key)) {
+            const stream = this.createStream(key);
+            this.streams.set(key, stream);
+            this.logs.debug('Stream created', { key });
+        }
+        // welcome
+        setTimeout(() => this.streams.get(key)?.heartbeat(), 1000);
+        if (input.token === undefined)
+            void this.stash.connect(key).then((token) => {
+                if (token instanceof Error)
+                    this.logs.error('Failed to connect to stash', { key, error: token });
+                else
+                    this.streams.get(key)?.push({ event: 'token', data: token });
+            });
+        else
+            void this.stash.pop(key, input.token).then((result) => {
+                if (result === null)
+                    return;
+                if ('code' in result && result.code === 'NO_RESULTS')
+                    return;
+                if (result instanceof Error) {
+                    this.logs.error('Failed to pop from stash', { key, error: result });
+                    return;
+                }
+                const stream = this.streams.get(key);
+                if (stream === undefined)
+                    return;
+                const [token, events] = result;
+                for (const event of events)
+                    stream.push({ event: event.event, data: event.data });
+                stream.push({ event: 'token', data: token });
+            });
+        return this.streams.get(key);
+    }
+    createStream(key) {
+        const stream = new Stream();
+        stream.events.once('destroy', () => {
+            this.logs.debug('Stream destroyed', { key });
+            this.streams.delete(key);
+        });
+        return stream;
+    }
+}
+//# sourceMappingURL=create.js.map

package/components/realtime.streams/operations/create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../source/create.ts"],"names":[],"mappings":"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"}

package/components/realtime.streams/operations/lib/Stash.d.ts

@@ -0,0 +1,21 @@
+export declare class Stash {
+    private readonly stash;
+    private readonly configuration;
+    private readonly logs;
+    constructor(stash: any, configuration: Configuration, logs: any);
+    connect(key: string): Promise<string | Error>;
+    push(key: string, event: string, data: unknown): Promise<string | Error>;
+    pop(key: string, token: string): Promise<[string, Event[]] | null | Error>;
+    private xadd;
+    private encode;
+    private decode;
+}
+interface Configuration {
+    maxlen: number;
+    expire: number;
+}
+interface Event {
+    event: string;
+    data: unknown;
+}
+export {};

package/components/realtime.streams/operations/lib/Stash.js

@@ -0,0 +1,86 @@
+export class Stash {
+    stash;
+    configuration;
+    logs;
+    constructor(stash, configuration, logs) {
+        this.stash = stash;
+        this.configuration = configuration;
+        this.logs = logs;
+    }
+    async connect(key) {
+        return await this.xadd(key, 'connect');
+    }
+    async push(key, event, data) {
+        return await this.xadd(key, event, data);
+    }
+    async pop(key, token) {
+        const stamp = this.decode(token);
+        const results = await this.stash
+            .xread('STREAMS', key, stamp)
+            .catch((error) => error);
+        if (results === null)
+            return ERR_NO_RESULTS;
+        if (results instanceof Error)
+            return results;
+        const items = entries(results);
+        if (items === null)
+            return null;
+        const events = [];
+        let lastStamp = null;
+        for (const item of items) {
+            const [, event, , json] = item[1];
+            lastStamp = item[0];
+            const data = json === undefined ? undefined : JSON.parse(json);
+            if (data === undefined)
+                this.logs.debug('Undefined event payload', { key, event });
+            events.push({ event, data });
+        }
+        if (lastStamp === null)
+            return null;
+        return [this.encode(lastStamp), events];
+    }
+    async xadd(key, event, data) {
+        const args = ['MAXLEN', '~', this.configuration.maxlen, '*', 'type', event];
+        if (data !== undefined)
+            args.push('data', JSON.stringify(data));
+        const results = await this.stash
+            .multi()
+            .xadd(key, ...args)
+            .expire(key, this.configuration.expire)
+            .exec()
+            .catch((error) => error);
+        if (results === null)
+            return ERR_NO_RESULTS;
+        if (results instanceof Error)
+            return results;
+        const [[error, stamp]] = results;
+        if (error !== null)
+            return error;
+        return this.encode(stamp);
+    }
+    encode(token) {
+        return Buffer.from(token).toString('base64url');
+    }
+    decode(token) {
+        return Buffer.from(token, 'base64url').toString();
+    }
+}
+/**
+ * `xread` answers with an array of `[stream, entries]` pairs over RESP2 and with an
+ * object keyed by stream name over RESP3. One stream is read, so either way it is the
+ * first, and an empty answer means nothing has been added since the token.
+ */
+function entries(results) {
+    if (Array.isArray(results))
+        return results.length === 0 ? null : results[0][1];
+    if (typeof results === 'object' && results !== null) {
+        const streams = Object.values(results);
+        return streams.length === 0 ? null : streams[0];
+    }
+    return null;
+}
+class NoResultsError extends Error {
+    code = 'NO_RESULTS';
+}
+const ERR_NO_RESULTS = new NoResultsError();
+//# sourceMappingURL=Stash.js.map

package/components/realtime.streams/operations/lib/Stash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Stash.js","sourceRoot":"","sources":["../../source/lib/Stash.ts"],"names":[],"mappings":"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"}

package/components/realtime.streams/operations/lib/Stream.d.ts

@@ -0,0 +1,13 @@
+import { EventEmitter } from 'node:events';
+import { Readable } from 'node:stream';
+export declare class Stream extends Readable {
+    events: EventEmitter<any>;
+    private interval;
+    private ended;
+    constructor();
+    _read(): void;
+    _destroy(error: Error | null, callback: (error?: (Error | null)) => void): void;
+    /** Ends the stream: whoever reads it gets EOF rather than a broken pipe. */
+    close(): void;
+    heartbeat(stream?: Readable): boolean;
+}

package/components/realtime.streams/operations/lib/Stream.js

@@ -0,0 +1,43 @@
+import { EventEmitter } from 'node:events';
+import { Readable } from 'node:stream';
+export class Stream extends Readable {
+    events = new EventEmitter();
+    interval = null;
+    ended = false;
+    constructor() {
+        super(objectMode);
+    }
+    // has to be here
+    _read() {
+        if (this.interval === null)
+            this.interval = setInterval(() => this.heartbeat(), HEARTBEAT_INTERVAL);
+    }
+    _destroy(error, callback) {
+        if (this.interval !== null)
+            clearInterval(this.interval);
+        this.events.emit('destroy');
+        super._destroy(error, callback);
+    }
+    /** Ends the stream: whoever reads it gets EOF rather than a broken pipe. */
+    close() {
+        this.ended = true;
+        if (this.interval !== null) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+        this.push(null);
+    }
+    heartbeat(stream = this) {
+        if (this.ended)
+            return false;
+        const resume = stream.push('heartbeat ' + Date.now());
+        if (!resume && this.interval !== null) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+        return resume;
+    }
+}
+const HEARTBEAT_INTERVAL = 16_000; // why?
+const objectMode = { objectMode: true };
+//# sourceMappingURL=Stream.js.map

package/components/realtime.streams/operations/lib/Stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Stream.js","sourceRoot":"","sources":["../../source/lib/Stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,MAAM,OAAO,MAAO,SAAQ,QAAQ;IAC3B,MAAM,GAAG,IAAI,YAAY,EAAE,CAAA;IAE1B,QAAQ,GAA0B,IAAI,CAAA;IACtC,KAAK,GAAG,KAAK,CAAA;IAErB;QACE,KAAK,CAAC,UAAU,CAAC,CAAA;IACnB,CAAC;IAED,iBAAiB;IACD,KAAK;QACnB,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI;YACxB,IAAI,CAAC,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,kBAAkB,CAAC,CAAA;IAC3E,CAAC;IAEe,QAAQ,CAAE,KAAmB,EAAE,QAA0C;QACvF,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI;YACxB,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAE9B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QAE3B,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IACjC,CAAC;IAED,4EAA4E;IACrE,KAAK;QACV,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QAEjB,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC3B,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;YAC5B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAA;QACtB,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACjB,CAAC;IAEM,SAAS,CAAE,MAAM,GAAa,IAAI;QACvC,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAA;QAE5B,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;QAErD,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtC,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;YAC5B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAA;QACtB,CAAC;QAED,OAAO,MAAM,CAAA;IACf,CAAC;CACF;AAED,MAAM,kBAAkB,GAAG,MAAM,CAAA,CAAC,OAAO;AACzC,MAAM,UAAU,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,CAAA"}

package/components/realtime.streams/operations/lib/index.d.ts

@@ -0,0 +1,2 @@
+export { Stash } from './Stash.js';
+export { Stream } from './Stream.js';

package/components/realtime.streams/operations/lib/index.js

@@ -0,0 +1,3 @@
+export { Stash } from './Stash.js';
+export { Stream } from './Stream.js';
+//# sourceMappingURL=index.js.map

package/components/realtime.streams/operations/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA"}

package/components/realtime.streams/operations/lib/types.d.ts

@@ -0,0 +1,22 @@
+import { type Stream } from './Stream.js';
+import { type Stash } from './Stash.js';
+export interface Context {
+    stash: any;
+    state: {
+        streams: Map<string, Stream>;
+        stash: Stash;
+    };
+    logs: {
+        info: (m: string, att?: object) => void;
+        error: (m: string, att?: object) => void;
+    };
+    configuration: {
+        maxlen: number;
+        expire: number;
+    };
+}
+export interface PushInput {
+    key: string;
+    event: string;
+    data: unknown;
+}