@venn-lang/ws 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# @venn-lang/ws
+
+> The `ws` namespace: open a WebSocket, send, wait for a message, close.
+
+Venn's grammar knows no verbs. `@venn-lang/ws` registers the `ws` namespace with the runtime, so
+`ws.connect` resolves to an action and `ws.expect` hands back a typed message. The socket itself lives
+behind the `WsClient` port, not in a handle the flow carries around, so a host swaps the whole
+transport by binding a different implementation.
+
+## Install
+
+Nothing to install yet. The package is unpublished (version `0.0.0`) and ships inside
+`@venn-lang/stdlib`, which the `venn` CLI and the language server both load. A `.vn` file declares it:
+
+```ruby
+use "venn/ws"
+```
+
+## Usage
+
+```ruby
+module demo.stream
+
+use "venn/ws"
+
+flow "Stock stream" {
+  step "the socket accepts the subscription" {
+    ws.connect "wss://example.test/stream" { auth: "token" }
+    ws.send { type: "subscribe", data: { sku: "sku-42" } }
+    ws.close
+  }
+}
+```
+
+## API
+
+Everything below is exported from the package barrel.
+
+| Export | What it is |
+| --- | --- |
+| `wsPlugin` (also the default export) | The `PluginDefinition`: namespace `ws`, `requires: ["net"]`. |
+| `WsClientPort` | `Port<WsClient>`, id `venn.port.ws-client`, version 1, methods `connect`, `send`, `expect`, `close`. |
+| `createFakeWsClient({ incoming })` | The double: preloaded messages in, sent messages recorded on `sent`. |
+| `createRealWsClient()` | The real client. Out of scope for this build: every method throws `VN8090`. |
+| `messageSchema` | The Zod schema behind the nominal `Message` type the plugin registers. |
+| `wsTypeDefs` | What the plugin publishes to the checker, as `TypeSpec` data. |
+
+Types: `WsClient`, `FakeWsClient`, `WsConnectArgs`, `WsExpectQuery`, `Message`.
+
+## Verbs
+
+| Verb | Shape | Result |
+| --- | --- | --- |
+| `ws.connect` | `ws.connect url { auth }` | nothing |
+| `ws.send` | `ws.send { type, data }` | nothing |
+| `ws.expect` | `ws.expect { type }` or `ws.expect { where }` | `ws.Message` |
+| `ws.close` | `ws.close` | nothing |
+
+Only `ws.connect` has a positional argument, the URL. For `ws.send` the message *is* the options map.
+For `ws.expect` the query is: `type` matches the message type, `where` matches field by field, and the
+first message that satisfies it is consumed and returned.
+
+## Matchers and types
+
+The plugin publishes one type, `ws.Message`: an open record with optional `type` and `data`. It is
+open because `expect { where: … }` matches on whatever fields a message actually carries beyond those
+two.
+
+A matcher named `type` is registered against `Message`, but `type` is a grammar keyword, so it cannot
+be spelled after `expect` today. Read the field instead:
+
+```ruby
+const msg = ws.expect { type: "ack" }
+expect msg.type == "ack"
+```
+
+## Ports and conformance
+
+`WsClient` has the two implementations every port has, and both run
+`src/clients/ws-client.suite.ts`:
+
+- `createRealWsClient()` is a stub in this build. Every method raises `VN8090`.
+- `createFakeWsClient({ incoming })` resolves `expect` from a preloaded queue and records every
+  `send` on `sent`, so a test asserts on what the flow put on the wire without a wire:
+
+```ts
+import { createFakeWsClient } from "@venn-lang/ws";
+
+const client = createFakeWsClient({ incoming: [{ type: "ack", data: { ok: true } }] });
+await client.connect({ url: "wss://example.test", auth: "token" });
+await client.send({ type: "ping", data: 1 });
+// client.sent === [{ type: "ping", data: 1 }]
+```
+
+`expect` prefers the matching message over the first one, and falls back to the first when nothing
+matches. An empty queue raises `VN8091`.
+
+That matters for `ws.expect` in a `.vn` file: `@venn-lang/stdlib` binds `createFakeWsClient({ incoming: [] })`
+by default, so the verb has nothing to resolve and fails with `VN8091` until a host binds a client
+seeded with messages.
+
+## See also
+
+- [`@venn-lang/mqtt`](../std-mqtt), the same shape over topics rather than a socket.
+- [`@venn-lang/http`](../std-http), the reference plugin, with a real client and a real server.
+- [`@venn-lang/stdlib`](../stdlib) for the plugin list and the default port bindings.

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+import { Port } from "@venn-lang/contracts";
+import { PluginDefinition, ZodType } from "@venn-lang/sdk";
+import { TypeSpec } from "@venn-lang/types";
+//#region src/types/message.d.ts
+/**
+ * Runtime validation for `ws.Message`, registered on the plugin.
+ *
+ * Pairs with `wsTypeDefs.Message`, which tells the checker the same shape: this
+ * one guards a value, that one types an expression.
+ */
+declare const messageSchema: ZodType;
+//#endregion
+//#region src/types/message.types.d.ts
+/**
+ * One message on the socket, and what `ws.expect` hands back.
+ *
+ * Both fields are optional because a peer is free to send whatever it likes;
+ * `where` queries match on fields beyond these two.
+ */
+interface Message {
+  type?: string;
+  data?: unknown;
+}
+//#endregion
+//#region src/types/type-defs.d.ts
+/**
+ * The types the plugin publishes to flows, as `ws.Message`.
+ *
+ * Mirrors `Message` in `message.types.ts` and the Zod schema beside it: the
+ * schema guards a value at runtime, this tells the checker what `ws.expect`
+ * handed back. Open, because `expect { where: … }` matches on whatever fields a
+ * message carries beyond `type` and `data`.
+ */
+declare const wsTypeDefs: Readonly<Record<string, TypeSpec>>;
+//#endregion
+//#region src/port/ws-client.types.d.ts
+/** What `ws.connect` passes on: the URL it was given, and any `auth` from the opts map. */
+interface WsConnectArgs {
+  url: string;
+  auth?: unknown;
+}
+/**
+ * Which incoming message `ws.expect` is waiting for: one with this `type`, or
+ * one whose fields match every entry in `where`. Both empty means the next one.
+ */
+interface WsExpectQuery {
+  type?: string;
+  where?: Record<string, unknown>;
+}
+/**
+ * One WebSocket connection: open it, write to it, wait on it, close it.
+ *
+ * The port holds the socket, which is why no method takes a handle: a flow says
+ * `ws.send { … }` and the implementation knows which connection it means.
+ *
+ * Two implementations: `createRealWsClient` and `createFakeWsClient`.
+ */
+interface WsClient {
+  connect(args: WsConnectArgs): Promise<void>;
+  send(message: Message): Promise<void>;
+  expect(query: WsExpectQuery): Promise<Message>;
+  close(): Promise<void>;
+}
+/** A `WsClient` that also lets a test read back what the flow sent. */
+interface FakeWsClient extends WsClient {
+  /** Every message handed to `send`, in order. */
+  readonly sent: readonly Message[];
+}
+//#endregion
+//#region src/port/ws-client.port.d.ts
+/**
+ * The port descriptor every `ws` verb resolves through `ctx.port(...)`.
+ *
+ * Declares the `net` capability, so a host that cannot open sockets refuses the
+ * binding at load time with a readable diagnostic.
+ */
+declare const WsClientPort: Port<WsClient>;
+//#endregion
+//#region src/clients/fake-client.d.ts
+/**
+ * The double: no socket, and `expect` resolves at once instead of waiting.
+ *
+ * @param args.incoming Messages the peer is pretending to have sent, in order.
+ * @returns A client whose `sent` array is everything the flow wrote.
+ * @throws VN8091 from `expect` once the incoming queue is empty.
+ */
+declare function createFakeWsClient(args?: {
+  incoming?: Message[];
+}): FakeWsClient;
+//#endregion
+//#region src/clients/real-client.d.ts
+/**
+ * The real WebSocket client. Not implemented in this build.
+ *
+ * It exists so the port has its second implementation and the failure is a named
+ * Venn error rather than a missing method.
+ *
+ * @throws VN8090 from every method.
+ */
+declare function createRealWsClient(): WsClient;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `ws` namespace: `connect`, `send`, `expect`, `close`, the `type` matcher
+ * and the `ws.Message` type.
+ *
+ * Requires the `net` capability, so a host without it refuses the plugin at load
+ * time rather than failing mid-flow.
+ */
+declare const wsPlugin: PluginDefinition;
+//#endregion
+export { type FakeWsClient, type Message, type WsClient, WsClientPort, type WsConnectArgs, type WsExpectQuery, createFakeWsClient, createRealWsClient, wsPlugin as default, wsPlugin, messageSchema, wsTypeDefs };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types/message.ts","../src/types/message.types.ts","../src/types/type-defs.ts","../src/port/ws-client.types.ts","../src/port/ws-client.port.ts","../src/clients/fake-client.ts","../src/clients/real-client.ts","../src/plugin.ts"],"mappings":";;;;;;;;;;cAQa,eAAe;;;;;;;;;UCFX;EACf;EACA;;;;;;;;;;;;cCEW,YAAY,SAAS,eAAe;;;;UCPhC;EACf;EACA;;;;;;UAOe;EACf;EACA,QAAQ;;;;;;;;;;UAWO;EACf,QAAQ,MAAM,gBAAgB;EAC9B,KAAK,SAAS,UAAU;EACxB,OAAO,OAAO,gBAAgB,QAAQ;EACtC,SAAS;;;UAIM,qBAAqB;;WAE3B,eAAe;;;;;;;;;;cC1Bb,cAAc,KAAK;;;;;;;;;;iBCEhB,mBAAmB;EAAQ,WAAW;IAAmB;;;;;;;;;;;iBCAzD,sBAAsB;;;;;;;;;;cCCzB,UAAU"}

package/dist/index.js

@@ -0,0 +1,224 @@
+import { VennError } from "@venn-lang/contracts";
+import { arg, defineAction, defineMatcher, definePlugin, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+//#region src/clients/fake-client.ts
+/**
+* The double: no socket, and `expect` resolves at once instead of waiting.
+*
+* @param args.incoming Messages the peer is pretending to have sent, in order.
+* @returns A client whose `sent` array is everything the flow wrote.
+* @throws VN8091 from `expect` once the incoming queue is empty.
+*/
+function createFakeWsClient(args = {}) {
+	const incoming = [...args.incoming ?? []];
+	const sent = [];
+	return {
+		sent,
+		connect: async () => {},
+		send: async (message) => void sent.push(message),
+		expect: async (query) => takeMatch(incoming, query),
+		close: async () => {}
+	};
+}
+/**
+* Consume the first message matching `query`, or the head of the queue when
+* none match, so a mistyped query still advances instead of deadlocking.
+*/
+function takeMatch(queue, query) {
+	const index = queue.findIndex((message) => matches(message, query));
+	const found = queue.splice(index >= 0 ? index : 0, 1)[0];
+	if (!found) throw noMessage();
+	return found;
+}
+function matches(message, query) {
+	if (query.type !== void 0) return message.type === query.type;
+	if (query.where) return matchesWhere(message, query.where);
+	return true;
+}
+function matchesWhere(message, where) {
+	const record = message;
+	return Object.entries(where).every(([key, value]) => equal(record[key], value));
+}
+function equal(a, b) {
+	return JSON.stringify(a) === JSON.stringify(b);
+}
+function noMessage() {
+	return new VennError({
+		code: "VN8091",
+		message: "No WebSocket message available to match."
+	});
+}
+//#endregion
+//#region src/clients/real-client.ts
+/**
+* The real WebSocket client. Not implemented in this build.
+*
+* It exists so the port has its second implementation and the failure is a named
+* Venn error rather than a missing method.
+*
+* @throws VN8090 from every method.
+*/
+function createRealWsClient() {
+	return {
+		connect: notImplemented,
+		send: notImplemented,
+		expect: notImplemented,
+		close: notImplemented
+	};
+}
+function notImplemented() {
+	throw new VennError({
+		code: "VN8090",
+		message: "WebSocket real client not implemented in this build"
+	});
+}
+//#endregion
+//#region src/port/ws-client.port.ts
+/**
+* The port descriptor every `ws` verb resolves through `ctx.port(...)`.
+*
+* Declares the `net` capability, so a host that cannot open sockets refuses the
+* binding at load time with a readable diagnostic.
+*/
+const WsClientPort = {
+	id: "venn.port.ws-client",
+	version: 1,
+	requires: ["net"],
+	methods: [
+		"connect",
+		"send",
+		"expect",
+		"close"
+	]
+};
+//#endregion
+//#region src/actions/close.ts
+/** `ws.close`: hang up the connection the port is holding. Takes nothing. */
+const wsClose = defineAction({
+	name: "close",
+	doc: "Close the WebSocket connection.",
+	result: t.void,
+	run: (ctx) => ctx.port(WsClientPort).close()
+});
+/**
+* `ws.connect "wss://…" { auth: token }`: open the socket.
+*
+* Returns nothing, because the port owns the connection. That is what lets
+* `ws.send` and `ws.close` reach it without the flow carrying a handle.
+*/
+const wsConnect = defineAction({
+	name: "connect",
+	doc: "Open a WebSocket connection.",
+	params: z.object({ auth: z.unknown().optional() }),
+	args: [arg("url", t.string, "Where to connect: `ws://` or `wss://`.")],
+	result: t.void,
+	run: (ctx, input) => ctx.port(WsClientPort).connect({
+		url: String(input.args[0] ?? ""),
+		auth: input.params.auth
+	})
+});
+/**
+* `ws.expect { type: "ack" }` or `ws.expect { where: { … } }`: wait for the next
+* message that matches.
+*
+* The query is the options map, so nothing is positional. The result is typed as
+* `ws.Message`, which is what lets `expect res type "ack"` know its subject.
+*/
+const wsExpect = defineAction({
+	name: "expect",
+	doc: "Wait for the next matching incoming message.",
+	params: z.object({
+		type: z.string().optional(),
+		where: z.record(z.string(), z.unknown()).optional()
+	}),
+	result: t.ref("ws.Message"),
+	run: (ctx, input) => ctx.port(WsClientPort).expect(input.params)
+});
+//#endregion
+//#region src/actions/index.ts
+/** The ws namespace's verbs. Adding one is a new file plus a single line here. */
+const wsActions = [
+	wsConnect,
+	defineAction({
+		name: "send",
+		doc: "Send a message over the WebSocket.",
+		params: z.object({
+			type: z.string().optional(),
+			data: z.unknown().optional()
+		}),
+		result: t.void,
+		run: (ctx, input) => ctx.port(WsClientPort).send(input.params)
+	}),
+	wsExpect,
+	wsClose
+];
+//#endregion
+//#region src/matchers/of-type.ts
+/** `expect res type "ack"`: passes if the message carries exactly that `type`. */
+const ofType = defineMatcher({
+	name: "type",
+	args: [arg("type", t.string, "The message type expected: `text`, `binary`.")],
+	appliesTo: "Message",
+	test: ({ subject, args }) => messageType(subject) === String(args[0]),
+	message: ({ args }) => `expected the message to have type "${String(args[0])}"`
+});
+function messageType(subject) {
+	return subject.type;
+}
+//#endregion
+//#region src/matchers/index.ts
+const wsMatchers = [ofType];
+//#endregion
+//#region src/types/message.ts
+/**
+* Runtime validation for `ws.Message`, registered on the plugin.
+*
+* Pairs with `wsTypeDefs.Message`, which tells the checker the same shape: this
+* one guards a value, that one types an expression.
+*/
+const messageSchema = z.object({
+	type: z.string().optional(),
+	data: z.unknown().optional()
+});
+//#endregion
+//#region src/types/type-defs.ts
+/**
+* The types the plugin publishes to flows, as `ws.Message`.
+*
+* Mirrors `Message` in `message.types.ts` and the Zod schema beside it: the
+* schema guards a value at runtime, this tells the checker what `ws.expect`
+* handed back. Open, because `expect { where: … }` matches on whatever fields a
+* message carries beyond `type` and `data`.
+*/
+const wsTypeDefs = { 
+/** One message off the socket, as `ws.expect` gives it back. */
+Message: t.record({
+	type: t.string,
+	data: t.dynamic
+}, {
+	optional: ["type", "data"],
+	open: true
+}) };
+//#endregion
+//#region src/plugin.ts
+/**
+* The `ws` namespace: `connect`, `send`, `expect`, `close`, the `type` matcher
+* and the `ws.Message` type.
+*
+* Requires the `net` capability, so a host without it refuses the plugin at load
+* time rather than failing mid-flow.
+*/
+const wsPlugin = definePlugin({
+	name: "venn/ws",
+	version: "0.0.0",
+	namespace: "ws",
+	requires: ["net"],
+	actions: wsActions,
+	matchers: wsMatchers,
+	types: { Message: messageSchema },
+	typeDefs: wsTypeDefs
+});
+//#endregion
+export { WsClientPort, createFakeWsClient, createRealWsClient, wsPlugin as default, wsPlugin, messageSchema, wsTypeDefs };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["params","params"],"sources":["../src/clients/fake-client.ts","../src/clients/real-client.ts","../src/port/ws-client.port.ts","../src/actions/close.ts","../src/actions/connect.ts","../src/actions/expect.ts","../src/actions/send.ts","../src/actions/index.ts","../src/matchers/of-type.ts","../src/matchers/index.ts","../src/types/message.ts","../src/types/type-defs.ts","../src/plugin.ts"],"sourcesContent":["import { VennError } from \"@venn-lang/contracts\";\nimport type { FakeWsClient, WsExpectQuery } from \"../port/index.js\";\nimport type { Message } from \"../types/index.js\";\n\n/**\n * The double: no socket, and `expect` resolves at once instead of waiting.\n *\n * @param args.incoming Messages the peer is pretending to have sent, in order.\n * @returns A client whose `sent` array is everything the flow wrote.\n * @throws VN8091 from `expect` once the incoming queue is empty.\n */\nexport function createFakeWsClient(args: { incoming?: Message[] } = {}): FakeWsClient {\n  const incoming = [...(args.incoming ?? [])];\n  const sent: Message[] = [];\n  return {\n    sent,\n    connect: async () => {},\n    send: async (message) => void sent.push(message),\n    expect: async (query) => takeMatch(incoming, query),\n    close: async () => {},\n  };\n}\n\n/**\n * Consume the first message matching `query`, or the head of the queue when\n * none match, so a mistyped query still advances instead of deadlocking.\n */\nfunction takeMatch(queue: Message[], query: WsExpectQuery): Message {\n  const index = queue.findIndex((message) => matches(message, query));\n  const found = queue.splice(index >= 0 ? index : 0, 1)[0];\n  if (!found) throw noMessage();\n  return found;\n}\n\nfunction matches(message: Message, query: WsExpectQuery): boolean {\n  if (query.type !== undefined) return message.type === query.type;\n  if (query.where) return matchesWhere(message, query.where);\n  return true;\n}\n\nfunction matchesWhere(message: Message, where: Record<string, unknown>): boolean {\n  const record = message as Record<string, unknown>;\n  return Object.entries(where).every(([key, value]) => equal(record[key], value));\n}\n\nfunction equal(a: unknown, b: unknown): boolean {\n  return JSON.stringify(a) === JSON.stringify(b);\n}\n\nfunction noMessage(): VennError {\n  return new VennError({ code: \"VN8091\", message: \"No WebSocket message available to match.\" });\n}\n","import { VennError } from \"@venn-lang/contracts\";\nimport type { WsClient } from \"../port/index.js\";\n\n/**\n * The real WebSocket client. Not implemented in this build.\n *\n * It exists so the port has its second implementation and the failure is a named\n * Venn error rather than a missing method.\n *\n * @throws VN8090 from every method.\n */\nexport function createRealWsClient(): WsClient {\n  return {\n    connect: notImplemented,\n    send: notImplemented,\n    expect: notImplemented,\n    close: notImplemented,\n  };\n}\n\nfunction notImplemented(): never {\n  throw new VennError({\n    code: \"VN8090\",\n    message: \"WebSocket real client not implemented in this build\",\n  });\n}\n","import type { Port } from \"@venn-lang/contracts\";\nimport type { WsClient } from \"./ws-client.types.js\";\n\n/**\n * The port descriptor every `ws` verb resolves through `ctx.port(...)`.\n *\n * Declares the `net` capability, so a host that cannot open sockets refuses the\n * binding at load time with a readable diagnostic.\n */\nexport const WsClientPort: Port<WsClient> = {\n  id: \"venn.port.ws-client\",\n  version: 1,\n  requires: [\"net\"],\n  methods: [\"connect\", \"send\", \"expect\", \"close\"],\n};\n","import { type ActionDefinition, defineAction } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { WsClientPort } from \"../port/index.js\";\n\n/** `ws.close`: hang up the connection the port is holding. Takes nothing. */\nexport const wsClose: ActionDefinition = defineAction({\n  name: \"close\",\n  doc: \"Close the WebSocket connection.\",\n  result: t.void,\n  run: (ctx) => ctx.port(WsClientPort).close(),\n});\n","import { type ActionDefinition, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { WsClientPort } from \"../port/index.js\";\n\nconst params = z.object({ auth: z.unknown().optional() });\n\n/**\n * `ws.connect \"wss://…\" { auth: token }`: open the socket.\n *\n * Returns nothing, because the port owns the connection. That is what lets\n * `ws.send` and `ws.close` reach it without the flow carrying a handle.\n */\nexport const wsConnect: ActionDefinition = defineAction({\n  name: \"connect\",\n  doc: \"Open a WebSocket connection.\",\n  params,\n  args: [arg(\"url\", t.string, \"Where to connect: `ws://` or `wss://`.\")],\n  result: t.void,\n  run: (ctx, input) =>\n    ctx.port(WsClientPort).connect({ url: String(input.args[0] ?? \"\"), auth: input.params.auth }),\n});\n","import { type ActionDefinition, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { WsClientPort } from \"../port/index.js\";\n\nconst params = z.object({\n  type: z.string().optional(),\n  where: z.record(z.string(), z.unknown()).optional(),\n});\n\n/**\n * `ws.expect { type: \"ack\" }` or `ws.expect { where: { … } }`: wait for the next\n * message that matches.\n *\n * The query is the options map, so nothing is positional. The result is typed as\n * `ws.Message`, which is what lets `expect res type \"ack\"` know its subject.\n */\nexport const wsExpect: ActionDefinition = defineAction({\n  name: \"expect\",\n  doc: \"Wait for the next matching incoming message.\",\n  params,\n  result: t.ref(\"ws.Message\"),\n  run: (ctx, input) => ctx.port(WsClientPort).expect(input.params),\n});\n","import { type ActionDefinition, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { WsClientPort } from \"../port/index.js\";\n\nconst params = z.object({ type: z.string().optional(), data: z.unknown().optional() });\n\n/**\n * `ws.send { type: \"ping\", data: 1 }`: write one message.\n *\n * Nothing is positional: the options map is the message, and `params` above is\n * what checks its keys.\n */\nexport const wsSend: ActionDefinition = defineAction({\n  name: \"send\",\n  doc: \"Send a message over the WebSocket.\",\n  params,\n  result: t.void,\n  run: (ctx, input) => ctx.port(WsClientPort).send(input.params),\n});\n","import type { ActionDefinition } from \"@venn-lang/sdk\";\nimport { wsClose } from \"./close.js\";\nimport { wsConnect } from \"./connect.js\";\nimport { wsExpect } from \"./expect.js\";\nimport { wsSend } from \"./send.js\";\n\n/** The ws namespace's verbs. Adding one is a new file plus a single line here. */\nexport const wsActions: ActionDefinition[] = [wsConnect, wsSend, wsExpect, wsClose];\n","import { arg, defineMatcher, type MatcherDefinition } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\n\n/** `expect res type \"ack\"`: passes if the message carries exactly that `type`. */\nexport const ofType: MatcherDefinition = defineMatcher({\n  name: \"type\",\n  args: [arg(\"type\", t.string, \"The message type expected: `text`, `binary`.\")],\n  appliesTo: \"Message\",\n  test: ({ subject, args }) => messageType(subject) === String(args[0]),\n  message: ({ args }) => `expected the message to have type \"${String(args[0])}\"`,\n});\n\nfunction messageType(subject: unknown): string | undefined {\n  return (subject as { type?: string }).type;\n}\n","import type { MatcherDefinition } from \"@venn-lang/sdk\";\nimport { ofType } from \"./of-type.js\";\n\nexport const wsMatchers: MatcherDefinition[] = [ofType];\n","import { type ZodType, z } from \"@venn-lang/sdk\";\n\n/**\n * Runtime validation for `ws.Message`, registered on the plugin.\n *\n * Pairs with `wsTypeDefs.Message`, which tells the checker the same shape: this\n * one guards a value, that one types an expression.\n */\nexport const messageSchema: ZodType = z.object({\n  type: z.string().optional(),\n  data: z.unknown().optional(),\n});\n","import { type TypeSpec, t } from \"@venn-lang/types\";\n\n/**\n * The types the plugin publishes to flows, as `ws.Message`.\n *\n * Mirrors `Message` in `message.types.ts` and the Zod schema beside it: the\n * schema guards a value at runtime, this tells the checker what `ws.expect`\n * handed back. Open, because `expect { where: … }` matches on whatever fields a\n * message carries beyond `type` and `data`.\n */\nexport const wsTypeDefs: Readonly<Record<string, TypeSpec>> = {\n  /** One message off the socket, as `ws.expect` gives it back. */\n  Message: t.record(\n    { type: t.string, data: t.dynamic },\n    { optional: [\"type\", \"data\"], open: true },\n  ),\n};\n","import { definePlugin, type PluginDefinition } from \"@venn-lang/sdk\";\nimport { wsActions } from \"./actions/index.js\";\nimport { wsMatchers } from \"./matchers/index.js\";\nimport { messageSchema, wsTypeDefs } from \"./types/index.js\";\n\n/**\n * The `ws` namespace: `connect`, `send`, `expect`, `close`, the `type` matcher\n * and the `ws.Message` type.\n *\n * Requires the `net` capability, so a host without it refuses the plugin at load\n * time rather than failing mid-flow.\n */\nexport const wsPlugin: PluginDefinition = definePlugin({\n  name: \"venn/ws\",\n  version: \"0.0.0\",\n  namespace: \"ws\",\n  requires: [\"net\"],\n  actions: wsActions,\n  matchers: wsMatchers,\n  types: { Message: messageSchema },\n  typeDefs: wsTypeDefs,\n});\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@venn-lang/ws",
+  "version": "0.1.0",
+  "description": "The ws namespace: open a WebSocket, send, wait for a message, close.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "ws"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/std-ws#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/std-ws"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@venn-lang/contracts": "0.1.0",
+    "@venn-lang/sdk": "0.1.0",
+    "@venn-lang/types": "0.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions/close.ts

@@ -0,0 +1,11 @@
+import { type ActionDefinition, defineAction } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { WsClientPort } from "../port/index.js";
+
+/** `ws.close`: hang up the connection the port is holding. Takes nothing. */
+export const wsClose: ActionDefinition = defineAction({
+  name: "close",
+  doc: "Close the WebSocket connection.",
+  result: t.void,
+  run: (ctx) => ctx.port(WsClientPort).close(),
+});

package/src/actions/connect.ts

@@ -0,0 +1,21 @@
+import { type ActionDefinition, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { WsClientPort } from "../port/index.js";
+
+const params = z.object({ auth: z.unknown().optional() });
+
+/**
+ * `ws.connect "wss://…" { auth: token }`: open the socket.
+ *
+ * Returns nothing, because the port owns the connection. That is what lets
+ * `ws.send` and `ws.close` reach it without the flow carrying a handle.
+ */
+export const wsConnect: ActionDefinition = defineAction({
+  name: "connect",
+  doc: "Open a WebSocket connection.",
+  params,
+  args: [arg("url", t.string, "Where to connect: `ws://` or `wss://`.")],
+  result: t.void,
+  run: (ctx, input) =>
+    ctx.port(WsClientPort).connect({ url: String(input.args[0] ?? ""), auth: input.params.auth }),
+});

package/src/actions/expect.ts

@@ -0,0 +1,23 @@
+import { type ActionDefinition, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { WsClientPort } from "../port/index.js";
+
+const params = z.object({
+  type: z.string().optional(),
+  where: z.record(z.string(), z.unknown()).optional(),
+});
+
+/**
+ * `ws.expect { type: "ack" }` or `ws.expect { where: { … } }`: wait for the next
+ * message that matches.
+ *
+ * The query is the options map, so nothing is positional. The result is typed as
+ * `ws.Message`, which is what lets `expect res type "ack"` know its subject.
+ */
+export const wsExpect: ActionDefinition = defineAction({
+  name: "expect",
+  doc: "Wait for the next matching incoming message.",
+  params,
+  result: t.ref("ws.Message"),
+  run: (ctx, input) => ctx.port(WsClientPort).expect(input.params),
+});

package/src/actions/index.ts

@@ -0,0 +1,8 @@
+import type { ActionDefinition } from "@venn-lang/sdk";
+import { wsClose } from "./close.js";
+import { wsConnect } from "./connect.js";
+import { wsExpect } from "./expect.js";
+import { wsSend } from "./send.js";
+
+/** The ws namespace's verbs. Adding one is a new file plus a single line here. */
+export const wsActions: ActionDefinition[] = [wsConnect, wsSend, wsExpect, wsClose];

package/src/actions/send.ts

@@ -0,0 +1,19 @@
+import { type ActionDefinition, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { WsClientPort } from "../port/index.js";
+
+const params = z.object({ type: z.string().optional(), data: z.unknown().optional() });
+
+/**
+ * `ws.send { type: "ping", data: 1 }`: write one message.
+ *
+ * Nothing is positional: the options map is the message, and `params` above is
+ * what checks its keys.
+ */
+export const wsSend: ActionDefinition = defineAction({
+  name: "send",
+  doc: "Send a message over the WebSocket.",
+  params,
+  result: t.void,
+  run: (ctx, input) => ctx.port(WsClientPort).send(input.params),
+});

package/src/clients/fake-client.ts

@@ -0,0 +1,52 @@
+import { VennError } from "@venn-lang/contracts";
+import type { FakeWsClient, WsExpectQuery } from "../port/index.js";
+import type { Message } from "../types/index.js";
+
+/**
+ * The double: no socket, and `expect` resolves at once instead of waiting.
+ *
+ * @param args.incoming Messages the peer is pretending to have sent, in order.
+ * @returns A client whose `sent` array is everything the flow wrote.
+ * @throws VN8091 from `expect` once the incoming queue is empty.
+ */
+export function createFakeWsClient(args: { incoming?: Message[] } = {}): FakeWsClient {
+  const incoming = [...(args.incoming ?? [])];
+  const sent: Message[] = [];
+  return {
+    sent,
+    connect: async () => {},
+    send: async (message) => void sent.push(message),
+    expect: async (query) => takeMatch(incoming, query),
+    close: async () => {},
+  };
+}
+
+/**
+ * Consume the first message matching `query`, or the head of the queue when
+ * none match, so a mistyped query still advances instead of deadlocking.
+ */
+function takeMatch(queue: Message[], query: WsExpectQuery): Message {
+  const index = queue.findIndex((message) => matches(message, query));
+  const found = queue.splice(index >= 0 ? index : 0, 1)[0];
+  if (!found) throw noMessage();
+  return found;
+}
+
+function matches(message: Message, query: WsExpectQuery): boolean {
+  if (query.type !== undefined) return message.type === query.type;
+  if (query.where) return matchesWhere(message, query.where);
+  return true;
+}
+
+function matchesWhere(message: Message, where: Record<string, unknown>): boolean {
+  const record = message as Record<string, unknown>;
+  return Object.entries(where).every(([key, value]) => equal(record[key], value));
+}
+
+function equal(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function noMessage(): VennError {
+  return new VennError({ code: "VN8091", message: "No WebSocket message available to match." });
+}

package/src/clients/index.ts

@@ -0,0 +1,2 @@
+export { createFakeWsClient } from "./fake-client.js";
+export { createRealWsClient } from "./real-client.js";

package/src/clients/real-client.ts

@@ -0,0 +1,26 @@
+import { VennError } from "@venn-lang/contracts";
+import type { WsClient } from "../port/index.js";
+
+/**
+ * The real WebSocket client. Not implemented in this build.
+ *
+ * It exists so the port has its second implementation and the failure is a named
+ * Venn error rather than a missing method.
+ *
+ * @throws VN8090 from every method.
+ */
+export function createRealWsClient(): WsClient {
+  return {
+    connect: notImplemented,
+    send: notImplemented,
+    expect: notImplemented,
+    close: notImplemented,
+  };
+}
+
+function notImplemented(): never {
+  throw new VennError({
+    code: "VN8090",
+    message: "WebSocket real client not implemented in this build",
+  });
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * The `ws` plugin: `connect`, `send`, `expect` and `close` over one socket.
+ *
+ * The socket lives behind the `WsClient` port, so a flow never carries a handle
+ * and the same script runs against a real endpoint or the in-memory double.
+ */
+
+export * from "./clients/index.js";
+export { wsPlugin, wsPlugin as default } from "./plugin.js";
+export * from "./port/index.js";
+export * from "./types/index.js";

package/src/matchers/index.ts

@@ -0,0 +1,4 @@
+import type { MatcherDefinition } from "@venn-lang/sdk";
+import { ofType } from "./of-type.js";
+
+export const wsMatchers: MatcherDefinition[] = [ofType];

package/src/matchers/of-type.ts

@@ -0,0 +1,15 @@
+import { arg, defineMatcher, type MatcherDefinition } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+
+/** `expect res type "ack"`: passes if the message carries exactly that `type`. */
+export const ofType: MatcherDefinition = defineMatcher({
+  name: "type",
+  args: [arg("type", t.string, "The message type expected: `text`, `binary`.")],
+  appliesTo: "Message",
+  test: ({ subject, args }) => messageType(subject) === String(args[0]),
+  message: ({ args }) => `expected the message to have type "${String(args[0])}"`,
+});
+
+function messageType(subject: unknown): string | undefined {
+  return (subject as { type?: string }).type;
+}

package/src/plugin.ts

@@ -0,0 +1,22 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { wsActions } from "./actions/index.js";
+import { wsMatchers } from "./matchers/index.js";
+import { messageSchema, wsTypeDefs } from "./types/index.js";
+
+/**
+ * The `ws` namespace: `connect`, `send`, `expect`, `close`, the `type` matcher
+ * and the `ws.Message` type.
+ *
+ * Requires the `net` capability, so a host without it refuses the plugin at load
+ * time rather than failing mid-flow.
+ */
+export const wsPlugin: PluginDefinition = definePlugin({
+  name: "venn/ws",
+  version: "0.0.0",
+  namespace: "ws",
+  requires: ["net"],
+  actions: wsActions,
+  matchers: wsMatchers,
+  types: { Message: messageSchema },
+  typeDefs: wsTypeDefs,
+});

package/src/port/index.ts

@@ -0,0 +1,2 @@
+export { WsClientPort } from "./ws-client.port.js";
+export type { FakeWsClient, WsClient, WsConnectArgs, WsExpectQuery } from "./ws-client.types.js";

package/src/port/ws-client.port.ts

@@ -0,0 +1,15 @@
+import type { Port } from "@venn-lang/contracts";
+import type { WsClient } from "./ws-client.types.js";
+
+/**
+ * The port descriptor every `ws` verb resolves through `ctx.port(...)`.
+ *
+ * Declares the `net` capability, so a host that cannot open sockets refuses the
+ * binding at load time with a readable diagnostic.
+ */
+export const WsClientPort: Port<WsClient> = {
+  id: "venn.port.ws-client",
+  version: 1,
+  requires: ["net"],
+  methods: ["connect", "send", "expect", "close"],
+};

package/src/port/ws-client.types.ts

@@ -0,0 +1,37 @@
+import type { Message } from "../types/index.js";
+
+/** What `ws.connect` passes on: the URL it was given, and any `auth` from the opts map. */
+export interface WsConnectArgs {
+  url: string;
+  auth?: unknown;
+}
+
+/**
+ * Which incoming message `ws.expect` is waiting for: one with this `type`, or
+ * one whose fields match every entry in `where`. Both empty means the next one.
+ */
+export interface WsExpectQuery {
+  type?: string;
+  where?: Record<string, unknown>;
+}
+
+/**
+ * One WebSocket connection: open it, write to it, wait on it, close it.
+ *
+ * The port holds the socket, which is why no method takes a handle: a flow says
+ * `ws.send { … }` and the implementation knows which connection it means.
+ *
+ * Two implementations: `createRealWsClient` and `createFakeWsClient`.
+ */
+export interface WsClient {
+  connect(args: WsConnectArgs): Promise<void>;
+  send(message: Message): Promise<void>;
+  expect(query: WsExpectQuery): Promise<Message>;
+  close(): Promise<void>;
+}
+
+/** A `WsClient` that also lets a test read back what the flow sent. */
+export interface FakeWsClient extends WsClient {
+  /** Every message handed to `send`, in order. */
+  readonly sent: readonly Message[];
+}

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export { messageSchema } from "./message.js";
+export type { Message } from "./message.types.js";
+export { wsTypeDefs } from "./type-defs.js";

package/src/types/message.ts

@@ -0,0 +1,12 @@
+import { type ZodType, z } from "@venn-lang/sdk";
+
+/**
+ * Runtime validation for `ws.Message`, registered on the plugin.
+ *
+ * Pairs with `wsTypeDefs.Message`, which tells the checker the same shape: this
+ * one guards a value, that one types an expression.
+ */
+export const messageSchema: ZodType = z.object({
+  type: z.string().optional(),
+  data: z.unknown().optional(),
+});

package/src/types/message.types.ts

@@ -0,0 +1,10 @@
+/**
+ * One message on the socket, and what `ws.expect` hands back.
+ *
+ * Both fields are optional because a peer is free to send whatever it likes;
+ * `where` queries match on fields beyond these two.
+ */
+export interface Message {
+  type?: string;
+  data?: unknown;
+}

package/src/types/type-defs.ts

@@ -0,0 +1,17 @@
+import { type TypeSpec, t } from "@venn-lang/types";
+
+/**
+ * The types the plugin publishes to flows, as `ws.Message`.
+ *
+ * Mirrors `Message` in `message.types.ts` and the Zod schema beside it: the
+ * schema guards a value at runtime, this tells the checker what `ws.expect`
+ * handed back. Open, because `expect { where: … }` matches on whatever fields a
+ * message carries beyond `type` and `data`.
+ */
+export const wsTypeDefs: Readonly<Record<string, TypeSpec>> = {
+  /** One message off the socket, as `ws.expect` gives it back. */
+  Message: t.record(
+    { type: t.string, data: t.dynamic },
+    { optional: ["type", "data"], open: true },
+  ),
+};