@lambdot/websocket 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.2.0
+
+### Patch Changes
+
+- Updated dependencies [[`71e5732`](https://github.com/Embers-of-the-Fire/lambdot/commit/71e57321ad4ec7d1aef3651d104123f8167ec2e7), [`71e5732`](https://github.com/Embers-of-the-Fire/lambdot/commit/71e57321ad4ec7d1aef3651d104123f8167ec2e7)]:
+  - @lambdot/core@0.2.0
+
+## 0.1.1
+
+### Patch Changes
+
+- [#10](https://github.com/Embers-of-the-Fire/lambdot/pull/10) [`19d37e4`](https://github.com/Embers-of-the-Fire/lambdot/commit/19d37e42c7a5514fb62c8f31c65e1aa01916d355) Thanks [@Embers-of-the-Fire](https://github.com/Embers-of-the-Fire)! - Switch inter-package dependency pins from exact versions to `workspace:*` so workspace members always resolve against local sources during development; pnpm rewrites the protocol to exact versions at pack/publish time.
+- Updated dependencies [[`19d37e4`](https://github.com/Embers-of-the-Fire/lambdot/commit/19d37e42c7a5514fb62c8f31c65e1aa01916d355)]:
+  - @lambdot/core@0.1.1
+
 ## [0.1.0](https://github.com/Embers-of-the-Fire/lambdot/compare/websocket-v0.0.1...websocket-v0.1.0) (2026-08-29)
 
 

package/README.md

@@ -0,0 +1,145 @@
+# @lambdot/websocket
+
+The generic websocket transport. It owns the socket lifecycle — connect,
+fan out incoming text frames, close on unload — and nothing else: no message
+shapes, no addresses, no content contract. Everything chat-specific is
+deferred to a `WsSpec` supplied by consumers, which makes this a core
+behavior (like `console`), not a chat platform. Protocol packages
+(`@lambdot/protocol-qq`, …) ride this transport by supplying their own
+specs.
+
+The transport is a **service plugin, not a stream**: `wsTransport(name)`
+emits the live `WsConnection` as its namespace value under `name`. The
+`wsInput(name, spec)` / `wsOutput(name, spec)` factories build a platform's
+two halves from the spec, declaring the connection in their input — wiring
+them before the transport is a compile error, because the `mapping`
+parameter is typed as the namespaces visible so far. The socket opens when
+the transport activates and closes when the composition stops.
+
+The name is a parameter, so instances multiply: distinct names compose side
+by side (`wsPlatform("wsecho-a", spec)` next to `wsPlatform("wsecho-b", spec)`),
+and several websocket platforms share one kernel, each platform's input and
+output mapping its own transport's connection.
+
+## Usage
+
+Prefer the bundle. `wsPlatform(name, spec)` builds one websocket platform as
+a triple of plugins — they stay separate so feature plugins can be wired
+between the input (whose message stream is `use`d) and the output (which is
+terminal and always wired last). The transport and output are usually
+`bind`ed, keeping them internal to the chain:
+
+```ts
+import type { Message, Stream } from "@lambdot/core";
+import { createKernel, definePlugin, mapStream } from "@lambdot/core";
+import { wsPlatform } from "@lambdot/websocket";
+
+import { echoSpec, type WsEchoAddress } from "./echo-spec.ts";
+
+const reply = definePlugin({
+    name: "reply",
+    apply(input: { wsecho: Stream<Message<string, WsEchoAddress>> }) {
+        return mapStream(input.wsecho, (event) => ({
+            address: event.address,
+            content: `echo: ${event.payload}`,
+        }));
+    },
+});
+
+const wsecho = wsPlatform("wsecho", echoSpec);
+
+const kernel = createKernel()
+    .bind(wsecho.transport, { option: { url } })
+    .use(wsecho.input, { mapping: (ctx) => ({ connection: ctx["wsecho/transport"] }) })
+    // identity wiring: reply's input keys already match the visible ctx
+    .use(reply)
+    .bind(wsecho.output, {
+        mapping: (ctx) => ({ connection: ctx["wsecho/transport"], commands: ctx.reply }),
+    });
+```
+
+Reach for the individual `wsTransport` / `wsInput` / `wsOutput` factories
+when a kernel hosts several tagged websocket platforms and the triples must
+interleave with other plugins — the factories the bundle wraps stay exported
+for exactly that. Each output filters the shared command stream back down to
+its own platform tag, so `address.platform` routes every reply out the
+socket it arrived on:
+
+```ts
+const wsechoA = wsPlatform("wsecho-a", echoSpec("a"));
+const wsechoB = wsPlatform("wsecho-b", echoSpec("b"));
+
+const kernel = createKernel()
+    .bind(wsechoA.transport, { option: { url: urlA } })
+    .use(wsechoA.input, { mapping: (ctx) => ({ connection: ctx["wsecho-a/transport"] }) })
+    .bind(wsechoB.transport, { option: { url: urlB } })
+    .use(wsechoB.input, { mapping: (ctx) => ({ connection: ctx["wsecho-b/transport"] }) })
+    .use(reply)
+    .bind(wsechoA.output, {
+        mapping: (ctx) => ({
+            connection: ctx["wsecho-a/transport"],
+            commands: filterStream(
+                ctx.reply,
+                (cmd): cmd is Command<AddressA, string> => cmd.address.platform === "wsecho-a",
+            ),
+        }),
+    })
+    .bind(wsechoB.output, {/* ...same for "wsecho-b"... */});
+```
+
+A concrete platform supplies one `WsSpec` — platform tag, address shape,
+frame codec — and nothing else:
+
+```ts
+import type { Address } from "@lambdot/core";
+import type { WsSpec } from "@lambdot/websocket";
+
+export type WsEchoAddress = Address<"wsecho">;
+
+export const echoSpec: WsSpec<"wsecho", WsEchoAddress, string, string> = {
+    platform: "wsecho",
+    decode: (data) => ({ payload: data, address: { platform: "wsecho" } }),
+    encode: (content) => content,
+};
+```
+
+`decode` may return `null` to ignore a frame. Adding a second platform
+costs one spec object, ~5 lines; the transport, factories, and feature
+plugins don't change.
+
+## API
+
+- `wsPlatform(name, spec)` — bundle a transport and the input/output halves
+  built from `spec` into a `WsPlatform` triple (`{ transport, input, output }`).
+  The transport is named `${name}/transport`, the input `name`, the output
+  `${name}/output`.
+- `wsTransport(name)` — the general half: connection lifecycle only. Config
+  is `{ url }` (passed via `option`); emits the live `WsConnection` under
+  the name.
+- `wsInput(name, spec)` — subscribes to the connection, decodes each frame,
+  and emits a shared `Stream<Message<TPayload, TAddress>>` of the decoded
+  messages.
+- `wsOutput(name, spec)` — consumes a `Stream<Command<TAddress, TContent>>`
+  and sends each command's encoded content through the connection. Terminal:
+  wire it last, after the features whose reply streams it consumes.
+- `WsSpec<TPlatform, TAddress, TPayload, TContent>` — the deferred behavior
+  slot: `platform`, plus the `decode` / `encode` frame codec.
+- `WsConnection` — the shared transport service: `url`, `send(data)`,
+  `onMessage(listener)` (text frames only; binary frames are dropped).
+- `WsTransportConfig` — `{ readonly url: string }`.
+
+## Examples
+
+- [../../../examples/websocket-bot](../../../examples/websocket-bot) — one platform
+  end to end: a raw driver round-trips through server, transport, input,
+  reply feature, and output.
+- [../../../examples/dual-websocket-bot](../../../examples/dual-websocket-bot) — two
+  tagged platforms sharing one kernel under distinct names, each output
+  filtering the shared command stream by `address.platform`.
+
+Protocol packages under `packages/protocol/` ride this transport, supplying
+their wire protocol's address type and frame codec as a `WsSpec`.
+
+## License
+
+Dual-licensed under [Apache-2.0](../../../LICENSE-APACHE) and [MIT](../../../LICENSE-MIT).

package/package.json

@@ -1,14 +1,19 @@
 {
-    "name": "@lambdot/websocket",
-    "version": "0.1.0",
-    "type": "module",
-    "exports": {
-        ".": "./src/index.ts"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "dependencies": {
-        "@lambdot/core": "workspace:*"
-    }
-}
+  "name": "@lambdot/websocket",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Embers-of-the-Fire/lambdot",
+    "directory": "packages/core/websocket"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@lambdot/core": "0.2.0"
+  }
+}

package/src/index.ts

@@ -1,23 +1,17 @@
-import type {
-    Address,
-    Disposer,
-    EventDef,
-    FeaturePlugin,
-    InputPlugin,
-    OutputPlugin,
-} from "@lambdot/core";
+import type { Address, Command, Message, Plugin, Stream } from "@lambdot/core";
+import { channel, definePlugin, message, pumpStream, shareStream } from "@lambdot/core";
 
 /**
- * The shared transport service, provided as a typed capability. Owns the
- * socket; platform plugins consume it — the transport itself knows nothing
- * about platforms, addresses, or event kinds.
+ * The shared transport service, emitted as a plugin's output value. Owns the
+ * socket; platform plugins consume it through their input — the transport
+ * itself knows nothing about platforms, addresses, or message shapes.
  */
 export interface WsConnection {
     readonly url: string;
     /** Send a text frame. */
     send(data: string): void;
-    /** Subscribe to incoming text frames. Returns an unsubscribe disposer. */
-    onMessage(listener: (data: string) => void): Disposer;
+    /** Subscribe to incoming text frames. The listener remains active for the connection lifetime. */
+    onMessage(listener: (data: string) => void): void;
 }
 
 export interface WsTransportConfig {
@@ -25,28 +19,16 @@ export interface WsTransportConfig {
 }
 
 /**
- * The typed capability contract shared by a transport and its consumers,
- * parameterized by capability name: the transport declares it as
- * `TProvides`, the platform factories as `TInjects`. Distinct names fold
- * side by side (`WsCapability<"ws-discord"> & WsCapability<"ws-qq">`), so
- * several websocket platforms can share one kernel — the kernel rejects a
- * duplicate capability name at runtime, and the type fold makes each
- * consumer read back its own connection with no casts.
+ * The general half: connection lifecycle only. Emits the live connection as
+ * its output value; platform plugins declare it as their input. The socket
+ * opens at activation and closes when the composition stops.
  */
-export type WsCapability<TCap extends string> = { readonly [K in TCap]: WsConnection };
-
-/**
- * The general half: connection lifecycle only. Provides the live connection
- * as a typed value under the given capability name (folded into the kernel
- * context as `ctx[capability]`); platform plugins activate once it is
- * available via `inject: [capability]`.
- */
-export function wsTransport<TCap extends string>(
-    capability: TCap,
-): FeaturePlugin<{}, {}, undefined, WsTransportConfig, `ws-transport:${TCap}`, WsCapability<TCap>> {
-    return {
-        name: `ws-transport:${capability}`,
-        async apply(ctx, config) {
+export function wsTransport<const TName extends string>(
+    name: TName,
+): Plugin<void, WsConnection, WsTransportConfig, TName> {
+    return definePlugin({
+        name,
+        async apply(_input, scope, config) {
             const socket = new WebSocket(config.url);
             await new Promise<void>((resolve, reject) => {
                 socket.addEventListener("open", () => resolve(), { once: true });
@@ -58,199 +40,161 @@ export function wsTransport<TCap extends string>(
                     },
                 );
             });
-
-            const listeners = new Set<(data: string) => void>();
-            socket.addEventListener("message", (event) => {
-                if (typeof event.data !== "string") return;
-                for (const listener of listeners) listener(event.data);
+            scope.onDispose(() => {
+                socket.close();
             });
 
-            const connection: WsConnection = {
+            return {
                 url: config.url,
                 send: (data) => socket.send(data),
                 onMessage(listener) {
-                    listeners.add(listener);
-                    return () => {
-                        listeners.delete(listener);
-                    };
+                    socket.addEventListener("message", (event) => {
+                        if (typeof event.data === "string") listener(event.data);
+                    });
                 },
             };
-
-            // The kernel's `provide` keeps its value parameter behind a
-            // conditional type that stays deferred for a generic capability
-            // name; `WsCapability<TCap>` already ties this name to
-            // `WsConnection`, so pin the call down here.
-            const unprovide = (ctx.provide as (name: TCap, value: WsConnection) => Disposer).call(
-                ctx,
-                capability,
-                connection,
-            );
-            return () => {
-                socket.close();
-                void unprovide();
-            };
         },
-    };
+    });
 }
 
 /**
  * The deferred behavior slot: everything the generic transport cannot know —
- * the platform tag, the event kind, and the frame codec. A concrete platform
- * (discord, qq, ...) supplies one of these to the factories below.
+ * the platform tag, the address shape, and the frame codec. A concrete
+ * platform (discord, qq, ...) supplies one of these to the factories below.
  */
 export interface WsSpec<
     TPlatform extends string,
     TAddress extends Address<TPlatform>,
     TPayload,
     TContent,
-    TKind extends string,
 > {
     readonly platform: TPlatform;
-    readonly kind: TKind;
-    /** Decode an incoming frame into an event, or null to ignore the frame. */
+    /** Decode an incoming frame into a message, or null to ignore the frame. */
     decode(data: string): { payload: TPayload; address: TAddress } | null;
     /** Encode outgoing content into a text frame. */
     encode(content: TContent, address: TAddress): string;
 }
 
 /**
- * Build the input half of a websocket platform from its spec, consuming the
- * connection provided under `capability` by a `wsTransport`. Event kinds
- * flow through the generic fold, so registration-order gating still applies
- * to the concrete instantiation.
+ * The input half of a websocket platform: consumes the connection and emits
+ * the stream of decoded messages. Wire the connection with a mapping from
+ * the transport's namespace.
  */
 export function wsInput<
-    TCap extends string,
+    const TName extends string,
     TPlatform extends string,
     TAddress extends Address<TPlatform>,
     TPayload,
     TContent,
-    TKind extends string,
 >(
-    capability: TCap,
-    spec: WsSpec<TPlatform, TAddress, TPayload, TContent, TKind>,
-): InputPlugin<
-    { [K in TKind]: EventDef<TPayload, TAddress> },
-    void,
-    `${TPlatform}-input`,
-    {},
-    WsCapability<TCap>
-> {
-    return {
-        role: "input",
-        name: `${spec.platform}-input`,
-        inject: [capability],
-        apply(ctx) {
-            return ctx[capability].onMessage((data) => {
+    name: TName,
+    spec: WsSpec<TPlatform, TAddress, TPayload, TContent>,
+): Plugin<{ connection: WsConnection }, Stream<Message<TPayload, TAddress>>, void, TName> {
+    return definePlugin({
+        name,
+        apply(input, scope) {
+            const messages = channel<Message<TPayload, TAddress>>();
+            input.connection.onMessage((data) => {
                 const decoded = spec.decode(data);
-                if (decoded) void ctx.ingest(spec.kind, decoded.payload, decoded.address);
+                if (decoded) messages.push(message(decoded.payload, decoded.address));
             });
+            scope.onDispose(() => {
+                messages.close();
+            });
+            // Shared: several consumers may subscribe to the message stream.
+            return shareStream(messages.stream);
         },
-    };
+    });
 }
 
-/** Build the output half of a websocket platform from its spec. */
+/**
+ * The output half of a websocket platform: consumes a command stream and
+ * sends each command's encoded content through the connection. Terminal —
+ * wire it last, after the features whose reply streams it consumes.
+ */
 export function wsOutput<
-    TCap extends string,
+    const TName extends string,
     TPlatform extends string,
     TAddress extends Address<TPlatform>,
     TPayload,
     TContent,
-    TKind extends string,
 >(
-    capability: TCap,
-    spec: WsSpec<TPlatform, TAddress, TPayload, TContent, TKind>,
-): OutputPlugin<
-    TPlatform,
-    TAddress,
-    TContent,
+    name: TName,
+    spec: WsSpec<TPlatform, TAddress, TPayload, TContent>,
+): Plugin<
+    { connection: WsConnection; commands: Stream<Command<TAddress, TContent>> },
+    void,
     void,
-    `${TPlatform}-output`,
-    {},
-    WsCapability<TCap>
+    TName
 > {
-    let connection: WsConnection | undefined;
-    return {
-        role: "output",
-        name: `${spec.platform}-output`,
-        platform: spec.platform,
-        inject: [capability],
-        send(to, content) {
-            if (!connection) throw new Error(`output "${spec.platform}" is not active`);
-            connection.send(spec.encode(content, to));
-        },
-        apply(ctx) {
-            connection = ctx[capability];
-            return () => {
-                connection = undefined;
-            };
+    return definePlugin({
+        name,
+        apply(input, scope) {
+            const { connection } = input;
+            scope.onDispose(
+                pumpStream(
+                    input.commands,
+                    (cmd) => connection.send(spec.encode(cmd.content, cmd.address)),
+                    (error) => scope.onError(error),
+                ),
+            );
         },
-    };
+    });
 }
 
 /**
- * One websocket platform, bundled: the transport that owns the socket under
- * `capability`, plus the input/output halves built from `spec`. The triple
- * stays separate (rather than one fused plugin) so the type fold can keep
- * enforcing registration order — transport before the halves that inject it.
- *
+ * One websocket platform, bundled as three leaves. The transport and output
+ * are usually `bind`ed (internal wiring); the input's message stream is
+ * `use`d (exposed to features). The output is terminal, so it is always
+ * wired last:
+
  * ```ts
- * const discord = wsPlatform("ws-discord", discordSpec);
+ * const wsecho = wsPlatform("wsecho", echoSpec);
  * createKernel()
- *     .use(discord.transport, { url })
- *     .use(discord.input)
- *     .use(discord.output);
+ *     .bind(wsecho.transport, { option: { url } })
+ *     .use(wsecho.input, { mapping: (ctx) => ({ connection: ctx["wsecho/transport"] }) })
+ *     .use(reply)
+ *     .bind(wsecho.output, {
+ *         mapping: (ctx) => ({ connection: ctx["wsecho/transport"], commands: ctx.reply }),
+ *     });
  * ```
  */
 export interface WsPlatform<
-    TCap extends string,
+    TName extends string,
     TPlatform extends string,
     TAddress extends Address<TPlatform>,
     TPayload,
     TContent,
-    TKind extends string,
 > {
-    readonly transport: FeaturePlugin<
-        {},
-        {},
-        undefined,
-        WsTransportConfig,
-        `ws-transport:${TCap}`,
-        WsCapability<TCap>
-    >;
-    readonly input: InputPlugin<
-        { [K in TKind]: EventDef<TPayload, TAddress> },
+    readonly transport: Plugin<void, WsConnection, WsTransportConfig, `${TName}/transport`>;
+    readonly input: Plugin<
+        { connection: WsConnection },
+        Stream<Message<TPayload, TAddress>>,
         void,
-        `${TPlatform}-input`,
-        {},
-        WsCapability<TCap>
+        TName
     >;
-    readonly output: OutputPlugin<
-        TPlatform,
-        TAddress,
-        TContent,
+    readonly output: Plugin<
+        { connection: WsConnection; commands: Stream<Command<TAddress, TContent>> },
+        void,
         void,
-        `${TPlatform}-output`,
-        {},
-        WsCapability<TCap>
+        `${TName}/output`
     >;
 }
 
-/** Build a whole websocket platform (transport + input + output) from a capability name and a spec. */
+/** Build a whole websocket platform (transport + input + output) from a name and a spec. */
 export function wsPlatform<
-    TCap extends string,
+    const TName extends string,
     TPlatform extends string,
     TAddress extends Address<TPlatform>,
     TPayload,
     TContent,
-    TKind extends string,
 >(
-    capability: TCap,
-    spec: WsSpec<TPlatform, TAddress, TPayload, TContent, TKind>,
-): WsPlatform<TCap, TPlatform, TAddress, TPayload, TContent, TKind> {
+    name: TName,
+    spec: WsSpec<TPlatform, TAddress, TPayload, TContent>,
+): WsPlatform<TName, TPlatform, TAddress, TPayload, TContent> {
     return {
-        transport: wsTransport(capability),
-        input: wsInput(capability, spec),
-        output: wsOutput(capability, spec),
+        transport: wsTransport(`${name}/transport`),
+        input: wsInput(name, spec),
+        output: wsOutput(`${name}/output`, spec),
     };
 }