@effectionx/websocket 2.0.1

package/README.md

@@ -0,0 +1,73 @@
+# WebSocket
+
+A streamlined [WebSocket][websocket] client for Effection programs that
+transforms the event-based WebSocket API into a clean, resource-oriented stream.
+
+## Why Use this API?
+
+Traditional WebSocket API require managing multiple event handlers (`open`,
+`close`, `error`, `message`) which can become complex and error-prone.
+
+This package simplifies WebSocket usage by:
+
+- Providing a clean stream-based interface
+- Handling connection state management automatically
+- Implementing proper error handling
+- Ensuring resource cleanup
+
+## Basic Usage
+
+```typescript
+import { each, main } from "effection";
+import { useWebSocket } from "@effectionx/websocket";
+
+await main(function* () {
+  // Connection is guaranteed to be open when this returns
+  let socket = yield* useWebSocket("ws://websocket.example.org");
+
+  // Send messages to the server
+  socket.send("Hello World");
+
+  // Receive messages using a simple iterator
+  for (let message of yield* each(socket)) {
+    console.log("Message from server", message);
+    yield* each.next();
+  }
+});
+```
+
+## Features
+
+- **Ready-to-use Connections**: `useWebSocket()` returns only after the
+  connection is established
+- **Automatic Error Handling**: Socket errors are properly propagated to your
+  error boundary
+- **Stream-based API**: Messages are delivered through a simple stream interface
+- **Clean Resource Management**: Connections are properly cleaned up when the
+  operation completes
+
+## Advanced Usage
+
+### Custom WebSocket Implementations
+
+For environments without native WebSocket support (like Node.js < 21), you can
+provide your own WebSocket implementation:
+
+```typescript
+import { createWebSocket } from "my-websocket-client";
+import { each, main } from "effection";
+import { useWebSocket } from "@effectionx/websocket";
+
+await main(function* () {
+  let socket = yield* useWebSocket(() =>
+    createWebSocket("ws://websocket.example.org")
+  );
+
+  for (let message of yield* each(socket)) {
+    console.log("Message from server", message);
+    yield* each.next();
+  }
+});
+```
+
+[websocket]: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket

package/esm/mod.d.ts

@@ -0,0 +1,2 @@
+export * from "./websocket.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/esm/mod.js

@@ -0,0 +1 @@
+export * from "./websocket.js";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/websocket.d.ts

@@ -0,0 +1,90 @@
+import type { Operation, Stream } from "effection";
+/**
+ * Handle to a
+ * [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) object
+ * that can be consumed as an Effection stream. It has all the same properties as
+ * the underlying `WebSocket` apart from the event handlers. Instead, the resource
+ * itself is a subscribale stream. When the socket is closed, the stream will
+ * complete with a [`CloseEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent)
+ *
+ * A WebSocketResource does not have an explicit close method. Rather, the underlying
+ * socket will be automatically closed when the resource passes out of scope.
+ */
+export interface WebSocketResource<T> extends Stream<MessageEvent<T>, CloseEvent> {
+    /**
+     * the type of data that this websocket accepts
+     */
+    readonly binaryType: BinaryType;
+    readonly bufferedAmmount: number;
+    readonly extensions: string;
+    readonly protocol: string;
+    readonly readyState: number;
+    readonly url: string;
+    send(data: WebSocketData): void;
+}
+/**
+ * Create a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+ * resource using the native
+ * [WebSocket constructor](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket)
+ * available on the current platform.
+ *
+ * The resource will not be returned until a connection has been
+ * succesffuly established with the server and the
+ * [`open`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/open_event)
+ * has been received. Once initialized, it will crash if it receives
+ * an [`error`]() event at any time.
+ *
+ * Once created, the websocket resource can be use to consume events from the server:
+ *
+ * ```ts
+ * let socket = yield* useWebSocket("ws://websocket.example.org");
+ *
+ * for (let event of yield* each(socket)) {
+ *   console.log('event data: ', event.data);
+ *   yield* each.next();
+ * }
+ * ```
+ *
+ * @param url - The URL of the target WebSocket server to connect to. The URL must use one of the following schemes: ws, wss, http, or https, and cannot include a URL fragment. If a relative URL is provided, it is relative to the base URL of the calling script. For more detail, see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket#url
+ *
+ * @param prototol - A single string or an array of strings representing the sub-protocol(s) that the client would like to use, in order of preference. If it is omitted, an empty array is used by default, i.e. []. For more details, see
+ *
+ * @returns an operation yielding a {@link WebSocketResource}
+ */
+export declare function useWebSocket<T>(url: string, protocols?: string): Operation<WebSocketResource<T>>;
+/**
+ * Create a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+ * resource, but delegate the creation of the underlying websocket to a function
+ * of your choice. This is necessary on platforms that do not have a global
+ * `WebSocket` constructor such as NodeJS \<= 20.
+ *
+ * The resource will not be returned until a connection has been
+ * succesffuly established with the server and the
+ * [`open`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/open_event)
+ * has been received. Once initialized, it will crash if it receives
+ * an [`error`]() event at any time.
+ *
+ * Once created, the websocket resource can be use to consume events from the server:
+ *
+ * ```ts
+ * import * as ws from 'ws';
+ *
+ * function* example() {
+ *   let socket = yield* useWebSocket(() => new ws.WebSocket("ws://websocket.example.org"));
+ *
+ *   for (let event of yield* each(socket)) {
+ *     console.log('event data: ', event.data);
+ *     yield* each.next();
+ *   }
+ * }
+ *
+ * ```
+ * @param create - a function that will construct the underlying [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) object that this resource wil use
+ * @returns an operation yielding a {@link WebSocketResource}
+ */
+export declare function useWebSocket<T>(create: () => WebSocket): Operation<WebSocketResource<T>>;
+/**
+ * @ignore
+ */
+export type WebSocketData = Parameters<WebSocket["send"]>[0];
+//# sourceMappingURL=websocket.d.ts.map

package/esm/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../src/websocket.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,CAClC,SAAQ,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC;IAC3C;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,SAAS,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,MAAM,EAAE,MAAM,SAAS,GACtB,SAAS,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;AAsEnC;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/esm/websocket.js

@@ -0,0 +1,60 @@
+import { createSignal, once, race, resource, spawn, withResolvers, } from "effection";
+/**
+ * @ignore the catch-all version that supports both forms above.
+ */
+export function useWebSocket(url, protocols) {
+    return resource(function* (provide) {
+        let socket = typeof url === "string"
+            ? new WebSocket(url, protocols)
+            : url();
+        let messages = createSignal();
+        let { operation: closed, resolve: close } = withResolvers();
+        yield* spawn(function* () {
+            throw yield* once(socket, "error");
+        });
+        yield* once(socket, "open");
+        yield* spawn(function* () {
+            let subscription = yield* messages;
+            let next = yield* subscription.next();
+            while (!next.done) {
+                next = yield* subscription.next();
+            }
+            close(next.value);
+        });
+        try {
+            socket.addEventListener("message", messages.send);
+            socket.addEventListener("close", messages.close);
+            yield* race([
+                closed,
+                provide({
+                    get binaryType() {
+                        return socket.binaryType;
+                    },
+                    get bufferedAmmount() {
+                        return socket.bufferedAmount;
+                    },
+                    get extensions() {
+                        return socket.extensions;
+                    },
+                    get protocol() {
+                        return socket.protocol;
+                    },
+                    get readyState() {
+                        return socket.readyState;
+                    },
+                    get url() {
+                        return socket.url;
+                    },
+                    send: (data) => socket.send(data),
+                    [Symbol.iterator]: messages[Symbol.iterator],
+                }),
+            ]);
+        }
+        finally {
+            socket.close(1000, "released");
+            yield* closed;
+            socket.removeEventListener("message", messages.send);
+            socket.removeEventListener("close", messages.close);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@effectionx/websocket",
+  "version": "2.0.1",
+  "author": "engineering@frontside.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thefrontside/effectionx.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/thefrontside/effectionx/issues"
+  },
+  "main": "./script/mod.js",
+  "module": "./esm/mod.js",
+  "exports": {
+    ".": {
+      "import": "./esm/mod.js",
+      "require": "./script/mod.js"
+    }
+  },
+  "engines": {
+    "node": ">= 16"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "effection": "4.0.0-alpha.6"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/script/mod.d.ts

@@ -0,0 +1,2 @@
+export * from "./websocket.js";
+//# sourceMappingURL=mod.d.ts.map

package/script/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/script/mod.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./websocket.js"), exports);

package/script/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/script/websocket.d.ts

@@ -0,0 +1,90 @@
+import type { Operation, Stream } from "effection";
+/**
+ * Handle to a
+ * [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) object
+ * that can be consumed as an Effection stream. It has all the same properties as
+ * the underlying `WebSocket` apart from the event handlers. Instead, the resource
+ * itself is a subscribale stream. When the socket is closed, the stream will
+ * complete with a [`CloseEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent)
+ *
+ * A WebSocketResource does not have an explicit close method. Rather, the underlying
+ * socket will be automatically closed when the resource passes out of scope.
+ */
+export interface WebSocketResource<T> extends Stream<MessageEvent<T>, CloseEvent> {
+    /**
+     * the type of data that this websocket accepts
+     */
+    readonly binaryType: BinaryType;
+    readonly bufferedAmmount: number;
+    readonly extensions: string;
+    readonly protocol: string;
+    readonly readyState: number;
+    readonly url: string;
+    send(data: WebSocketData): void;
+}
+/**
+ * Create a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+ * resource using the native
+ * [WebSocket constructor](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket)
+ * available on the current platform.
+ *
+ * The resource will not be returned until a connection has been
+ * succesffuly established with the server and the
+ * [`open`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/open_event)
+ * has been received. Once initialized, it will crash if it receives
+ * an [`error`]() event at any time.
+ *
+ * Once created, the websocket resource can be use to consume events from the server:
+ *
+ * ```ts
+ * let socket = yield* useWebSocket("ws://websocket.example.org");
+ *
+ * for (let event of yield* each(socket)) {
+ *   console.log('event data: ', event.data);
+ *   yield* each.next();
+ * }
+ * ```
+ *
+ * @param url - The URL of the target WebSocket server to connect to. The URL must use one of the following schemes: ws, wss, http, or https, and cannot include a URL fragment. If a relative URL is provided, it is relative to the base URL of the calling script. For more detail, see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket#url
+ *
+ * @param prototol - A single string or an array of strings representing the sub-protocol(s) that the client would like to use, in order of preference. If it is omitted, an empty array is used by default, i.e. []. For more details, see
+ *
+ * @returns an operation yielding a {@link WebSocketResource}
+ */
+export declare function useWebSocket<T>(url: string, protocols?: string): Operation<WebSocketResource<T>>;
+/**
+ * Create a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+ * resource, but delegate the creation of the underlying websocket to a function
+ * of your choice. This is necessary on platforms that do not have a global
+ * `WebSocket` constructor such as NodeJS \<= 20.
+ *
+ * The resource will not be returned until a connection has been
+ * succesffuly established with the server and the
+ * [`open`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/open_event)
+ * has been received. Once initialized, it will crash if it receives
+ * an [`error`]() event at any time.
+ *
+ * Once created, the websocket resource can be use to consume events from the server:
+ *
+ * ```ts
+ * import * as ws from 'ws';
+ *
+ * function* example() {
+ *   let socket = yield* useWebSocket(() => new ws.WebSocket("ws://websocket.example.org"));
+ *
+ *   for (let event of yield* each(socket)) {
+ *     console.log('event data: ', event.data);
+ *     yield* each.next();
+ *   }
+ * }
+ *
+ * ```
+ * @param create - a function that will construct the underlying [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) object that this resource wil use
+ * @returns an operation yielding a {@link WebSocketResource}
+ */
+export declare function useWebSocket<T>(create: () => WebSocket): Operation<WebSocketResource<T>>;
+/**
+ * @ignore
+ */
+export type WebSocketData = Parameters<WebSocket["send"]>[0];
+//# sourceMappingURL=websocket.d.ts.map

package/script/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../src/websocket.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,CAClC,SAAQ,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC;IAC3C;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,SAAS,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,MAAM,EAAE,MAAM,SAAS,GACtB,SAAS,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;AAsEnC;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/script/websocket.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useWebSocket = useWebSocket;
+const effection_1 = require("effection");
+/**
+ * @ignore the catch-all version that supports both forms above.
+ */
+function useWebSocket(url, protocols) {
+    return (0, effection_1.resource)(function* (provide) {
+        let socket = typeof url === "string"
+            ? new WebSocket(url, protocols)
+            : url();
+        let messages = (0, effection_1.createSignal)();
+        let { operation: closed, resolve: close } = (0, effection_1.withResolvers)();
+        yield* (0, effection_1.spawn)(function* () {
+            throw yield* (0, effection_1.once)(socket, "error");
+        });
+        yield* (0, effection_1.once)(socket, "open");
+        yield* (0, effection_1.spawn)(function* () {
+            let subscription = yield* messages;
+            let next = yield* subscription.next();
+            while (!next.done) {
+                next = yield* subscription.next();
+            }
+            close(next.value);
+        });
+        try {
+            socket.addEventListener("message", messages.send);
+            socket.addEventListener("close", messages.close);
+            yield* (0, effection_1.race)([
+                closed,
+                provide({
+                    get binaryType() {
+                        return socket.binaryType;
+                    },
+                    get bufferedAmmount() {
+                        return socket.bufferedAmount;
+                    },
+                    get extensions() {
+                        return socket.extensions;
+                    },
+                    get protocol() {
+                        return socket.protocol;
+                    },
+                    get readyState() {
+                        return socket.readyState;
+                    },
+                    get url() {
+                        return socket.url;
+                    },
+                    send: (data) => socket.send(data),
+                    [Symbol.iterator]: messages[Symbol.iterator],
+                }),
+            ]);
+        }
+        finally {
+            socket.close(1000, "released");
+            yield* closed;
+            socket.removeEventListener("message", messages.send);
+            socket.removeEventListener("close", messages.close);
+        }
+    });
+}