@solana/subscribable 6.3.1 → 6.3.2-canary-20260313112147

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/subscribable",
-  "version": "6.3.1",
+  "version": "6.3.2-canary-20260313112147",
   "description": "Helpers for creating subscription-based event emitters",
   "homepage": "https://www.solanakit.com/api#solanasubscribable",
   "exports": {
@@ -33,7 +33,8 @@
   "types": "./dist/types/index.d.ts",
   "type": "commonjs",
   "files": [
-    "./dist/"
+    "./dist/",
+    "./src/"
   ],
   "sideEffects": false,
   "keywords": [
@@ -55,7 +56,7 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/errors": "6.3.1"
+    "@solana/errors": "6.3.2-canary-20260313112147"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

package/src/async-iterable.ts

@@ -0,0 +1,231 @@
+import {
+    SOLANA_ERROR__INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_MUST_NOT_POLL_BEFORE_RESOLVING_EXISTING_MESSAGE_PROMISE,
+    SOLANA_ERROR__INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_STATE_MISSING,
+    SolanaError,
+} from '@solana/errors';
+import { AbortController } from '@solana/event-target-impl';
+
+import { DataPublisher } from './data-publisher';
+
+type Config = Readonly<{
+    /**
+     * Triggering this abort signal will cause all iterators spawned from this iterator to return
+     * once they have published all queued messages.
+     */
+    abortSignal: AbortSignal;
+    /**
+     * Messages from this channel of `dataPublisher` will be the ones yielded through the iterators.
+     *
+     * Messages only begin to be queued after the first time an iterator begins to poll. Channel
+     * messages published before that time will be dropped.
+     */
+    dataChannelName: string;
+    // FIXME: It would be nice to be able to constrain the type of `dataPublisher` to one that
+    //        definitely supports the `dataChannelName` and `errorChannelName` channels, and
+    //        furthermore publishes `TData` on the `dataChannelName` channel. This is more difficult
+    //        than it should be: https://tsplay.dev/NlZelW
+    dataPublisher: DataPublisher;
+    /**
+     * Messages from this channel of `dataPublisher` will be the ones thrown through the iterators.
+     *
+     * Any new iterators created after the first error is encountered will reject with that error
+     * when polled.
+     */
+    errorChannelName: string;
+}>;
+
+const enum PublishType {
+    DATA,
+    ERROR,
+}
+
+type IteratorKey = symbol;
+type IteratorState<TData> =
+    | {
+          __hasPolled: false;
+          publishQueue: (
+              | {
+                    __type: PublishType.DATA;
+                    data: TData;
+                }
+              | {
+                    __type: PublishType.ERROR;
+                    err: unknown;
+                }
+          )[];
+      }
+    | {
+          __hasPolled: true;
+          onData: (data: TData) => void;
+          onError: Parameters<ConstructorParameters<typeof Promise>[0]>[1];
+      };
+
+let EXPLICIT_ABORT_TOKEN: symbol;
+function createExplicitAbortToken() {
+    // This function is an annoying workaround to prevent `process.env.NODE_ENV` from appearing at
+    // the top level of this module and thwarting an optimizing compiler's attempt to tree-shake.
+    return Symbol(
+        __DEV__
+            ? "This symbol is thrown from a socket's iterator when the connection is explicitly " +
+                  'aborted by the user'
+            : undefined,
+    );
+}
+
+const UNINITIALIZED = Symbol();
+
+/**
+ * Returns an `AsyncIterable` given a data publisher.
+ *
+ * The iterable will produce iterators that vend messages published to `dataChannelName` and will
+ * throw the first time a message is published to `errorChannelName`. Triggering the abort signal
+ * will cause all iterators spawned from this iterator to return once they have published all queued
+ * messages.
+ *
+ * Things to note:
+ *
+ * - If a message is published over a channel before the `AsyncIterator` attached to it has polled
+ *   for the next result, the message will be queued in memory.
+ * - Messages only begin to be queued after the first time an iterator begins to poll. Channel
+ *   messages published before that time will be dropped.
+ * - If there are messages in the queue and an error occurs, all queued messages will be vended to
+ *   the iterator before the error is thrown.
+ * - If there are messages in the queue and the abort signal fires, all queued messages will be
+ *   vended to the iterator after which it will return.
+ * - Any new iterators created after the first error is encountered will reject with that error when
+ *   polled.
+ *
+ * @param config
+ *
+ * @example
+ * ```ts
+ * const iterable = createAsyncIterableFromDataPublisher({
+ *     abortSignal: AbortSignal.timeout(10_000),
+ *     dataChannelName: 'message',
+ *     dataPublisher,
+ *     errorChannelName: 'error',
+ * });
+ * try {
+ *     for await (const message of iterable) {
+ *         console.log('Got message', message);
+ *     }
+ * } catch (e) {
+ *     console.error('An error was published to the error channel', e);
+ * } finally {
+ *     console.log("It's been 10 seconds; that's enough for now.");
+ * }
+ * ```
+ */
+export function createAsyncIterableFromDataPublisher<TData>({
+    abortSignal,
+    dataChannelName,
+    dataPublisher,
+    errorChannelName,
+}: Config): AsyncIterable<TData> {
+    const iteratorState: Map<IteratorKey, IteratorState<TData>> = new Map();
+    function publishErrorToAllIterators(reason: unknown) {
+        for (const [iteratorKey, state] of iteratorState.entries()) {
+            if (state.__hasPolled) {
+                iteratorState.delete(iteratorKey);
+                state.onError(reason);
+            } else {
+                state.publishQueue.push({
+                    __type: PublishType.ERROR,
+                    err: reason,
+                });
+            }
+        }
+    }
+    const abortController = new AbortController();
+    abortSignal.addEventListener('abort', () => {
+        abortController.abort();
+        publishErrorToAllIterators((EXPLICIT_ABORT_TOKEN ||= createExplicitAbortToken()));
+    });
+    const options = { signal: abortController.signal } as const;
+    let firstError: unknown = UNINITIALIZED;
+    dataPublisher.on(
+        errorChannelName,
+        err => {
+            if (firstError === UNINITIALIZED) {
+                firstError = err;
+                abortController.abort();
+                publishErrorToAllIterators(err);
+            }
+        },
+        options,
+    );
+    dataPublisher.on(
+        dataChannelName,
+        data => {
+            iteratorState.forEach((state, iteratorKey) => {
+                if (state.__hasPolled) {
+                    const { onData } = state;
+                    iteratorState.set(iteratorKey, { __hasPolled: false, publishQueue: [] });
+                    onData(data as TData);
+                } else {
+                    state.publishQueue.push({
+                        __type: PublishType.DATA,
+                        data: data as TData,
+                    });
+                }
+            });
+        },
+        options,
+    );
+    return {
+        async *[Symbol.asyncIterator]() {
+            if (abortSignal.aborted) {
+                return;
+            }
+            if (firstError !== UNINITIALIZED) {
+                throw firstError;
+            }
+            const iteratorKey = Symbol();
+            iteratorState.set(iteratorKey, { __hasPolled: false, publishQueue: [] });
+            try {
+                while (true) {
+                    const state = iteratorState.get(iteratorKey);
+                    if (!state) {
+                        // There should always be state by now.
+                        throw new SolanaError(SOLANA_ERROR__INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_STATE_MISSING);
+                    }
+                    if (state.__hasPolled) {
+                        // You should never be able to poll twice in a row.
+                        throw new SolanaError(
+                            SOLANA_ERROR__INVARIANT_VIOLATION__SUBSCRIPTION_ITERATOR_MUST_NOT_POLL_BEFORE_RESOLVING_EXISTING_MESSAGE_PROMISE,
+                        );
+                    }
+                    const publishQueue = state.publishQueue;
+                    try {
+                        if (publishQueue.length) {
+                            state.publishQueue = [];
+                            for (const item of publishQueue) {
+                                if (item.__type === PublishType.DATA) {
+                                    yield item.data;
+                                } else {
+                                    throw item.err;
+                                }
+                            }
+                        } else {
+                            yield await new Promise<TData>((resolve, reject) => {
+                                iteratorState.set(iteratorKey, {
+                                    __hasPolled: true,
+                                    onData: resolve,
+                                    onError: reject,
+                                });
+                            });
+                        }
+                    } catch (e) {
+                        if (e === (EXPLICIT_ABORT_TOKEN ||= createExplicitAbortToken())) {
+                            return;
+                        } else {
+                            throw e;
+                        }
+                    }
+                }
+            } finally {
+                iteratorState.delete(iteratorKey);
+            }
+        },
+    };
+}

package/src/data-publisher.ts

@@ -0,0 +1,73 @@
+import { TypedEventEmitter, TypedEventTarget } from './event-emitter';
+
+type UnsubscribeFn = () => void;
+
+/**
+ * Represents an object with an `on` function that you can call to subscribe to certain data over a
+ * named channel.
+ *
+ * @example
+ * ```ts
+ * let dataPublisher: DataPublisher<{ error: SolanaError }>;
+ * dataPublisher.on('data', handleData); // ERROR. `data` is not a known channel name.
+ * dataPublisher.on('error', e => {
+ *     console.error(e);
+ * }); // OK.
+ * ```
+ */
+export interface DataPublisher<TDataByChannelName extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Call this to subscribe to data over a named channel.
+     *
+     * @param channelName The name of the channel on which to subscribe for messages
+     * @param subscriber The function to call when a message becomes available
+     * @param options.signal An abort signal you can fire to unsubscribe
+     *
+     * @returns A function that you can call to unsubscribe
+     */
+    on<const TChannelName extends keyof TDataByChannelName>(
+        channelName: TChannelName,
+        subscriber: (data: TDataByChannelName[TChannelName]) => void,
+        options?: { signal: AbortSignal },
+    ): UnsubscribeFn;
+}
+
+/**
+ * Returns an object with an `on` function that you can call to subscribe to certain data over a
+ * named channel.
+ *
+ * The `on` function returns an unsubscribe function.
+ *
+ * @example
+ * ```ts
+ * const socketDataPublisher = getDataPublisherFromEventEmitter(new WebSocket('wss://api.devnet.solana.com'));
+ * const unsubscribe = socketDataPublisher.on('message', message => {
+ *     if (JSON.parse(message.data).id === 42) {
+ *         console.log('Got response 42');
+ *         unsubscribe();
+ *     }
+ * });
+ * ```
+ */
+export function getDataPublisherFromEventEmitter<TEventMap extends Record<string, Event>>(
+    eventEmitter: TypedEventEmitter<TEventMap> | TypedEventTarget<TEventMap>,
+): DataPublisher<{
+    [TEventType in keyof TEventMap]: TEventMap[TEventType] extends CustomEvent ? TEventMap[TEventType]['detail'] : null;
+}> {
+    return {
+        on(channelName, subscriber, options) {
+            function innerListener(ev: Event) {
+                if (ev instanceof CustomEvent) {
+                    const data = (ev as CustomEvent<TEventMap[typeof channelName]>).detail;
+                    (subscriber as unknown as (data: TEventMap[typeof channelName]) => void)(data);
+                } else {
+                    (subscriber as () => void)();
+                }
+            }
+            eventEmitter.addEventListener(channelName, innerListener, options);
+            return () => {
+                eventEmitter.removeEventListener(channelName, innerListener);
+            };
+        },
+    };
+}

package/src/demultiplex.ts

@@ -0,0 +1,97 @@
+import { EventTarget } from '@solana/event-target-impl';
+
+import { DataPublisher, getDataPublisherFromEventEmitter } from './data-publisher';
+
+/**
+ * Given a channel that carries messages for multiple subscribers on a single channel name, this
+ * function returns a new {@link DataPublisher} that splits them into multiple channel names.
+ *
+ * @param messageTransformer A function that receives the message as the first argument, and returns
+ * a tuple of the derived channel name and the message.
+ *
+ * @example
+ * Imagine a channel that carries multiple notifications whose destination is contained within the
+ * message itself.
+ *
+ * ```ts
+ * const demuxedDataPublisher = demultiplexDataPublisher(channel, 'message', message => {
+ *     const destinationChannelName = `notification-for:${message.subscriberId}`;
+ *     return [destinationChannelName, message];
+ * });
+ * ```
+ *
+ * Now you can subscribe to _only_ the messages you are interested in, without having to subscribe
+ * to the entire `'message'` channel and filter out the messages that are not for you.
+ *
+ * ```ts
+ * demuxedDataPublisher.on(
+ *     'notification-for:123',
+ *     message => {
+ *         console.log('Got a message for subscriber 123', message);
+ *     },
+ *     { signal: AbortSignal.timeout(5_000) },
+ * );
+ * ```
+ */
+export function demultiplexDataPublisher<
+    TDataPublisher extends DataPublisher,
+    const TChannelName extends Parameters<TDataPublisher['on']>[0],
+>(
+    publisher: TDataPublisher,
+    sourceChannelName: TChannelName,
+    messageTransformer: (
+        // FIXME: Deriving the type of the message from `TDataPublisher` and `TChannelName` would
+        //        help callers to constrain their transform functions.
+        message: unknown,
+    ) => [destinationChannelName: string, message: unknown] | void,
+): DataPublisher {
+    let innerPublisherState:
+        | {
+              readonly dispose: () => void;
+              numSubscribers: number;
+          }
+        | undefined;
+    const eventTarget = new EventTarget();
+    const demultiplexedDataPublisher = getDataPublisherFromEventEmitter(eventTarget);
+    return {
+        ...demultiplexedDataPublisher,
+        on(channelName, subscriber, options) {
+            if (!innerPublisherState) {
+                const innerPublisherUnsubscribe = publisher.on(sourceChannelName, sourceMessage => {
+                    const transformResult = messageTransformer(sourceMessage);
+                    if (!transformResult) {
+                        return;
+                    }
+                    const [destinationChannelName, message] = transformResult;
+                    eventTarget.dispatchEvent(
+                        new CustomEvent(destinationChannelName, {
+                            detail: message,
+                        }),
+                    );
+                });
+                innerPublisherState = {
+                    dispose: innerPublisherUnsubscribe,
+                    numSubscribers: 0,
+                };
+            }
+            innerPublisherState.numSubscribers++;
+            const unsubscribe = demultiplexedDataPublisher.on(channelName, subscriber, options);
+            let isActive = true;
+            function handleUnsubscribe() {
+                if (!isActive) {
+                    return;
+                }
+                isActive = false;
+                options?.signal.removeEventListener('abort', handleUnsubscribe);
+                innerPublisherState!.numSubscribers--;
+                if (innerPublisherState!.numSubscribers === 0) {
+                    innerPublisherState!.dispose();
+                    innerPublisherState = undefined;
+                }
+                unsubscribe();
+            }
+            options?.signal.addEventListener('abort', handleUnsubscribe);
+            return handleUnsubscribe;
+        },
+    };
+}

package/src/event-emitter.ts

@@ -0,0 +1,55 @@
+type EventMap = Record<string, Event>;
+type Listener<TEvent extends Event> = ((evt: TEvent) => void) | { handleEvent(object: TEvent): void };
+
+/**
+ * This type allows you to type `addEventListener` and `removeEventListener` so that the call
+ * signature of the listener matches the event type given.
+ *
+ * @example
+ * ```ts
+ * const emitter: TypedEventEmitter<{ message: MessageEvent }> = new WebSocket('wss://api.devnet.solana.com');
+ * emitter.addEventListener('data', handleData); // ERROR. `data` is not a known event type.
+ * emitter.addEventListener('message', message => {
+ *     console.log(message.origin); // OK. `message` is a `MessageEvent` so it has an `origin` property.
+ * });
+ * ```
+ */
+export interface TypedEventEmitter<TEventMap extends EventMap> {
+    addEventListener<const TEventType extends keyof TEventMap>(
+        type: TEventType,
+        listener: Listener<TEventMap[TEventType]>,
+        options?: AddEventListenerOptions | boolean,
+    ): void;
+    removeEventListener<const TEventType extends keyof TEventMap>(
+        type: TEventType,
+        listener: Listener<TEventMap[TEventType]>,
+        options?: EventListenerOptions | boolean,
+    ): void;
+}
+
+// Why not just extend the interface above, rather than to copy/paste it?
+// See https://github.com/microsoft/TypeScript/issues/60008
+/**
+ * This type is a superset of `TypedEventEmitter` that allows you to constrain calls to
+ * `dispatchEvent`.
+ *
+ * @example
+ * ```ts
+ * const target: TypedEventTarget<{ candyVended: CustomEvent<{ flavour: string }> }> = new EventTarget();
+ * target.dispatchEvent(new CustomEvent('candyVended', { detail: { flavour: 'raspberry' } })); // OK.
+ * target.dispatchEvent(new CustomEvent('candyVended', { detail: { flavor: 'raspberry' } })); // ERROR. Misspelling in detail.
+ * ```
+ */
+export interface TypedEventTarget<TEventMap extends EventMap> {
+    addEventListener<const TEventType extends keyof TEventMap>(
+        type: TEventType,
+        listener: Listener<TEventMap[TEventType]>,
+        options?: AddEventListenerOptions | boolean,
+    ): void;
+    dispatchEvent<TEventType extends keyof TEventMap>(ev: TEventMap[TEventType]): void;
+    removeEventListener<const TEventType extends keyof TEventMap>(
+        type: TEventType,
+        listener: Listener<TEventMap[TEventType]>,
+        options?: EventListenerOptions | boolean,
+    ): void;
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * This package contains utilities for creating subscription-based event targets. These differ from
+ * the `EventTarget` interface in that the method you use to add a listener returns an unsubscribe
+ * function. It is primarily intended for internal use -- particularly for those building
+ * {@link RpcSubscriptionChannel | RpcSubscriptionChannels} and associated infrastructure.
+ *
+ * @packageDocumentation
+ */
+export * from './async-iterable';
+export * from './data-publisher';
+export * from './demultiplex';
+export * from './event-emitter';