@atcute/firehose 0.1.0

package/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License
+
+Copyright (c) 2025 Mary
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @atcute/firehose
+
+lightweight and cute XRPC subscription client for AT Protocol.
+
+```ts
+import { FirehoseSubscription } from '@atcute/firehose';
+import { ComAtprotoSyncSubscribeRepos } from '@atcute/atproto';
+
+let cursor: number | undefined;
+
+const subscription = new FirehoseSubscription({
+	service: ['wss://bsky.network'],
+	nsid: ComAtprotoSyncSubscribeRepos.mainSchema,
+	params: () => ({ cursor }),
+});
+
+for await (const message of subscription) {
+	if (message.$type === 'com.atproto.sync.subscribeRepos#commit') {
+		cursor = message.seq;
+		console.log('commit:', message.seq, message.repo);
+	}
+}
+```

package/dist/frame-decoder.d.ts

@@ -0,0 +1,14 @@
+import type { DecodedFrame } from './types.js';
+/**
+ * decodes a CBOR frame from a buffer
+ */
+export declare const decodeFrame: (buffer: Uint8Array) => DecodedFrame;
+/**
+ * reconstructs full $type field from discriminator and nsid
+ */
+export declare const reconstructType: (discriminator: string | undefined, nsid: string) => string | undefined;
+/**
+ * adds $type field to message body if discriminator is present
+ */
+export declare const addTypeToBody: (body: unknown, discriminator: string | undefined, nsid: string) => unknown;
+//# sourceMappingURL=frame-decoder.d.ts.map

package/dist/frame-decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-decoder.d.ts","sourceRoot":"","sources":["../lib/frame-decoder.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAA+B,MAAM,YAAY,CAAC;AAE5E;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,UAAU,KAAG,YAuBhD,CAAC;AAeF;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,eAAe,MAAM,GAAG,SAAS,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,SAU1F,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,OAAO,EAAE,eAAe,MAAM,GAAG,SAAS,EAAE,MAAM,MAAM,KAAG,OAQ9F,CAAC"}

package/dist/frame-decoder.js

@@ -0,0 +1,59 @@
+import { decode, decodeFirst } from '@atcute/cbor';
+/**
+ * decodes a CBOR frame from a buffer
+ */
+export const decodeFrame = (buffer) => {
+    const [header, afterHeader] = decodeFirst(buffer);
+    if (!isValidHeader(header)) {
+        throw new Error('invalid frame header');
+    }
+    const body = decode(afterHeader);
+    if (header.op === 1) {
+        return {
+            type: 'message',
+            body,
+            discriminator: header.t,
+        };
+    }
+    else {
+        const errorBody = body;
+        return {
+            type: 'error',
+            error: errorBody.error,
+            message: errorBody.message,
+        };
+    }
+};
+/**
+ * type guard for frame header
+ */
+const isValidHeader = (value) => {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    return (obj.op === 1 || obj.op === -1) && (obj.t === undefined || typeof obj.t === 'string');
+};
+/**
+ * reconstructs full $type field from discriminator and nsid
+ */
+export const reconstructType = (discriminator, nsid) => {
+    if (!discriminator) {
+        return undefined;
+    }
+    if (discriminator[0] === '#') {
+        return nsid + discriminator;
+    }
+    return discriminator;
+};
+/**
+ * adds $type field to message body if discriminator is present
+ */
+export const addTypeToBody = (body, discriminator, nsid) => {
+    const type = reconstructType(discriminator, nsid);
+    if (type && typeof body === 'object' && body !== null) {
+        body.$type = type;
+    }
+    return body;
+};
+//# sourceMappingURL=frame-decoder.js.map

package/dist/frame-decoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-decoder.js","sourceRoot":"","sources":["../lib/frame-decoder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAInD;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAkB,EAAgB,EAAE;IAC/D,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAElD,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IACzC,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;IAEjC,IAAI,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO;YACN,IAAI,EAAE,SAAS;YACf,IAAI;YACJ,aAAa,EAAE,MAAM,CAAC,CAAC;SACvB,CAAC;IACH,CAAC;SAAM,CAAC;QACP,MAAM,SAAS,GAAG,IAAsB,CAAC;QACzC,OAAO;YACN,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,SAAS,CAAC,KAAK;YACtB,OAAO,EAAE,SAAS,CAAC,OAAO;SAC1B,CAAC;IACH,CAAC;AACF,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,aAAa,GAAG,CAAC,KAAc,EAAwB,EAAE;IAC9D,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACjD,OAAO,KAAK,CAAC;IACd,CAAC;IAED,MAAM,GAAG,GAAG,KAAgC,CAAC;IAE7C,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC;AAC9F,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,aAAiC,EAAE,IAAY,EAAsB,EAAE;IACtG,IAAI,CAAC,aAAa,EAAE,CAAC;QACpB,OAAO,SAAS,CAAC;IAClB,CAAC;IAED,IAAI,aAAa,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;QAC9B,OAAO,IAAI,GAAG,aAAa,CAAC;IAC7B,CAAC;IAED,OAAO,aAAa,CAAC;AACtB,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAa,EAAE,aAAiC,EAAE,IAAY,EAAW,EAAE;IACxG,MAAM,IAAI,GAAG,eAAe,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;IAElD,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QACtD,IAAgC,CAAC,KAAK,GAAG,IAAI,CAAC;IAChD,CAAC;IAED,OAAO,IAAI,CAAC;AACb,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { FirehoseSubscription } from './subscription.js';
+export type { FirehoseSubscriptionOptions, MessageOf, ParamsOf } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,YAAY,EAAE,2BAA2B,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { FirehoseSubscription } from './subscription.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/subscription.d.ts

@@ -0,0 +1,24 @@
+import { type XRPCSubscriptionMetadata } from '@atcute/lexicons/validations';
+import { EventIterator } from '@mary-ext/event-iterator';
+import type { ReadonlyDeep } from 'type-fest';
+import type { FirehoseSubscriptionOptions, MessageOf } from './types.js';
+/**
+ * generic XRPC subscription client for AT Protocol
+ */
+export declare class FirehoseSubscription<TSchema extends XRPCSubscriptionMetadata> {
+    #private;
+    /**
+     * creates a new firehose subscription
+     */
+    constructor(options: FirehoseSubscriptionOptions<TSchema>);
+    [Symbol.asyncIterator](): EventIterator<MessageOf<TSchema>>;
+    /**
+     * get current subscription options
+     */
+    getOptions(): ReadonlyDeep<FirehoseSubscriptionOptions<TSchema>>;
+    /**
+     * update subscription options, triggering a reconnection if currently connected
+     */
+    updateOptions(options: Partial<FirehoseSubscriptionOptions<TSchema>>): void;
+}
+//# sourceMappingURL=subscription.d.ts.map

package/dist/subscription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.d.ts","sourceRoot":"","sources":["../lib/subscription.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAExF,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAKzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C,OAAO,KAAK,EAAE,2BAA2B,EAAE,SAAS,EAAY,MAAM,YAAY,CAAC;AAEnF;;GAEG;AACH,qBAAa,oBAAoB,CAAC,OAAO,SAAS,wBAAwB;;IAQzE;;OAEG;gBACS,OAAO,EAAE,2BAA2B,CAAC,OAAO,CAAC;IA4FzD,CAAC,MAAM,CAAC,aAAa,CAAC;IAoBtB;;OAEG;IACH,UAAU,IAAI,YAAY,CAAC,2BAA2B,CAAC,OAAO,CAAC,CAAC;IAIhE;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,2BAA2B,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI;CAQ3E"}

package/dist/subscription.js

@@ -0,0 +1,112 @@
+import { safeParse } from '@atcute/lexicons/validations';
+import { EventIterator } from '@mary-ext/event-iterator';
+import { SimpleEventEmitter } from '@mary-ext/simple-event-emitter';
+import { WebSocket as ReconnectingWebSocket } from 'partysocket';
+import { addTypeToBody, decodeFrame } from './frame-decoder.js';
+/**
+ * generic XRPC subscription client for AT Protocol
+ */
+export class FirehoseSubscription {
+    #listening = 0;
+    #ws;
+    #emitter = new SimpleEventEmitter();
+    #options;
+    /**
+     * creates a new firehose subscription
+     */
+    constructor(options) {
+        this.#options = options;
+    }
+    #create() {
+        if (this.#ws !== undefined) {
+            return;
+        }
+        const { service: wsUrls, nsid, params, ws: wsOptions, validateMessages = true, onConnectionClose, onConnectionError, onConnectionOpen, onError, } = this.#options;
+        const emitter = this.#emitter;
+        const getUrl = () => {
+            let selectedUrl;
+            if (typeof wsUrls === 'string') {
+                selectedUrl = wsUrls;
+            }
+            else {
+                selectedUrl = wsUrls[Math.floor(Math.random() * wsUrls.length)];
+            }
+            const url = new URL('/xrpc/' + nsid.nsid, selectedUrl);
+            const currentParams = typeof params === 'function' ? params() : params;
+            if (currentParams !== undefined && currentParams !== null) {
+                const paramObj = currentParams;
+                for (const key in paramObj) {
+                    const value = paramObj[key];
+                    if (value !== undefined && value !== null) {
+                        url.searchParams.set(key, String(value));
+                    }
+                }
+            }
+            return url.toString();
+        };
+        const ws = new ReconnectingWebSocket(getUrl, null, wsOptions);
+        this.#ws = ws;
+        ws.binaryType = 'arraybuffer';
+        ws.onerror = onConnectionError ?? null;
+        ws.onclose = onConnectionClose ?? null;
+        ws.onopen = onConnectionOpen ?? null;
+        ws.onmessage = (ev) => {
+            const buffer = new Uint8Array(ev.data);
+            const frame = decodeFrame(buffer);
+            if (frame.type === 'error') {
+                onError?.(frame.error, frame.message);
+                return;
+            }
+            let body = addTypeToBody(frame.body, frame.discriminator, nsid.nsid);
+            if (validateMessages && nsid.message !== null) {
+                const result = safeParse(nsid.message, body);
+                if (!result.ok) {
+                    return;
+                }
+                body = result.value;
+            }
+            emitter.emit(body);
+        };
+    }
+    #destroy() {
+        const ws = this.#ws;
+        if (ws === undefined) {
+            return;
+        }
+        ws.close();
+        this.#ws = undefined;
+    }
+    [Symbol.asyncIterator]() {
+        return new EventIterator((emit) => {
+            if (this.#listening === 0) {
+                this.#create();
+            }
+            this.#listening++;
+            this.#emitter.subscribe(emit);
+            return () => {
+                if (this.#listening === 1) {
+                    this.#destroy();
+                }
+                this.#listening--;
+                this.#emitter.unsubscribe(emit);
+            };
+        });
+    }
+    /**
+     * get current subscription options
+     */
+    getOptions() {
+        return this.#options;
+    }
+    /**
+     * update subscription options, triggering a reconnection if currently connected
+     */
+    updateOptions(options) {
+        this.#options = { ...this.#options, ...options };
+        if (this.#ws !== undefined) {
+            this.#destroy();
+            this.#create();
+        }
+    }
+}
+//# sourceMappingURL=subscription.js.map

package/dist/subscription.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,76 @@
+import type { InferOutput, XRPCSubscriptionMetadata } from '@atcute/lexicons/validations';
+import type { CloseEvent, ErrorEvent, Options } from 'partysocket/ws';
+import type { BaseSchema } from '@atcute/lexicons/validations';
+/**
+ * extracts the params type from an XRPC subscription schema
+ */
+export type ParamsOf<T> = T extends XRPCSubscriptionMetadata<infer TParams, any, any> ? TParams extends null ? undefined : TParams extends BaseSchema ? InferOutput<TParams> : never : never;
+/**
+ * extracts the message type from an XRPC subscription schema
+ */
+export type MessageOf<T> = T extends XRPCSubscriptionMetadata<any, infer TMessage, any> ? TMessage extends null ? unknown : TMessage extends BaseSchema ? InferOutput<TMessage> : never : never;
+/**
+ * configuration options for FirehoseSubscription
+ */
+export interface FirehoseSubscriptionOptions<TSchema extends XRPCSubscriptionMetadata> {
+    /**
+     * XRPC service URL(s) to connect to
+     */
+    service: string | string[];
+    /**
+     * XRPC subscription schema from @atcute/lexicons
+     */
+    nsid: TSchema;
+    /**
+     * subscription parameters - can be a static object or a function that returns
+     * params. the function is called on each connection attempt, allowing for
+     * dynamic cursor tracking and reconnection state management.
+     */
+    params?: ParamsOf<TSchema> | (() => ParamsOf<TSchema>);
+    /**
+     * whether to validate incoming messages against the schema
+     * @default true
+     */
+    validateMessages?: boolean;
+    onConnectionOpen?: (event: Event) => void;
+    onConnectionClose?: (event: CloseEvent) => void;
+    onConnectionError?: (event: ErrorEvent) => void;
+    onError?: (error: string, message?: string) => void;
+    /**
+     * WebSocket connection options
+     */
+    ws?: Options;
+}
+/**
+ * decoded CBOR frame header
+ */
+export interface FrameHeader {
+    /**
+     * operation code: 1 for message, -1 for error
+     */
+    op: 1 | -1;
+    /**
+     * type discriminator for message frames (relative to NSID, e.g., "#commit")
+     */
+    t?: string;
+}
+/**
+ * error frame body
+ */
+export interface ErrorFrameBody {
+    error: string;
+    message?: string;
+}
+/**
+ * decoded frame result
+ */
+export type DecodedFrame = {
+    type: 'message';
+    body: unknown;
+    discriminator?: string;
+} | {
+    type: 'error';
+    error: string;
+    message?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../lib/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAE1F,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAEtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS,wBAAwB,CAAC,MAAM,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,GAClF,OAAO,SAAS,IAAI,GACnB,SAAS,GACT,OAAO,SAAS,UAAU,GACzB,WAAW,CAAC,OAAO,CAAC,GACpB,KAAK,GACP,KAAK,CAAC;AAET;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,wBAAwB,CAAC,GAAG,EAAE,MAAM,QAAQ,EAAE,GAAG,CAAC,GACpF,QAAQ,SAAS,IAAI,GACpB,OAAO,GACP,QAAQ,SAAS,UAAU,GAC1B,WAAW,CAAC,QAAQ,CAAC,GACrB,KAAK,GACP,KAAK,CAAC;AAET;;GAEG;AACH,MAAM,WAAW,2BAA2B,CAAC,OAAO,SAAS,wBAAwB;IACpF;;OAEG;IACH,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAE3B;;OAEG;IACH,IAAI,EAAE,OAAO,CAAC;IAEd;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IAEvD;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC1C,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAChD,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAChD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAEpD;;OAEG;IACH,EAAE,CAAC,EAAE,OAAO,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B;;OAEG;IACH,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEX;;OAEG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GACrB;IACA,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;CACtB,GACD;IACA,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../lib/types.ts"],"names":[],"mappings":""}

package/lib/frame-decoder.ts

@@ -0,0 +1,72 @@
+import { decode, decodeFirst } from '@atcute/cbor';
+
+import type { DecodedFrame, ErrorFrameBody, FrameHeader } from './types.js';
+
+/**
+ * decodes a CBOR frame from a buffer
+ */
+export const decodeFrame = (buffer: Uint8Array): DecodedFrame => {
+	const [header, afterHeader] = decodeFirst(buffer);
+
+	if (!isValidHeader(header)) {
+		throw new Error('invalid frame header');
+	}
+
+	const body = decode(afterHeader);
+
+	if (header.op === 1) {
+		return {
+			type: 'message',
+			body,
+			discriminator: header.t,
+		};
+	} else {
+		const errorBody = body as ErrorFrameBody;
+		return {
+			type: 'error',
+			error: errorBody.error,
+			message: errorBody.message,
+		};
+	}
+};
+
+/**
+ * type guard for frame header
+ */
+const isValidHeader = (value: unknown): value is FrameHeader => {
+	if (value === null || typeof value !== 'object') {
+		return false;
+	}
+
+	const obj = value as Record<string, unknown>;
+
+	return (obj.op === 1 || obj.op === -1) && (obj.t === undefined || typeof obj.t === 'string');
+};
+
+/**
+ * reconstructs full $type field from discriminator and nsid
+ */
+export const reconstructType = (discriminator: string | undefined, nsid: string): string | undefined => {
+	if (!discriminator) {
+		return undefined;
+	}
+
+	if (discriminator[0] === '#') {
+		return nsid + discriminator;
+	}
+
+	return discriminator;
+};
+
+/**
+ * adds $type field to message body if discriminator is present
+ */
+export const addTypeToBody = (body: unknown, discriminator: string | undefined, nsid: string): unknown => {
+	const type = reconstructType(discriminator, nsid);
+
+	if (type && typeof body === 'object' && body !== null) {
+		(body as Record<string, unknown>).$type = type;
+	}
+
+	return body;
+};

package/lib/index.ts

@@ -0,0 +1,2 @@
+export { FirehoseSubscription } from './subscription.js';
+export type { FirehoseSubscriptionOptions, MessageOf, ParamsOf } from './types.js';

package/lib/subscription.ts

@@ -0,0 +1,157 @@
+import { safeParse, type XRPCSubscriptionMetadata } from '@atcute/lexicons/validations';
+
+import { EventIterator } from '@mary-ext/event-iterator';
+import { SimpleEventEmitter } from '@mary-ext/simple-event-emitter';
+
+import { WebSocket as ReconnectingWebSocket } from 'partysocket';
+
+import type { ReadonlyDeep } from 'type-fest';
+
+import { addTypeToBody, decodeFrame } from './frame-decoder.js';
+import type { FirehoseSubscriptionOptions, MessageOf, ParamsOf } from './types.js';
+
+/**
+ * generic XRPC subscription client for AT Protocol
+ */
+export class FirehoseSubscription<TSchema extends XRPCSubscriptionMetadata> {
+	#listening = 0;
+	#ws?: ReconnectingWebSocket;
+
+	#emitter = new SimpleEventEmitter<[message: MessageOf<TSchema>]>();
+
+	#options: FirehoseSubscriptionOptions<TSchema>;
+
+	/**
+	 * creates a new firehose subscription
+	 */
+	constructor(options: FirehoseSubscriptionOptions<TSchema>) {
+		this.#options = options;
+	}
+
+	#create() {
+		if (this.#ws !== undefined) {
+			return;
+		}
+
+		const {
+			service: wsUrls,
+			nsid,
+			params,
+			ws: wsOptions,
+			validateMessages = true,
+			onConnectionClose,
+			onConnectionError,
+			onConnectionOpen,
+			onError,
+		} = this.#options;
+
+		const emitter = this.#emitter;
+
+		const getUrl = () => {
+			let selectedUrl: string;
+
+			if (typeof wsUrls === 'string') {
+				selectedUrl = wsUrls;
+			} else {
+				selectedUrl = wsUrls[Math.floor(Math.random() * wsUrls.length)];
+			}
+
+			const url = new URL('/xrpc/' + nsid.nsid, selectedUrl);
+
+			const currentParams: ParamsOf<TSchema> = typeof params === 'function' ? params() : params;
+
+			if (currentParams !== undefined && currentParams !== null) {
+				const paramObj = currentParams as Record<string, unknown>;
+				for (const key in paramObj) {
+					const value = paramObj[key];
+					if (value !== undefined && value !== null) {
+						url.searchParams.set(key, String(value));
+					}
+				}
+			}
+
+			return url.toString();
+		};
+
+		const ws = new ReconnectingWebSocket(getUrl, null, wsOptions);
+		this.#ws = ws;
+
+		ws.binaryType = 'arraybuffer';
+
+		ws.onerror = onConnectionError ?? null;
+		ws.onclose = onConnectionClose ?? null;
+		ws.onopen = onConnectionOpen ?? null;
+
+		ws.onmessage = (ev) => {
+			const buffer = new Uint8Array(ev.data);
+			const frame = decodeFrame(buffer);
+
+			if (frame.type === 'error') {
+				onError?.(frame.error, frame.message);
+				return;
+			}
+
+			let body = addTypeToBody(frame.body, frame.discriminator, nsid.nsid);
+
+			if (validateMessages && nsid.message !== null) {
+				const result = safeParse(nsid.message, body);
+				if (!result.ok) {
+					return;
+				}
+				body = result.value;
+			}
+
+			emitter.emit(body as MessageOf<TSchema>);
+		};
+	}
+
+	#destroy() {
+		const ws = this.#ws;
+		if (ws === undefined) {
+			return;
+		}
+
+		ws.close();
+
+		this.#ws = undefined;
+	}
+
+	[Symbol.asyncIterator]() {
+		return new EventIterator<MessageOf<TSchema>>((emit) => {
+			if (this.#listening === 0) {
+				this.#create();
+			}
+
+			this.#listening++;
+			this.#emitter.subscribe(emit);
+
+			return () => {
+				if (this.#listening === 1) {
+					this.#destroy();
+				}
+
+				this.#listening--;
+				this.#emitter.unsubscribe(emit);
+			};
+		});
+	}
+
+	/**
+	 * get current subscription options
+	 */
+	getOptions(): ReadonlyDeep<FirehoseSubscriptionOptions<TSchema>> {
+		return this.#options as ReadonlyDeep<FirehoseSubscriptionOptions<TSchema>>;
+	}
+
+	/**
+	 * update subscription options, triggering a reconnection if currently connected
+	 */
+	updateOptions(options: Partial<FirehoseSubscriptionOptions<TSchema>>): void {
+		this.#options = { ...this.#options, ...options };
+
+		if (this.#ws !== undefined) {
+			this.#destroy();
+			this.#create();
+		}
+	}
+}

package/lib/types.ts

@@ -0,0 +1,103 @@
+import type { InferOutput, XRPCSubscriptionMetadata } from '@atcute/lexicons/validations';
+
+import type { CloseEvent, ErrorEvent, Options } from 'partysocket/ws';
+
+import type { BaseSchema } from '@atcute/lexicons/validations';
+
+/**
+ * extracts the params type from an XRPC subscription schema
+ */
+export type ParamsOf<T> = T extends XRPCSubscriptionMetadata<infer TParams, any, any>
+	? TParams extends null
+		? undefined
+		: TParams extends BaseSchema
+			? InferOutput<TParams>
+			: never
+	: never;
+
+/**
+ * extracts the message type from an XRPC subscription schema
+ */
+export type MessageOf<T> = T extends XRPCSubscriptionMetadata<any, infer TMessage, any>
+	? TMessage extends null
+		? unknown
+		: TMessage extends BaseSchema
+			? InferOutput<TMessage>
+			: never
+	: never;
+
+/**
+ * configuration options for FirehoseSubscription
+ */
+export interface FirehoseSubscriptionOptions<TSchema extends XRPCSubscriptionMetadata> {
+	/**
+	 * XRPC service URL(s) to connect to
+	 */
+	service: string | string[];
+
+	/**
+	 * XRPC subscription schema from @atcute/lexicons
+	 */
+	nsid: TSchema;
+
+	/**
+	 * subscription parameters - can be a static object or a function that returns
+	 * params. the function is called on each connection attempt, allowing for
+	 * dynamic cursor tracking and reconnection state management.
+	 */
+	params?: ParamsOf<TSchema> | (() => ParamsOf<TSchema>);
+
+	/**
+	 * whether to validate incoming messages against the schema
+	 * @default true
+	 */
+	validateMessages?: boolean;
+
+	onConnectionOpen?: (event: Event) => void;
+	onConnectionClose?: (event: CloseEvent) => void;
+	onConnectionError?: (event: ErrorEvent) => void;
+	onError?: (error: string, message?: string) => void;
+
+	/**
+	 * WebSocket connection options
+	 */
+	ws?: Options;
+}
+
+/**
+ * decoded CBOR frame header
+ */
+export interface FrameHeader {
+	/**
+	 * operation code: 1 for message, -1 for error
+	 */
+	op: 1 | -1;
+
+	/**
+	 * type discriminator for message frames (relative to NSID, e.g., "#commit")
+	 */
+	t?: string;
+}
+
+/**
+ * error frame body
+ */
+export interface ErrorFrameBody {
+	error: string;
+	message?: string;
+}
+
+/**
+ * decoded frame result
+ */
+export type DecodedFrame =
+	| {
+			type: 'message';
+			body: unknown;
+			discriminator?: string;
+	  }
+	| {
+			type: 'error';
+			error: string;
+			message?: string;
+	  };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "type": "module",
+  "name": "@atcute/firehose",
+  "version": "0.1.0",
+  "description": "lightweight and cute XRPC subscription client for AT Protocol",
+  "license": "0BSD",
+  "repository": {
+    "url": "https://github.com/mary-ext/atcute",
+    "directory": "packages/clients/firehose"
+  },
+  "files": [
+    "dist/",
+    "lib/",
+    "!lib/**/*.bench.ts",
+    "!lib/**/*.test.ts"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "@mary-ext/event-iterator": "^1.0.0",
+    "@mary-ext/simple-event-emitter": "^1.0.0",
+    "partysocket": "^1.1.6",
+    "type-fest": "^4.41.0",
+    "@atcute/lexicons": "^1.2.2",
+    "@atcute/cbor": "^2.2.7",
+    "@atcute/uint8array": "^1.0.5"
+  },
+  "devDependencies": {
+    "@atcute/atproto": "^3.1.8"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "prepublish": "rm -rf dist; pnpm run build"
+  }
+}