@justscale/core 0.1.0

package/dist/features/channel/channels.js

@@ -0,0 +1,252 @@
+/**
+ * Channels Factory
+ *
+ * Create a typed channels service for pub/sub messaging.
+ */
+import { AbstractChannelBackend, } from './backend.js';
+import { createChannel } from './channel.js';
+import { resolveChannelKey, } from './types.js';
+// Processable protocol support
+import { encodeProcessable, decodeProcessable, } from '../../process/serialization.js';
+const PAYLOAD_TAG = '__$p';
+/** Encode a message for cross-node delivery using Processable protocol */
+function encodeForBackend(message, descriptor) {
+    // Use explicit descriptor if provided (e.g. for proto schemas)
+    if (descriptor) {
+        return { [PAYLOAD_TAG]: descriptor.name, d: descriptor.serialize(message) };
+    }
+    // Auto-detect from message value (class instances, objects with [Symbol.process])
+    return encodeProcessable(message);
+}
+/** Decode a message received from the backend */
+function decodeFromBackend(message, descriptor) {
+    // Check for Processable-encoded message (from explicit descriptor encoding)
+    if (message != null &&
+        typeof message === 'object' &&
+        PAYLOAD_TAG in message) {
+        const encoded = message;
+        const name = encoded[PAYLOAD_TAG];
+        // Use explicit descriptor if name matches
+        if (descriptor && descriptor.name === name) {
+            return descriptor.deserialize(encoded.d);
+        }
+    }
+    // Fall back to generic decode (handles both __$p tagged and non-tagged)
+    return decodeProcessable(message);
+}
+/**
+ * Create a typed channels service.
+ *
+ * Channels provide pub/sub messaging where:
+ * - Subscribers receive messages via async iterables
+ * - Publishers broadcast to all subscribers of a channel
+ * - Hooks enable cluster integration for multi-node deployments
+ *
+ * @example Basic usage
+ * ```typescript
+ * // Define channels service
+ * const RoomChannels = createChannels<ServerMessage>();
+ *
+ * // Inject into service - channels key off Ref<T>, not string IDs.
+ * const ChatService = defineService({
+ *   inject: { channels: RoomChannels },
+ *   factory: ({ channels }) => ({
+ *     subscribe(room: Ref<Room>) {
+ *       return channels.subscribe(room);
+ *     },
+ *     broadcast(room: Ref<Room>, msg: ServerMessage) {
+ *       channels.publish(room, msg);
+ *     },
+ *   }),
+ * });
+ * ```
+ *
+ * @example With cluster hooks
+ * ```typescript
+ * const RoomChannels = createChannels<ServerMessage>().withHooks({
+ *   onFirstSubscriber: async (key) => {
+ *     // Register this node's interest at cluster level
+ *     await clusterRegistry.subscribe(Room.ref`${key}`);
+ *   },
+ *   onLastUnsubscribe: async (key) => {
+ *     // Unregister when no local subscribers remain
+ *     await clusterRegistry.unsubscribe(Room.ref`${key}`);
+ *   },
+ *   onPublish: (key, msg) => {
+ *     // Broadcast to other nodes via event bus - wire format carries
+ *     // the key; each recipient rebuilds its own typed ref.
+ *     events.emit(`room.${msg.type}`, { roomKey: key, ...msg });
+ *   },
+ * });
+ * ```
+ *
+ * @example In contextual controller
+ * ```typescript
+ * const join = Procedure("room/:roomId/join")
+ *   .handle(async function*({ params }) {
+ *     // Boundary: convert the raw path param to a typed reference.
+ *     const room = Room.ref`${params.roomId}`;
+ *     const subscription = channels.subscribe(room);
+ *
+ *     // Stream messages to client
+ *     for await (const msg of subscription) {
+ *       yield msg;
+ *     }
+ *     // Subscription auto-cleaned when generator exits
+ *   });
+ * ```
+ */
+export function createChannels(options = {}) {
+    const prefix = options.prefix ?? '';
+    // Trace helper
+    const TRACE_ENABLED = process.env.JUSTSCALE_TRACE === '1' || process.env.JUSTSCALE_TRACE === 'true';
+    function trace(message, data) {
+        if (!TRACE_ENABLED)
+            return;
+        const timestamp = new Date().toISOString();
+        const dataStr = data ? ' ' + JSON.stringify(data) : '';
+        console.debug(`[${timestamp}] [TRACE] [Channels] ${message}${dataStr}`);
+    }
+    const descriptor = options.descriptor;
+    const createInstance = (hooks, backend) => {
+        // Unique instance ID for debugging
+        const instanceId = `channels_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+        trace('createInstance', { instanceId, prefix });
+        // Channel storage (lazy creation)
+        const channels = new Map();
+        // Backend subscriptions (for cleanup)
+        const backendSubs = new Map();
+        // Apply prefix to channel key for backend communication
+        const toBackendKey = (channelKey) => `${prefix}${channelKey}`;
+        // Safely invoke a user hook: swallow sync throws and async rejections.
+        // User hooks are transport-side observability and must never crash the
+        // framework's pub/sub path.
+        const safeInvokeHook = (fn, label) => {
+            if (!fn)
+                return;
+            try {
+                const result = fn();
+                if (result && typeof result.catch === 'function') {
+                    result.catch((err) => {
+                        trace('userHook.asyncRejected', { instanceId, hook: label, error: String(err) });
+                        return undefined;
+                    });
+                }
+            }
+            catch (err) {
+                trace('userHook.syncThrew', { instanceId, hook: label, error: String(err) });
+            }
+        };
+        // Wrap hooks to integrate with backend
+        const effectiveHooks = {
+            onFirstSubscriber: (channelKey) => {
+                // Call user hook first (errors swallowed - observability only,
+                // independent of backend readiness so a buggy user hook can't break
+                // signal delivery).
+                safeInvokeHook(hooks?.onFirstSubscriber ? () => hooks.onFirstSubscriber(channelKey) : undefined, 'onFirstSubscriber');
+                // Subscribe to backend for remote messages (with prefix). Returning
+                // the backend's `.ready` here is what makes ChannelSubscription.ready
+                // wait for the LISTEN/SUBSCRIBE ACK — without it,
+                // publish-immediately-after-subscribe would race the wire setup.
+                const backendKey = toBackendKey(channelKey);
+                trace('onFirstSubscriber.backendSubscribe', { instanceId, channelKey, backendKey });
+                const sub = backend.subscribe(backendKey, (msg) => {
+                    // Decode Processable-encoded messages from remote nodes
+                    const decoded = decodeFromBackend(msg, descriptor);
+                    trace('backendCallback', { instanceId, channelKey, backendKey, hasChannel: channels.has(channelKey), subscriberCount: channels.get(channelKey)?.subscriberCount ?? 0 });
+                    const channel = channels.get(channelKey);
+                    if (channel && channel.subscriberCount > 0) {
+                        channel.deliverLocal(decoded);
+                    }
+                });
+                backendSubs.set(channelKey, sub);
+                return sub.ready;
+            },
+            onLastUnsubscribe: (channelKey) => {
+                // Unsubscribe from backend
+                const sub = backendSubs.get(channelKey);
+                if (sub) {
+                    sub[Symbol.dispose]();
+                    backendSubs.delete(channelKey);
+                }
+                // Call user hook (errors swallowed - observability only)
+                safeInvokeHook(hooks?.onLastUnsubscribe ? () => hooks.onLastUnsubscribe(channelKey) : undefined, 'onLastUnsubscribe');
+            },
+            onPublish: (channelKey, message) => {
+                // Encode message for cross-node delivery (Processable protocol)
+                const encoded = encodeForBackend(message, descriptor);
+                // Publish to backend for remote delivery (with prefix)
+                const backendKey = toBackendKey(channelKey);
+                trace('onPublish.toBackend', { instanceId, channelKey, backendKey });
+                backend.publish(backendKey, encoded);
+                // Call user hook with original message, not encoded (errors swallowed)
+                safeInvokeHook(hooks?.onPublish ? () => hooks.onPublish(channelKey, message) : undefined, 'onPublish');
+            },
+        };
+        const getOrCreateChannel = (channelKey) => {
+            let channel = channels.get(channelKey);
+            if (!channel) {
+                channel = createChannel(channelKey, effectiveHooks);
+                channels.set(channelKey, channel);
+            }
+            return channel;
+        };
+        return {
+            configureHooks(_hooks) {
+            },
+            subscribe(channelKey) {
+                const key = resolveChannelKey(channelKey);
+                trace('subscribe', { instanceId, channelKey: key });
+                const channel = getOrCreateChannel(key);
+                return channel.subscribe();
+            },
+            publish(channelKey, message) {
+                const key = resolveChannelKey(channelKey);
+                trace('publish', { instanceId, channelKey: key, subscriberCount: channels.get(key)?.subscriberCount ?? 0 });
+                const channel = getOrCreateChannel(key);
+                channel.publish(message);
+            },
+            deliverRemote(channelKey, message) {
+                const key = resolveChannelKey(channelKey);
+                trace('deliverRemote', { instanceId, channelKey: key, hasChannel: channels.has(key), subscriberCount: channels.get(key)?.subscriberCount ?? 0 });
+                // Decode Processable-encoded messages
+                const decoded = decodeFromBackend(message, descriptor);
+                // Only deliver if we have subscribers (otherwise ignore)
+                const channel = channels.get(key);
+                if (channel && channel.subscriberCount > 0) {
+                    // Deliver to local subscribers without triggering onPublish hook
+                    // (to avoid re-broadcasting back to cluster)
+                    channel.deliverLocal(decoded);
+                }
+            },
+            getChannel(channelKey) {
+                return getOrCreateChannel(resolveChannelKey(channelKey));
+            },
+            hasSubscribers(channelKey) {
+                const channel = channels.get(resolveChannelKey(channelKey));
+                return channel ? channel.subscriberCount > 0 : false;
+            },
+            getActiveChannels() {
+                return Array.from(channels.entries())
+                    .filter(([, ch]) => ch.subscriberCount > 0)
+                    .map(([key]) => key);
+            },
+            close() {
+                // Dispose all backend subscriptions
+                for (const [, sub] of backendSubs) {
+                    sub[Symbol.dispose]();
+                }
+                backendSubs.clear();
+                channels.clear();
+            },
+        };
+    };
+    return {
+        deps: { backend: AbstractChannelBackend },
+        factory: ({ backend }) => createInstance(options.hooks, backend),
+        withHooks(hooks) {
+            return createChannels({ ...options, hooks });
+        },
+    };
+}
+//# sourceMappingURL=channels.js.map

package/dist/features/channel/channels.js.map

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

package/dist/features/channel/feature.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Channel Feature
+ *
+ * Provides pub/sub channels with pluggable backends.
+ * Requires a channel backend to be registered before adding this feature.
+ */
+import { AbstractChannelBackend } from './backend.js';
+/**
+ * Channel Feature
+ *
+ * Validates that a channel backend has been registered.
+ * Add a backend using `bindService` before adding this feature.
+ *
+ * @example Using memory backend (for testing or single-node)
+ * ```typescript
+ * import { ChannelFeature, MemoryChannelBackend, AbstractChannelBackend, bindService } from '@justscale/core';
+ *
+ * const cluster = createClusterBuilder()
+ *   .add(MemoryChannelBackend)
+ *   .add(bindService(AbstractChannelBackend, MemoryChannelBackend))
+ *   .add(ChannelFeature)
+ *   .add(ChatService)
+ *   .build();
+ * ```
+ *
+ * @example Using Redis backend (for production/multi-node)
+ * ```typescript
+ * import { ChannelFeature, AbstractChannelBackend, bindService } from '@justscale/core';
+ * import { RedisChannelBackend } from '@justscale/redis';
+ *
+ * const cluster = createClusterBuilder()
+ *   .add(RedisChannelBackend)
+ *   .add(bindService(AbstractChannelBackend, RedisChannelBackend))
+ *   .add(ChannelFeature)
+ *   .add(ChatService)
+ *   .build();
+ * ```
+ */
+export declare const ChannelFeature: import("../../builder/types.js").FeatureToken<[typeof AbstractChannelBackend], []>;
+//# sourceMappingURL=feature.d.ts.map

package/dist/features/channel/feature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature.d.ts","sourceRoot":"","sources":["../../../src/features/channel/feature.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,cAAc,oFAGN,CAAC"}

package/dist/features/channel/feature.js

@@ -0,0 +1,44 @@
+/**
+ * Channel Feature
+ *
+ * Provides pub/sub channels with pluggable backends.
+ * Requires a channel backend to be registered before adding this feature.
+ */
+import { createFeatureBuilder } from '../../builder/index.js';
+import { AbstractChannelBackend } from './backend.js';
+/**
+ * Channel Feature
+ *
+ * Validates that a channel backend has been registered.
+ * Add a backend using `bindService` before adding this feature.
+ *
+ * @example Using memory backend (for testing or single-node)
+ * ```typescript
+ * import { ChannelFeature, MemoryChannelBackend, AbstractChannelBackend, bindService } from '@justscale/core';
+ *
+ * const cluster = createClusterBuilder()
+ *   .add(MemoryChannelBackend)
+ *   .add(bindService(AbstractChannelBackend, MemoryChannelBackend))
+ *   .add(ChannelFeature)
+ *   .add(ChatService)
+ *   .build();
+ * ```
+ *
+ * @example Using Redis backend (for production/multi-node)
+ * ```typescript
+ * import { ChannelFeature, AbstractChannelBackend, bindService } from '@justscale/core';
+ * import { RedisChannelBackend } from '@justscale/redis';
+ *
+ * const cluster = createClusterBuilder()
+ *   .add(RedisChannelBackend)
+ *   .add(bindService(AbstractChannelBackend, RedisChannelBackend))
+ *   .add(ChannelFeature)
+ *   .add(ChatService)
+ *   .build();
+ * ```
+ */
+export const ChannelFeature = createFeatureBuilder()
+    .name('channel')
+    .requires(AbstractChannelBackend)
+    .provides((b) => b);
+//# sourceMappingURL=feature.js.map

package/dist/features/channel/feature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature.js","sourceRoot":"","sources":["../../../src/features/channel/feature.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,oBAAoB,EAAE;KACjD,IAAI,CAAC,SAAS,CAAC;KACf,QAAQ,CAAC,sBAAsB,CAAC;KAChC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC"}

package/dist/features/channel/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Channel - Pub/Sub Channels
+ *
+ * Provides typed pub/sub messaging with:
+ * - Per-channel subscriptions (async iterables)
+ * - Reference counting for cluster optimization
+ * - Hooks for cluster integration
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createChannels } from "@justscale/core";
+ * import type { Ref } from "@justscale/core/models";
+ * import { Room } from "./room.model";
+ *
+ * // Define typed channels
+ * const RoomChannels = createChannels<ServerMessage>();
+ *
+ * // Inject into service - channels key off Ref<T>, not string IDs.
+ * const ChatService = defineService({
+ *   inject: { channels: RoomChannels },
+ *   factory: ({ channels }) => ({
+ *     subscribe(room: Ref<Room>) {
+ *       return channels.subscribe(room);
+ *     },
+ *     broadcast(room: Ref<Room>, msg: ServerMessage) {
+ *       channels.publish(room, msg);
+ *     },
+ *   }),
+ * });
+ * ```
+ */
+export { ChannelFeature } from './feature.js';
+export { createChannels } from './channels.js';
+export type { ChannelsDef } from './channels.js';
+export { AbstractChannelBackend, MemoryChannelBackend } from './backend.js';
+export type { BackendSubscription, ChannelBackend, ChannelBackendInstance } from './backend.js';
+export type { Channel, ChannelKey, ChannelSubscription, ChannelsInstance, ChannelsOptions, ChannelHooks, } from './types.js';
+export { resolveChannelKey } from './types.js';
+export { createChannel } from './channel.js';
+export type { ChannelInternal } from './channel.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/features/channel/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/channel/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAC5E,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAGhG,YAAY,EACV,OAAO,EACP,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAG/C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

package/dist/features/channel/index.js

@@ -0,0 +1,41 @@
+/**
+ * Channel - Pub/Sub Channels
+ *
+ * Provides typed pub/sub messaging with:
+ * - Per-channel subscriptions (async iterables)
+ * - Reference counting for cluster optimization
+ * - Hooks for cluster integration
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createChannels } from "@justscale/core";
+ * import type { Ref } from "@justscale/core/models";
+ * import { Room } from "./room.model";
+ *
+ * // Define typed channels
+ * const RoomChannels = createChannels<ServerMessage>();
+ *
+ * // Inject into service - channels key off Ref<T>, not string IDs.
+ * const ChatService = defineService({
+ *   inject: { channels: RoomChannels },
+ *   factory: ({ channels }) => ({
+ *     subscribe(room: Ref<Room>) {
+ *       return channels.subscribe(room);
+ *     },
+ *     broadcast(room: Ref<Room>, msg: ServerMessage) {
+ *       channels.publish(room, msg);
+ *     },
+ *   }),
+ * });
+ * ```
+ */
+// Feature
+export { ChannelFeature } from './feature.js';
+// Main factory
+export { createChannels } from './channels.js';
+// Backend (for implementing custom backends)
+export { AbstractChannelBackend, MemoryChannelBackend } from './backend.js';
+export { resolveChannelKey } from './types.js';
+// Internal (for advanced use)
+export { createChannel } from './channel.js';
+//# sourceMappingURL=index.js.map

package/dist/features/channel/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/features/channel/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,UAAU;AACV,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,eAAe;AACf,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C,6CAA6C;AAC7C,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAY5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,8BAA8B;AAC9B,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/features/channel/types.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Channel Types
+ *
+ * Core types for the channels pub/sub system.
+ */
+/**
+ * A channel key: a plain string or anything with an `identifier` property
+ * (e.g. a Reference from a model).
+ */
+export type ChannelKey = string | {
+    readonly identifier: string;
+};
+/** Resolve a ChannelKey to a plain string. */
+export declare function resolveChannelKey(key: ChannelKey): string;
+/**
+ * A subscription to a channel.
+ * Implements AsyncIterable for streaming messages and Disposable for cleanup.
+ */
+export interface ChannelSubscription<TMessage> extends AsyncIterable<TMessage>, Disposable {
+    /** Unsubscribe from the channel */
+    unsubscribe(): void;
+    /** The channel key this subscription is for */
+    readonly channelKey: string;
+    /** Whether this subscription is still active */
+    readonly active: boolean;
+    /**
+     * Resolves when the underlying backend subscription has been ACKed (e.g.
+     * Postgres LISTEN, Redis SUBSCRIBE), AND the cluster `onFirstSubscriber`
+     * hook (if any) has completed. Messages published before this settles may
+     * be missed at the backend level.
+     *
+     * Reject on backend connect / listen failure — callers that
+     * publish-immediately-after-subscribe MUST `await sub.ready` first.
+     *
+     * For local-only channels (no remote backend), resolves synchronously.
+     */
+    readonly ready: Promise<void>;
+}
+/**
+ * A single channel instance that can be published to and subscribed from.
+ */
+export interface Channel<TMessage> {
+    /** The channel key */
+    readonly key: string;
+    /** Current number of local subscribers */
+    readonly subscriberCount: number;
+    /** Subscribe to this channel */
+    subscribe(): ChannelSubscription<TMessage>;
+    /** Publish a message to all subscribers */
+    publish(message: TMessage): void;
+}
+/**
+ * Hooks for cluster integration.
+ * Called when subscription state changes on this node.
+ */
+export interface ChannelHooks {
+    /**
+     * Called when the first subscriber joins a channel on this node.
+     * Use this to register interest at the cluster level.
+     */
+    onFirstSubscriber?: (channelKey: string) => void | Promise<void>;
+    /**
+     * Called when the last subscriber leaves a channel on this node.
+     * Use this to unregister interest at the cluster level.
+     */
+    onLastUnsubscribe?: (channelKey: string) => void | Promise<void>;
+    /**
+     * Called when a message is published locally.
+     * Use this to broadcast to other cluster nodes.
+     */
+    onPublish?: (channelKey: string, message: unknown) => void | Promise<void>;
+}
+/**
+ * Options for creating a channels service.
+ */
+export interface ChannelsOptions {
+    /**
+     * Prefix for channel keys when communicating with the backend.
+     * E.g., "room:" means channel "123" becomes "room:123" for the backend.
+     * @default ""
+     */
+    prefix?: string;
+    /** Hooks for cluster integration */
+    hooks?: ChannelHooks;
+    /**
+     * Process descriptor for encoding/decoding messages via the Processable protocol.
+     *
+     * When provided, messages are encoded before cross-node delivery and decoded
+     * on receipt. This enables efficient binary serialization for proto types.
+     *
+     * If not provided, messages from class instances with static [Symbol.process]
+     * are automatically detected and encoded at publish time.
+     *
+     * @example Proto channels
+     * ```typescript
+     * import { ChatEventSchema } from './events.proto'
+     * const RoomChannels = createChannels<ChatEvent>({
+     *   descriptor: ChatEventSchema[Symbol.process],
+     * })
+     * ```
+     */
+    descriptor?: ProcessDescriptor;
+}
+/**
+ * Runtime instance of a channels service.
+ */
+export interface ChannelsInstance<TMessage> {
+    /** Configure hooks at runtime. Prefer withHooks() on the ChannelsDef instead. */
+    configureHooks(hooks: ChannelHooks): void;
+    /**
+     * Subscribe to a channel by key.
+     * Returns an async iterable subscription.
+     *
+     * @example
+     * ```typescript
+     * const subscription = channels.subscribe(Room.ref`123`);
+     * for await (const msg of subscription) {
+     *   client.send(msg);
+     * }
+     * ```
+     */
+    subscribe(channelKey: ChannelKey): ChannelSubscription<TMessage>;
+    /**
+     * Publish a message to a channel.
+     * Message is delivered to all local subscribers and (via hooks) to remote nodes.
+     *
+     * @example
+     * ```typescript
+     * channels.publish(Room.ref`123`, { type: "message", content: "Hello!" });
+     * ```
+     */
+    publish(channelKey: ChannelKey, message: TMessage): void;
+    /**
+     * Deliver a message from a remote node.
+     * Use this in your cluster event handler.
+     *
+     * @example
+     * ```typescript
+     * // In event controller
+     * onRoomEvent: Events.on("room.*").handle(({ payload }) => {
+     *   channels.deliverRemote(payload.room, payload);
+     * })
+     * ```
+     */
+    deliverRemote(channelKey: ChannelKey, message: TMessage): void;
+    /**
+     * Get a channel by key (creates if not exists).
+     */
+    getChannel(channelKey: ChannelKey): Channel<TMessage>;
+    /**
+     * Check if a channel has any local subscribers.
+     */
+    hasSubscribers(channelKey: ChannelKey): boolean;
+    /**
+     * Get all channel keys that have subscribers.
+     */
+    getActiveChannels(): string[];
+    /**
+     * Close the channels instance and release all resources.
+     * Disposes all backend subscriptions and clears channel state.
+     * Call this when shutting down to ensure clean exit.
+     */
+    close(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/features/channel/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/features/channel/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,8CAA8C;AAC9C,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAEzD;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB,CAAC,QAAQ,CAC3C,SAAQ,aAAa,CAAC,QAAQ,CAAC,EAC/B,UAAU;IACV,mCAAmC;IACnC,WAAW,IAAI,IAAI,CAAA;IAEnB,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAE3B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IAExB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,OAAO,CAAC,QAAQ;IAC/B,sBAAsB;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IAEpB,0CAA0C;IAC1C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAEhC,gCAAgC;IAChC,SAAS,IAAI,mBAAmB,CAAC,QAAQ,CAAC,CAAA;IAE1C,2CAA2C;IAC3C,OAAO,CAAC,OAAO,EAAE,QAAQ,GAAG,IAAI,CAAA;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhE;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhE;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3E;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,oCAAoC;IACpC,KAAK,CAAC,EAAE,YAAY,CAAA;IAEpB;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAA;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ;IACxC,iFAAiF;IACjF,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAA;IAEzC;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAA;IAEhE;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,GAAG,IAAI,CAAA;IAExD;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,GAAG,IAAI,CAAA;IAE9D;;OAEG;IACH,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAErD;;OAEG;IACH,cAAc,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAA;IAE/C;;OAEG;IACH,iBAAiB,IAAI,MAAM,EAAE,CAAA;IAE7B;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAAA;CACd"}

package/dist/features/channel/types.js

@@ -0,0 +1,10 @@
+/**
+ * Channel Types
+ *
+ * Core types for the channels pub/sub system.
+ */
+/** Resolve a ChannelKey to a plain string. */
+export function resolveChannelKey(key) {
+    return typeof key === 'string' ? key : key.identifier;
+}
+//# sourceMappingURL=types.js.map

package/dist/features/channel/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/features/channel/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,8CAA8C;AAC9C,MAAM,UAAU,iBAAiB,CAAC,GAAe;IAC/C,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC;AACxD,CAAC"}