@eleven-am/pondsocket 0.1.11 → 0.1.13

package/dist/index.d.ts

@@ -0,0 +1,340 @@
+import { Server as HTTPServer, IncomingMessage, IncomingHttpHeaders } from 'http';
+import internal from 'stream';
+
+// eslint-disable-next-line import/no-unresolved
+import { Express } from 'express';
+import { WebSocketServer, WebSocket } from 'ws';
+
+export type PondPath = string | RegExp;
+type NextFunction = () => void;
+export type JoinParams = Record<string, any>;
+type PondAssigns = Record<string, any>;
+export type PondMessage = Record<string, any>;
+export type PondPresence = Record<string, any>;
+export type EndpointHandler = (req: IncomingConnection, res: ConnectionResponse) => void;
+type SocketCache = Pick<RequestCache, 'socket' | 'clientId' | 'assigns'>;
+type AuthorizeMiddleware = (request: JoinRequest, response: JoinResponse) => void | Promise<void>;
+type SocketMiddlewareFunction = (req: IncomingMessage, socket: internal.Duplex, head: Buffer, next: NextFunction) => void;
+
+interface RequestCache {
+    clientId: string;
+    socket: WebSocket;
+    channelName: string;
+    assigns: PondAssigns;
+    joinParams: Record<string, any>;
+    params: Record<string, string>;
+    query: Record<string, string>;
+}
+interface UserAssigns {
+    [userId: string]: PondAssigns;
+}
+interface UserData {
+    assigns: PondAssigns;
+    presence: PondPresence;
+    id: string;
+}
+interface EventObject {
+    event: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    payload: PondMessage;
+}
+interface IncomingConnection {
+    id: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    headers: IncomingHttpHeaders;
+    address: string;
+}
+interface UserPresences {
+    [userId: string]: PondPresence;
+}
+
+declare class AbstractRequest {
+    get event (): EventObject;
+
+    get channelNme (): string;
+
+    get assigns (): UserAssigns;
+
+    get presence (): UserPresences;
+}
+
+declare class EventRequest extends AbstractRequest {
+    get user (): UserData;
+}
+
+declare class EventResponse {
+    /**
+     * @desc Checks if the response has been sent
+     */
+    get responseSent (): boolean;
+
+    /**
+     * @desc Accepts the request and optionally assigns data to the client
+     * @param assigns - the data to assign to the client
+     */
+    accept (assigns?: PondAssigns): EventResponse;
+
+    /**
+     * @desc Rejects the request and optionally assigns data to the client
+     * @param message - the error message
+     * @param errorCode - the error code
+     * @param assigns - the data to assign to the client
+     */
+    reject (message?: string, errorCode?: number, assigns?: PondAssigns): EventResponse;
+
+    /**
+     * @desc Emits a direct message to the client
+     * @param event - the event name
+     * @param payload - the payload to send
+     * @param assigns - the data to assign to the client
+     */
+    send (event: string, payload: PondMessage, assigns?: PondAssigns): EventResponse;
+
+    /**
+     * @desc Sends a message to all clients in the channel
+     * @param event - the event to send
+     * @param payload - the payload to send
+     */
+    broadcast (event: string, payload: PondMessage): EventResponse;
+
+    /**
+     * @desc Sends a message to all clients in the channel except the client making the request
+     * @param event - the event to send
+     * @param payload - the payload to send
+     */
+    broadcastFromUser (event: string, payload: PondMessage): EventResponse;
+
+    /**
+     * @desc Sends a message to a set of clients in the channel
+     * @param event - the event to send
+     * @param payload - the payload to send
+     * @param userIds - the ids of the clients to send the message to
+     */
+    sendToUsers (event: string, payload: PondMessage, userIds: string[]): EventResponse;
+
+    /**
+     * @desc Tracks a user's presence in the channel
+     * @param presence - the initial presence data
+     * @param userId - the id of the user to track
+     */
+    trackPresence (presence: PondPresence, userId?: string): EventResponse;
+
+    /**
+     * @desc Updates a user's presence in the channel
+     * @param presence - the updated presence data
+     * @param userId - the id of the user to update
+     */
+    updatePresence (presence: PondPresence, userId?: string): EventResponse;
+
+    /**
+     * @desc Removes a user's presence from the channel
+     * @param userId - the id of the user to remove
+     */
+    unTrackPresence (userId?: string): EventResponse;
+
+    /**
+     * @desc Evicts a user from the channel
+     * @param reason - the reason for the eviction
+     * @param userId - the id of the user to evict,
+     */
+    evictUser (reason: string, userId?: string): void;
+
+    /**
+     * @desc Closes the channel from the server side for all clients
+     * @param reason - the reason for closing the channel
+     */
+    closeChannel (reason: string): void;
+}
+
+declare class JoinRequest extends AbstractRequest {
+    get joinParams (): JoinParams;
+
+    get user (): UserData;
+
+    get event (): EventObject;
+}
+
+declare class JoinResponse {
+    get responseSent (): boolean;
+
+    /**
+     * @desc Accepts the request and optionally assigns data to the client
+     * @param assigns - the data to assign to the client
+     */
+    accept (assigns?: PondAssigns): JoinResponse;
+
+    /**
+     * @desc Rejects the request and optionally assigns data to the client
+     * @param message - the error message
+     * @param errorCode - the error code
+     */
+    reject (message?: string, errorCode?: number): JoinResponse;
+
+    /**
+     * @desc Emits a direct message to the client
+     * @param event - the event name
+     * @param payload - the payload to send
+     * @param assigns - the data to assign to the client
+     */
+    send (event: string, payload: PondMessage, assigns?: PondAssigns): this;
+
+    /**
+     * @desc Emits a message to all clients in the channel
+     * @param event - the event name
+     * @param payload - the payload to send
+     */
+    broadcast (event: string, payload: PondMessage): JoinResponse;
+
+    /**
+     * @desc Emits a message to all clients in the channel except the sender
+     * @param event - the event name
+     * @param payload - the payload to send
+     */
+    broadcastFromUser (event: string, payload: PondMessage): JoinResponse;
+
+    /**
+     * @desc Emits a message to a specific set of clients
+     * @param event - the event name
+     * @param payload  - the payload to send
+     * @param userIds - the ids of the clients to send the message to
+     */
+    sendToUsers (event: string, payload: PondMessage, userIds: string[]): JoinResponse;
+
+    /**
+     * @desc tracks the presence of a client
+     * @param presence - the presence data to track
+     */
+    trackPresence (presence: PondPresence): JoinResponse;
+}
+
+declare class PondChannel {
+    /**
+     * @desc Authorize a user to join a channel
+     * @param handler - The handler to authorize the user
+     * @example
+     * const pond = new PondChannelEngine();
+     * pond.onJoinRequest((request, response) => {
+     *     if (request.event.assigns.admin)
+     *          response.accept();
+     *     else
+     *         response.reject('You are not an admin', 403);
+     * });
+     */
+    onJoinRequest (handler: AuthorizeMiddleware): void;
+
+    /**
+     * @desc Handles an event request made by a user
+     * @param event - The event to listen for
+     * @param handler - The handler to execute when the event is received
+     * @example
+     * pond.onEvent('echo', (request, response) => {
+     *     response.send('echo', {
+     *         message: request.payload,
+     *     });
+     * });
+     */
+    onEvent (event: PondPath, handler: (request: EventRequest, response: EventResponse) => void | Promise<void>): void;
+}
+
+declare class ConnectionResponse {
+    /**
+     * @desc Accepts the request and optionally assigns data to the client
+     * @param assigns - the data to assign to the client
+     */
+    accept (assigns?: PondAssigns): void;
+
+    /**
+     * @desc Rejects the request with the given error message
+     * @param message - the error message
+     * @param errorCode - the error code
+     */
+    reject (message?: string, errorCode?: number): void;
+
+    /**
+     * @desc Emits a direct message to the client
+     * @param event - the event name
+     * @param payload - the payload to send
+     * @param assigns - the data to assign to the client
+     */
+    send (event: string, payload: PondMessage, assigns?: PondAssigns): void;
+}
+
+export declare class Endpoint {
+    /**
+     * @desc Adds a new PondChannel to this path on this endpoint
+     * @param path - The path to add the channel to
+     * @param channel - The channel to add
+     *
+     * @example
+     * endpoint.useChannel('/chat', pondChannelInstance);
+     */
+    useChannel (path: PondPath, channel: PondChannel): void;
+
+    /**
+     * @desc List all clients connected to this endpoint
+     */
+    listConnections (): string[];
+
+    /**
+     * @desc Gets all clients connected to this endpoint
+     */
+    getClients (): SocketCache[];
+
+    /**
+     * @desc Broadcasts a message to all clients connected to this endpoint
+     * @param event - The event to broadcast
+     * @param payload - The payload to broadcast
+     */
+    broadcast (event: string, payload: PondMessage): void;
+
+    /**
+     * @desc Closes specific clients connected to this endpoint
+     * @param clientIds - The id for the client / clients to close
+     */
+    closeConnection (clientIds: string | string[]): void;
+}
+
+declare class PondSocket {
+    constructor (server?: HTTPServer, socketServer?: WebSocketServer);
+
+    /**
+     * @desc Specifies the port to listen on
+     * @param port - the port to listen on
+     * @param callback - the callback to call when the server is listening
+     */
+    listen (port: number, callback: (port?: number) => void): HTTPServer<typeof IncomingMessage, typeof import('http').ServerResponse>;
+
+    /**
+     * @desc Closes the server
+     * @param callback - the callback to call when the server is closed
+     */
+    close (callback?: () => void): HTTPServer<typeof IncomingMessage, typeof import('http').ServerResponse>;
+
+    /**
+     * @desc Accepts a new socket upgrade request on the provided endpoint using the handler function to authenticate the socket
+     * @param path - the pattern to accept || can also be a regex
+     * @param handler - the handler function to authenticate the socket
+     * @example
+     * const endpoint = pond.createEndpoint('/api/socket', (req, res) => {
+     *    const token = req.query.token;
+     *    if (!token)
+     *       return res.reject('No token provided');
+     *    res.accept({
+     *       assign: {
+     *           token
+     *       }
+     *    });
+     * })
+     */
+    createEndpoint (path: PondPath, handler: EndpointHandler): Endpoint;
+
+    /**
+     * @desc Adds a middleware function to the socket server
+     * @param middleware - the middleware function to add
+     */
+    use (middleware: SocketMiddlewareFunction): void;
+}
+
+export default PondSocket;

package/dist/index.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const pondSocket_1 = require("./server/server/pondSocket");
+exports.default = pondSocket_1.PondSocket;

package/dist/server/abstracts/abstractRequest.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractRequest = void 0;
+const matchPattern_1 = require("../utils/matchPattern");
+class AbstractRequest {
+    constructor(event, engine, payload) {
+        this._engine = engine;
+        this._event = event;
+        this._eventObject = null;
+        this._payload = payload;
+    }
+    get event() {
+        var _a, _b;
+        return {
+            event: this._event,
+            params: ((_a = this._eventObject) === null || _a === void 0 ? void 0 : _a.params) || {},
+            query: ((_b = this._eventObject) === null || _b === void 0 ? void 0 : _b.query) || {},
+            payload: this._payload,
+        };
+    }
+    get channelNme() {
+        return this._engine.name;
+    }
+    get assigns() {
+        return this._engine.getAssigns();
+    }
+    get presence() {
+        return this._engine.getPresence();
+    }
+    /**
+     * @desc Parses the event and returns true if the event matches the path
+     * @param path - the path to match
+     */
+    _parseQueries(path) {
+        const match = new matchPattern_1.MatchPattern();
+        this._eventObject = match.parseEvent(path, this._event);
+        return this._eventObject !== null;
+    }
+}
+exports.AbstractRequest = AbstractRequest;

package/dist/server/abstracts/abstractRequest.test.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const abstractRequest_1 = require("./abstractRequest");
+const createMockChannelEngine = () => ({
+    name: 'test',
+    getAssigns: () => ({}),
+    getPresence: () => ({}),
+});
+describe('AbstractRequest', () => {
+    it('should be able to be instantiated', () => {
+        const request = new abstractRequest_1.AbstractRequest('/test', createMockChannelEngine(), {});
+        expect(request).toBeTruthy();
+        expect(request.channelNme).toBe('test');
+        expect(request.assigns).toEqual({});
+        expect(request.presence).toEqual({});
+    });
+    it('should be able to parse queries', () => {
+        const request = new abstractRequest_1.AbstractRequest('/1234?choke=balls', createMockChannelEngine(), {});
+        expect(request.event).toEqual({
+            event: '/1234?choke=balls',
+            payload: {},
+            params: {},
+            query: {},
+        });
+        expect(request._parseQueries('/:id')).toBe(true);
+        expect(request.event).toEqual({
+            event: '/1234?choke=balls',
+            params: { id: '1234' },
+            query: { choke: 'balls' },
+            payload: {},
+        });
+    });
+    it('should be return the value of the payload', () => {
+        const request = new abstractRequest_1.AbstractRequest('/test', createMockChannelEngine(), { test: 'test' });
+        expect(request.event.payload).toEqual({ test: 'test' });
+        const request2 = new abstractRequest_1.AbstractRequest('/test', createMockChannelEngine(), { test: 'test',
+            test2: 'test2' });
+        expect(request2.event.payload).toEqual({ test: 'test',
+            test2: 'test2' });
+    });
+});

package/dist/server/abstracts/abstractResponse.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PondResponse = void 0;
+class PondResponse {
+}
+exports.PondResponse = PondResponse;

package/dist/server/abstracts/middleware.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Middleware = void 0;
+class Middleware {
+    constructor(second) {
+        this._stack = [];
+        if (second) {
+            this._stack.push(...second._stack);
+        }
+    }
+    /**
+     * @desc Adds a middleware function to the middleware stack
+     * @param middleware - the middleware function to add
+     */
+    use(middleware) {
+        this._stack.push(middleware);
+    }
+    /**
+     * @desc Runs the middleware stack
+     * @param req - the request object
+     * @param res - the response object
+     * @param final - the final function to call
+     */
+    run(req, res, final) {
+        const temp = this._stack.concat();
+        const nextFunction = () => {
+            const middleware = temp.shift();
+            if (middleware && !res.responseSent) {
+                void middleware(req, res, nextFunction);
+            }
+            else if (!res.responseSent) {
+                final();
+            }
+        };
+        nextFunction();
+    }
+}
+exports.Middleware = Middleware;

package/dist/server/abstracts/middleware.test.js

@@ -0,0 +1,70 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const middleware_1 = require("./middleware");
+describe('Middleware', () => {
+    it('should be able to add middleware to the stack', () => {
+        const middleware = new middleware_1.Middleware();
+        middleware.use(() => { });
+        expect(middleware['_stack'].length).toBe(1);
+    });
+    it('should be able to run middleware', () => __awaiter(void 0, void 0, void 0, function* () {
+        const middleware = new middleware_1.Middleware();
+        const mock = jest.fn();
+        middleware.use(mock);
+        yield middleware.run({}, {}, () => { });
+        expect(mock).toHaveBeenCalled();
+    }));
+    it('should be able to run multiple middleware', () => __awaiter(void 0, void 0, void 0, function* () {
+        const middleware = new middleware_1.Middleware();
+        const mock = jest.fn();
+        middleware.use((_, __, next) => {
+            mock('first');
+            next();
+        });
+        middleware.use((_, __, next) => {
+            mock('second');
+            next();
+        });
+        yield middleware.run({}, {}, () => { });
+        expect(mock).toHaveBeenCalledTimes(2);
+        expect(mock.mock.calls[0][2]).toBe(mock.mock.calls[1][2]);
+    }));
+    it('should be merge middleware in the correct order', () => __awaiter(void 0, void 0, void 0, function* () {
+        const middleware = new middleware_1.Middleware();
+        const mock = jest.fn();
+        middleware.use(mock);
+        middleware.use(mock);
+        const middleware2 = new middleware_1.Middleware(middleware);
+        expect(middleware2['_stack'].length).toBe(2);
+    }));
+    it('should call the final function when the middleware stack is empty', () => __awaiter(void 0, void 0, void 0, function* () {
+        const middleware = new middleware_1.Middleware();
+        const mock = jest.fn();
+        yield middleware.run({}, {}, mock);
+        expect(mock).toHaveBeenCalled();
+    }));
+    it('should be able to run middleware in the correct order when using a second middleware', () => __awaiter(void 0, void 0, void 0, function* () {
+        const middleware = new middleware_1.Middleware();
+        const mock = jest.fn();
+        middleware.use((_, __, next) => {
+            mock('first');
+            next();
+        });
+        middleware.use((_, __, next) => {
+            mock('second');
+            next();
+        });
+        const middleware2 = new middleware_1.Middleware(middleware);
+        yield middleware2.run({}, {}, () => { });
+        expect(mock.mock.calls[0][2]).toBe(mock.mock.calls[1][2]);
+    }));
+});