@gleamkit/socket.io 4.8.6

package/dist/socket-types.d.ts

@@ -0,0 +1,56 @@
+import type { IncomingHttpHeaders } from "http";
+import type { ParsedUrlQuery } from "querystring";
+export type DisconnectReason = "transport error" | "transport close" | "forced close" | "ping timeout" | "parse error" | "server shutting down" | "forced server close" | "client namespace disconnect" | "server namespace disconnect";
+export interface SocketReservedEventsMap {
+    disconnect: (reason: DisconnectReason, description?: any) => void;
+    disconnecting: (reason: DisconnectReason, description?: any) => void;
+    error: (err: Error) => void;
+}
+export interface EventEmitterReservedEventsMap {
+    newListener: (eventName: string | Symbol, listener: (...args: any[]) => void) => void;
+    removeListener: (eventName: string | Symbol, listener: (...args: any[]) => void) => void;
+}
+export declare const RESERVED_EVENTS: ReadonlySet<string | Symbol>;
+/**
+ * The handshake details
+ */
+export interface Handshake {
+    /**
+     * The headers sent as part of the handshake
+     */
+    headers: IncomingHttpHeaders;
+    /**
+     * The date of creation (as string)
+     */
+    time: string;
+    /**
+     * The ip of the client
+     */
+    address: string;
+    /**
+     * Whether the connection is cross-domain
+     */
+    xdomain: boolean;
+    /**
+     * Whether the connection is secure
+     */
+    secure: boolean;
+    /**
+     * The date of creation (as unix timestamp)
+     */
+    issued: number;
+    /**
+     * The request URL string
+     */
+    url: string;
+    /**
+     * The query object
+     */
+    query: ParsedUrlQuery;
+    /**
+     * The auth object
+     */
+    auth: {
+        [key: string]: any;
+    };
+}

package/dist/socket-types.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESERVED_EVENTS = void 0;
+exports.RESERVED_EVENTS = new Set([
+    "connect",
+    "connect_error",
+    "disconnect",
+    "disconnecting",
+    "newListener",
+    "removeListener",
+]);

package/dist/socket.d.ts

@@ -0,0 +1,613 @@
+import { Packet } from "socket.io-parser";
+import { AllButLast, DecorateAcknowledgements, DecorateAcknowledgementsWithMultipleResponses, DefaultEventsMap, EventNames, EventNamesWithAck, EventParams, EventsMap, FirstNonErrorArg, Last, StrictEventEmitter } from "./typed-events";
+import type { Client } from "./client";
+import type { Namespace } from "./namespace";
+import type { IncomingMessage } from "http";
+import type { Room, Session, SocketId } from "socket.io-adapter";
+import { BroadcastOperator } from "./broadcast-operator";
+import { DisconnectReason, Handshake, SocketReservedEventsMap } from "./socket-types";
+/**
+ * `[eventName, ...args]`
+ */
+export type Event = [string, ...any[]];
+/**
+ * This is the main object for interacting with a client.
+ *
+ * A Socket belongs to a given {@link Namespace} and uses an underlying {@link Client} to communicate.
+ *
+ * Within each {@link Namespace}, you can also define arbitrary channels (called "rooms") that the {@link Socket} can
+ * join and leave. That provides a convenient way to broadcast to a group of socket instances.
+ *
+ * @example
+ * io.on("connection", (socket) => {
+ *   console.log(`socket ${socket.id} connected`);
+ *
+ *   // send an event to the client
+ *   socket.emit("foo", "bar");
+ *
+ *   socket.on("foobar", () => {
+ *     // an event was received from the client
+ *   });
+ *
+ *   // join the room named "room1"
+ *   socket.join("room1");
+ *
+ *   // broadcast to everyone in the room named "room1"
+ *   io.to("room1").emit("hello");
+ *
+ *   // upon disconnection
+ *   socket.on("disconnect", (reason) => {
+ *     console.log(`socket ${socket.id} disconnected due to ${reason}`);
+ *   });
+ * });
+ */
+export declare class Socket<ListenEvents extends EventsMap = DefaultEventsMap, EmitEvents extends EventsMap = ListenEvents, ServerSideEvents extends EventsMap = DefaultEventsMap, SocketData = any> extends StrictEventEmitter<ListenEvents, EmitEvents, SocketReservedEventsMap> {
+    readonly nsp: Namespace<ListenEvents, EmitEvents, ServerSideEvents>;
+    readonly client: Client<ListenEvents, EmitEvents, ServerSideEvents>;
+    /**
+     * An unique identifier for the session.
+     */
+    readonly id: SocketId;
+    /**
+     * Whether the connection state was recovered after a temporary disconnection. In that case, any missed packets will
+     * be transmitted to the client, the data attribute and the rooms will be restored.
+     */
+    readonly recovered: boolean;
+    /**
+     * The handshake details.
+     */
+    readonly handshake: Handshake;
+    /**
+     * Additional information that can be attached to the Socket instance and which will be used in the
+     * {@link Server.fetchSockets()} method.
+     */
+    data: SocketData;
+    /**
+     * Whether the socket is currently connected or not.
+     *
+     * @example
+     * io.use((socket, next) => {
+     *   console.log(socket.connected); // false
+     *   next();
+     * });
+     *
+     * io.on("connection", (socket) => {
+     *   console.log(socket.connected); // true
+     * });
+     */
+    connected: boolean;
+    /**
+     * The session ID, which must not be shared (unlike {@link id}).
+     *
+     * @private
+     */
+    private readonly pid;
+    private readonly server;
+    private readonly adapter;
+    private acks;
+    private fns;
+    private flags;
+    private _anyListeners?;
+    private _anyOutgoingListeners?;
+    /**
+     * Interface to a `Client` for a given `Namespace`.
+     *
+     * @param {Namespace} nsp
+     * @param {Client} client
+     * @param {Object} auth
+     * @package
+     */
+    constructor(nsp: Namespace<ListenEvents, EmitEvents, ServerSideEvents>, client: Client<ListenEvents, EmitEvents, ServerSideEvents>, auth: Record<string, unknown>, previousSession?: Session);
+    /**
+     * Builds the `handshake` BC object
+     *
+     * @private
+     */
+    private buildHandshake;
+    /**
+     * Emits to this client.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   socket.emit("hello", "world");
+     *
+     *   // all serializable datastructures are supported (no need to call JSON.stringify)
+     *   socket.emit("hello", 1, "2", { 3: ["4"], 5: Buffer.from([6]) });
+     *
+     *   // with an acknowledgement from the client
+     *   socket.emit("hello", "world", (val) => {
+     *     // ...
+     *   });
+     * });
+     *
+     * @return Always returns `true`.
+     */
+    emit<Ev extends EventNames<EmitEvents>>(ev: Ev, ...args: EventParams<EmitEvents, Ev>): boolean;
+    /**
+     * Emits an event and waits for an acknowledgement
+     *
+     * @example
+     * io.on("connection", async (socket) => {
+     *   // without timeout
+     *   const response = await socket.emitWithAck("hello", "world");
+     *
+     *   // with a specific timeout
+     *   try {
+     *     const response = await socket.timeout(1000).emitWithAck("hello", "world");
+     *   } catch (err) {
+     *     // the client did not acknowledge the event in the given delay
+     *   }
+     * });
+     *
+     * @return a Promise that will be fulfilled when the client acknowledges the event
+     */
+    emitWithAck<Ev extends EventNamesWithAck<EmitEvents>>(ev: Ev, ...args: AllButLast<EventParams<EmitEvents, Ev>>): Promise<FirstNonErrorArg<Last<EventParams<EmitEvents, Ev>>>>;
+    /**
+     * @private
+     */
+    private registerAckCallback;
+    /**
+     * Targets a room when broadcasting.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   // the “foo” event will be broadcast to all connected clients in the “room-101” room, except this socket
+     *   socket.to("room-101").emit("foo", "bar");
+     *
+     *   // the code above is equivalent to:
+     *   io.to("room-101").except(socket.id).emit("foo", "bar");
+     *
+     *   // with an array of rooms (a client will be notified at most once)
+     *   socket.to(["room-101", "room-102"]).emit("foo", "bar");
+     *
+     *   // with multiple chained calls
+     *   socket.to("room-101").to("room-102").emit("foo", "bar");
+     * });
+     *
+     * @param room - a room, or an array of rooms
+     * @return a new {@link BroadcastOperator} instance for chaining
+     */
+    to(room: Room | Room[]): BroadcastOperator<DecorateAcknowledgementsWithMultipleResponses<EmitEvents>, SocketData>;
+    /**
+     * Targets a room when broadcasting. Similar to `to()`, but might feel clearer in some cases:
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   // disconnect all clients in the "room-101" room, except this socket
+     *   socket.in("room-101").disconnectSockets();
+     * });
+     *
+     * @param room - a room, or an array of rooms
+     * @return a new {@link BroadcastOperator} instance for chaining
+     */
+    in(room: Room | Room[]): BroadcastOperator<DecorateAcknowledgementsWithMultipleResponses<EmitEvents>, SocketData>;
+    /**
+     * Excludes a room when broadcasting.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   // the "foo" event will be broadcast to all connected clients, except the ones that are in the "room-101" room
+     *   // and this socket
+     *   socket.except("room-101").emit("foo", "bar");
+     *
+     *   // with an array of rooms
+     *   socket.except(["room-101", "room-102"]).emit("foo", "bar");
+     *
+     *   // with multiple chained calls
+     *   socket.except("room-101").except("room-102").emit("foo", "bar");
+     * });
+     *
+     * @param room - a room, or an array of rooms
+     * @return a new {@link BroadcastOperator} instance for chaining
+     */
+    except(room: Room | Room[]): BroadcastOperator<DecorateAcknowledgementsWithMultipleResponses<EmitEvents>, SocketData>;
+    /**
+     * Sends a `message` event.
+     *
+     * This method mimics the WebSocket.send() method.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   socket.send("hello");
+     *
+     *   // this is equivalent to
+     *   socket.emit("message", "hello");
+     * });
+     *
+     * @return self
+     */
+    send(...args: EventParams<EmitEvents, "message">): this;
+    /**
+     * Sends a `message` event. Alias of {@link send}.
+     *
+     * @return self
+     */
+    write(...args: EventParams<EmitEvents, "message">): this;
+    /**
+     * Writes a packet.
+     *
+     * @param {Object} packet - packet object
+     * @param {Object} opts - options
+     * @private
+     */
+    private packet;
+    /**
+     * Joins a room.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   // join a single room
+     *   socket.join("room1");
+     *
+     *   // join multiple rooms
+     *   socket.join(["room1", "room2"]);
+     * });
+     *
+     * @param {String|Array} rooms - room or array of rooms
+     * @return a Promise or nothing, depending on the adapter
+     */
+    join(rooms: Room | Array<Room>): Promise<void> | void;
+    /**
+     * Leaves a room.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   // leave a single room
+     *   socket.leave("room1");
+     *
+     *   // leave multiple rooms
+     *   socket.leave("room1").leave("room2");
+     * });
+     *
+     * @param {String} room
+     * @return a Promise or nothing, depending on the adapter
+     */
+    leave(room: string): Promise<void> | void;
+    /**
+     * Leave all rooms.
+     *
+     * @private
+     */
+    private leaveAll;
+    /**
+     * Called by `Namespace` upon successful
+     * middleware execution (ie: authorization).
+     * Socket is added to namespace array before
+     * call to join, so adapters can access it.
+     *
+     * @private
+     */
+    _onconnect(): void;
+    /**
+     * Called with each packet. Called by `Client`.
+     *
+     * @param {Object} packet
+     * @private
+     */
+    _onpacket(packet: Packet): void;
+    /**
+     * Called upon event packet.
+     *
+     * @param {Packet} packet - packet object
+     * @private
+     */
+    private onevent;
+    /**
+     * Produces an ack callback to emit with an event.
+     *
+     * @param {Number} id - packet id
+     * @private
+     */
+    private ack;
+    /**
+     * Called upon ack packet.
+     *
+     * @private
+     */
+    private onack;
+    /**
+     * Called upon client disconnect packet.
+     *
+     * @private
+     */
+    private ondisconnect;
+    /**
+     * Handles a client error.
+     *
+     * @private
+     */
+    _onerror(err: Error): void;
+    /**
+     * Called upon closing. Called by `Client`.
+     *
+     * @param {String} reason
+     * @param description
+     * @throw {Error} optional error object
+     *
+     * @private
+     */
+    _onclose(reason: DisconnectReason, description?: any): this | undefined;
+    /**
+     * Makes the socket leave all the rooms it was part of and prevents it from joining any other room
+     *
+     * @private
+     */
+    _cleanup(): void;
+    /**
+     * Produces an `error` packet.
+     *
+     * @param {Object} err - error object
+     *
+     * @private
+     */
+    _error(err: any): void;
+    /**
+     * Disconnects this client.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   // disconnect this socket (the connection might be kept alive for other namespaces)
+     *   socket.disconnect();
+     *
+     *   // disconnect this socket and close the underlying connection
+     *   socket.disconnect(true);
+     * })
+     *
+     * @param {Boolean} close - if `true`, closes the underlying connection
+     * @return self
+     */
+    disconnect(close?: boolean): this;
+    /**
+     * Sets the compress flag.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   socket.compress(false).emit("hello");
+     * });
+     *
+     * @param {Boolean} compress - if `true`, compresses the sending data
+     * @return {Socket} self
+     */
+    compress(compress: boolean): this;
+    /**
+     * Sets a modifier for a subsequent event emission that the event data may be lost if the client is not ready to
+     * receive messages (because of network slowness or other issues, or because they’re connected through long polling
+     * and is in the middle of a request-response cycle).
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   socket.volatile.emit("hello"); // the client may or may not receive it
+     * });
+     *
+     * @return {Socket} self
+     */
+    get volatile(): this;
+    /**
+     * Sets a modifier for a subsequent event emission that the event data will only be broadcast to every sockets but the
+     * sender.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   // the “foo” event will be broadcast to all connected clients, except this socket
+     *   socket.broadcast.emit("foo", "bar");
+     * });
+     *
+     * @return a new {@link BroadcastOperator} instance for chaining
+     */
+    get broadcast(): BroadcastOperator<DecorateAcknowledgementsWithMultipleResponses<EmitEvents>, SocketData>;
+    /**
+     * Sets a modifier for a subsequent event emission that the event data will only be broadcast to the current node.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   // the “foo” event will be broadcast to all connected clients on this node, except this socket
+     *   socket.local.emit("foo", "bar");
+     * });
+     *
+     * @return a new {@link BroadcastOperator} instance for chaining
+     */
+    get local(): BroadcastOperator<DecorateAcknowledgementsWithMultipleResponses<EmitEvents>, SocketData>;
+    /**
+     * Sets a modifier for a subsequent event emission that the callback will be called with an error when the
+     * given number of milliseconds have elapsed without an acknowledgement from the client:
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   socket.timeout(5000).emit("my-event", (err) => {
+     *     if (err) {
+     *       // the client did not acknowledge the event in the given delay
+     *     }
+     *   });
+     * });
+     *
+     * @returns self
+     */
+    timeout(timeout: number): Socket<ListenEvents, DecorateAcknowledgements<EmitEvents>, ServerSideEvents, SocketData>;
+    /**
+     * Dispatch incoming event to socket listeners.
+     *
+     * @param {Array} event - event that will get emitted
+     * @private
+     */
+    private dispatch;
+    /**
+     * Sets up socket middleware.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   socket.use(([event, ...args], next) => {
+     *     if (isUnauthorized(event)) {
+     *       return next(new Error("unauthorized event"));
+     *     }
+     *     // do not forget to call next
+     *     next();
+     *   });
+     *
+     *   socket.on("error", (err) => {
+     *     if (err && err.message === "unauthorized event") {
+     *       socket.disconnect();
+     *     }
+     *   });
+     * });
+     *
+     * @param {Function} fn - middleware function (event, next)
+     * @return {Socket} self
+     */
+    use(fn: (event: Event, next: (err?: Error) => void) => void): this;
+    /**
+     * Executes the middleware for an incoming event.
+     *
+     * @param {Array} event - event that will get emitted
+     * @param {Function} fn - last fn call in the middleware
+     * @private
+     */
+    private run;
+    /**
+     * Whether the socket is currently disconnected
+     */
+    get disconnected(): boolean;
+    /**
+     * A reference to the request that originated the underlying Engine.IO Socket.
+     */
+    get request(): IncomingMessage;
+    /**
+     * A reference to the underlying Client transport connection (Engine.IO Socket object).
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   console.log(socket.conn.transport.name); // prints "polling" or "websocket"
+     *
+     *   socket.conn.once("upgrade", () => {
+     *     console.log(socket.conn.transport.name); // prints "websocket"
+     *   });
+     * });
+     */
+    get conn(): import("engine.io").Socket;
+    /**
+     * Returns the rooms the socket is currently in.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   console.log(socket.rooms); // Set { <socket.id> }
+     *
+     *   socket.join("room1");
+     *
+     *   console.log(socket.rooms); // Set { <socket.id>, "room1" }
+     * });
+     */
+    get rooms(): Set<Room>;
+    /**
+     * Adds a listener that will be fired when any event is received. The event name is passed as the first argument to
+     * the callback.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   socket.onAny((event, ...args) => {
+     *     console.log(`got event ${event}`);
+     *   });
+     * });
+     *
+     * @param listener
+     */
+    onAny(listener: (...args: any[]) => void): this;
+    /**
+     * Adds a listener that will be fired when any event is received. The event name is passed as the first argument to
+     * the callback. The listener is added to the beginning of the listeners array.
+     *
+     * @param listener
+     */
+    prependAny(listener: (...args: any[]) => void): this;
+    /**
+     * Removes the listener that will be fired when any event is received.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   const catchAllListener = (event, ...args) => {
+     *     console.log(`got event ${event}`);
+     *   }
+     *
+     *   socket.onAny(catchAllListener);
+     *
+     *   // remove a specific listener
+     *   socket.offAny(catchAllListener);
+     *
+     *   // or remove all listeners
+     *   socket.offAny();
+     * });
+     *
+     * @param listener
+     */
+    offAny(listener?: (...args: any[]) => void): this;
+    /**
+     * Returns an array of listeners that are listening for any event that is specified. This array can be manipulated,
+     * e.g. to remove listeners.
+     */
+    listenersAny(): ((...args: any[]) => void)[];
+    /**
+     * Adds a listener that will be fired when any event is sent. The event name is passed as the first argument to
+     * the callback.
+     *
+     * Note: acknowledgements sent to the client are not included.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   socket.onAnyOutgoing((event, ...args) => {
+     *     console.log(`sent event ${event}`);
+     *   });
+     * });
+     *
+     * @param listener
+     */
+    onAnyOutgoing(listener: (...args: any[]) => void): this;
+    /**
+     * Adds a listener that will be fired when any event is emitted. The event name is passed as the first argument to the
+     * callback. The listener is added to the beginning of the listeners array.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   socket.prependAnyOutgoing((event, ...args) => {
+     *     console.log(`sent event ${event}`);
+     *   });
+     * });
+     *
+     * @param listener
+     */
+    prependAnyOutgoing(listener: (...args: any[]) => void): this;
+    /**
+     * Removes the listener that will be fired when any event is sent.
+     *
+     * @example
+     * io.on("connection", (socket) => {
+     *   const catchAllListener = (event, ...args) => {
+     *     console.log(`sent event ${event}`);
+     *   }
+     *
+     *   socket.onAnyOutgoing(catchAllListener);
+     *
+     *   // remove a specific listener
+     *   socket.offAnyOutgoing(catchAllListener);
+     *
+     *   // or remove all listeners
+     *   socket.offAnyOutgoing();
+     * });
+     *
+     * @param listener - the catch-all listener
+     */
+    offAnyOutgoing(listener?: (...args: any[]) => void): this;
+    /**
+     * Returns an array of listeners that are listening for any event that is specified. This array can be manipulated,
+     * e.g. to remove listeners.
+     */
+    listenersAnyOutgoing(): ((...args: any[]) => void)[];
+    /**
+     * Notify the listeners for each packet sent (emit or broadcast)
+     *
+     * @param packet
+     *
+     * @private
+     */
+    private notifyOutgoingListeners;
+    private newBroadcastOperator;
+}