@rlanz/socket 0.0.1-0

package/build/shared_types-Dw9AphfO.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Types shared between the server and the client.
+ */
+/**
+ * Message sent by the client to a channel.
+ */
+interface ChannelMessage {
+    channel: string;
+    event: string;
+    data?: unknown;
+}
+/**
+ * Channel handler acknowledgement response.
+ */
+interface ChannelAck<T = unknown> {
+    ok: boolean;
+    data?: T;
+    error?: string;
+}
+
+export type { ChannelAck as C, ChannelMessage as a };

package/build/socket_service-jxIaH5Rs.d.ts

@@ -0,0 +1,144 @@
+import { Server } from 'node:http';
+import { Logger } from '@adonisjs/logger';
+import Emittery from 'emittery';
+import { WebSocketServer } from 'ws';
+import { B as BaseChannel, b as ChannelMatch, A as AuthenticatedSocket, C as ChannelEventMap, c as PresenceData, d as ChannelOptions, S as SocketEvents, P as PresenceManager, e as SocketConfig, f as SocketServiceStatus, g as SocketHealthSnapshot } from './types-C0rDwbry.js';
+
+/**
+ * Matches channel names against registered patterns.
+ *
+ * Pattern: chat/:roomId
+ * Channel: chat/general
+ *
+ * chat / :roomId
+ *   |      |
+ * chat / general  => { roomId: "general" }
+ */
+declare class ChannelRouter {
+    #private;
+    /**
+     * Registers a channel.
+     */
+    register(channel: typeof BaseChannel): void;
+    /**
+     * Matches a channel name against registered patterns.
+     */
+    match(channelName: string): ChannelMatch | null;
+    /**
+     * Authorizes a socket before it joins a channel.
+     */
+    authorize<User = unknown, HttpContext = unknown>(socket: AuthenticatedSocket<User, HttpContext>, channelName: string): Promise<{
+        readonly success: false;
+        readonly error: string;
+        readonly instance?: undefined;
+        readonly params?: undefined;
+        readonly paramValues?: undefined;
+        readonly presenceData?: undefined;
+    } | {
+        readonly success: true;
+        readonly instance: BaseChannel<User, ChannelEventMap, HttpContext>;
+        readonly params: Record<string, string>;
+        readonly paramValues: string[];
+        readonly presenceData: Record<string, unknown> | PresenceData | null;
+        readonly error?: undefined;
+    }>;
+    /**
+     * Lists all registered channels.
+     */
+    list(): {
+        pattern: string;
+        name: string;
+        options: ChannelOptions | undefined;
+    }[];
+    /**
+     * Number of registered channels.
+     */
+    get size(): number;
+}
+
+type SocketEmission = {
+    target: 'global';
+    event: string;
+    data: unknown;
+} | {
+    target: 'channel';
+    channel: string;
+    event: string;
+    data: unknown;
+    except?: string[];
+} | {
+    target: 'user';
+    userId: string | number;
+    room: string;
+    event: string;
+    data: unknown;
+};
+type SocketEmissionTarget = SocketEmission['target'];
+interface SocketEmissionSink {
+    dispatch(emission: SocketEmission): void;
+}
+
+type SocketFakeTarget = SocketEmissionTarget;
+type SocketFakeEmission = SocketEmission;
+interface SocketFakeEmissionQuery {
+    data?: unknown | ((data: unknown) => boolean);
+    except?: string[] | ((except: string[] | undefined) => boolean);
+}
+interface SocketFakeCountQuery extends SocketFakeEmissionQuery {
+    target?: SocketFakeTarget;
+    event?: string;
+    channel?: string;
+    userId?: string | number;
+}
+declare class SocketFake implements SocketEmissionSink {
+    #private;
+    constructor(restore: () => void);
+    get emissions(): SocketFakeEmission[];
+    record(emission: SocketFakeEmission): void;
+    dispatch(emission: SocketFakeEmission): void;
+    clear(): void;
+    restore(): void;
+    [Symbol.dispose](): void;
+    assertBroadcasted(event: string, query?: SocketFakeEmissionQuery): void;
+    assertNotBroadcasted(event: string, query?: SocketFakeEmissionQuery): void;
+    assertEmittedTo(channel: string, event: string, query?: SocketFakeEmissionQuery): void;
+    assertNotEmittedTo(channel: string, event: string, query?: SocketFakeEmissionQuery): void;
+    assertEmittedToUser(userId: string | number, event: string, query?: SocketFakeEmissionQuery): void;
+    assertNotEmittedToUser(userId: string | number, event: string, query?: SocketFakeEmissionQuery): void;
+    assertEmittedCount(count: number, query?: SocketFakeCountQuery): void;
+    assertNothingEmitted(): void;
+}
+
+/**
+ * Main service for managing WebSocket connections.
+ */
+declare class SocketService<User = unknown, HttpContext = unknown> extends Emittery<SocketEvents<User, HttpContext>> {
+    #private;
+    /**
+     * Accesses the underlying ws server.
+     */
+    get server(): WebSocketServer;
+    setPresenceManager(presenceManager: PresenceManager): void;
+    boot(httpServer: Server, config: SocketConfig<User, HttpContext>, channelRouter: ChannelRouter, logger: Logger): Promise<void>;
+    to(channel: string): {
+        emit: (event: string, data: unknown) => void;
+        except: (socketId: string) => {
+            emit: (event: string, data: unknown) => void;
+        };
+    };
+    toUser(userId: string | number): {
+        emit: (event: string, data: unknown) => void;
+    };
+    broadcast(event: string, data: unknown): void;
+    getSocket(socketId: string): AuthenticatedSocket<User, HttpContext> | undefined;
+    get connectionsCount(): number;
+    get status(): SocketServiceStatus;
+    get ready(): boolean;
+    fake(): SocketFake;
+    restore(): void;
+    markFailed(error: unknown): void;
+    health(): SocketHealthSnapshot;
+    close(): Promise<void>;
+}
+
+export { ChannelRouter as C, SocketService as S, SocketFake as a, type SocketFakeCountQuery as b, type SocketFakeEmission as c, type SocketFakeEmissionQuery as d, type SocketFakeTarget as e };

package/build/src/client/index.d.ts

@@ -0,0 +1,106 @@
+import { SocketClientTransport, PresenceUser, EventHandler, SubscribeOptions, UnsubscribeOptions, SocketOptions, ConnectionState } from './types.js';
+export { PresenceData, SubscribeAckData, SubscribeResult } from './types.js';
+export { C as ChannelAck, a as ChannelMessage } from '../../shared_types-Dw9AphfO.js';
+
+/**
+ * Represents a subscribed channel.
+ * Chainable API inspired by Laravel Echo.
+ *
+ * @example
+ * ```ts
+ * socket.channel('chat/general')
+ *   .here((users) => setOnlineUsers(users))
+ *   .joining((user) => console.log(`${user.name} joined`))
+ *   .leaving((user) => console.log(`${user.name} left`))
+ *   .listen('chat:message', (msg) => addMessage(msg))
+ *   .subscribe()
+ * ```
+ */
+declare class Channel {
+    #private;
+    /**
+     * Channel name.
+     */
+    readonly name: string;
+    constructor(name: string, transport: SocketClientTransport);
+    /**
+     * Whether the channel should stay subscribed.
+     */
+    get subscribed(): boolean;
+    /**
+     * Whether the channel is active on the server.
+     */
+    get active(): boolean;
+    /**
+     * List of present users.
+     */
+    get users(): PresenceUser[];
+    /**
+     * Number of present users.
+     */
+    get count(): number;
+    /**
+     * Registers a handler called with the present users.
+     * Called immediately on subscribe and after each presence change.
+     */
+    here(handler: EventHandler<PresenceUser[]>): this;
+    /**
+     * Registers a handler called when a user joins.
+     */
+    joining(handler: EventHandler<PresenceUser>): this;
+    /**
+     * Registers a handler called when a user leaves.
+     */
+    leaving(handler: EventHandler<PresenceUser>): this;
+    /**
+     * Listens for an event on this channel.
+     */
+    listen<T = unknown>(event: string, handler: EventHandler<T>): this;
+    /**
+     * Removes an event listener.
+     */
+    stopListening(event: string, handler?: EventHandler): this;
+    /**
+     * Subscribes to the channel.
+     *
+     * client listeners -> subscribe ack -> active channel
+     *        |                 |                 |
+     *        v                 v                 v
+     *     events ready     presence sync      send/listen
+     */
+    subscribe(options?: SubscribeOptions): Promise<this>;
+    /**
+     * Unsubscribes from the channel.
+     */
+    unsubscribe(options?: UnsubscribeOptions): Promise<void>;
+    /**
+     * Sends an event to the server.
+     */
+    send<T = unknown>(event: string, data?: T): this;
+    /**
+     * Sends an event and waits for a response.
+     */
+    sendWithAck<T = unknown, R = unknown>(event: string, data?: T): Promise<R>;
+}
+
+/**
+ * Main Socket client.
+ */
+declare class Socket implements SocketClientTransport {
+    #private;
+    constructor(options?: SocketOptions);
+    get state(): ConnectionState;
+    get connected(): boolean;
+    get id(): string | undefined;
+    connect(): Promise<void>;
+    disconnect(): void;
+    channel(name: string): Channel;
+    leave(name: string): Promise<void>;
+    onStateChange(handler: EventHandler<ConnectionState>): () => void;
+    on<T = unknown>(event: string, handler: EventHandler<T>): () => void;
+    off(event: string, handler: EventHandler): void;
+    send(message: Record<string, unknown>): void;
+    sendRequest<T = unknown>(message: Record<string, unknown>, timeout?: number): Promise<T>;
+}
+
+export { Channel, ConnectionState, EventHandler, PresenceUser, Socket, SocketOptions, SubscribeOptions, UnsubscribeOptions };