@linebridge/engine-neo 1.1.0 → 1.3.0

package/lib/route_register.js

@@ -1,5 +1,3 @@
-import { Route, } from "linebridge/classes/Route/index";
-import { HandlerKind } from "linebridge/classes/Handler/index";
 /**
  * Registers a route with the engine's uWS app.
  *
@@ -11,57 +9,25 @@ export default function (route) {
     if (!this.uws) {
         throw new Error("Engine is not initialized");
     }
-    let routeInstance;
-    // support passing a class constructor or an already-constructed instance
-    if (typeof route === "function") {
-        try {
-            routeInstance = new route();
-        }
-        catch (err) {
-            console.error(`Failed to construct route class:\n`, err);
-            return;
-        }
-    }
-    else if (route instanceof Route) {
-        routeInstance = route;
-    }
-    else if (typeof route.fn === "function") {
-        routeInstance = new Route();
-        routeInstance.kind = HandlerKind.http;
-        routeInstance.path = route.path ?? "/";
-        routeInstance.method = route.method ?? "get";
-        routeInstance.useContexts = route.useContexts ?? [];
-        routeInstance.useMiddlewares = route.useMiddlewares ?? [];
-        routeInstance.fn = route.fn;
-    }
-    else {
-        throw new Error("Invalid route provided");
-    }
-    // try to initialize the route
-    try {
-        routeInstance._initialize(this.server);
-    }
-    catch (err) {
-        console.error(`Failed to initialize route:\n`, err);
-        return;
-    }
     // normalize DELETE method for uWS compatibility (uWS uses "del" internally)
-    if (routeInstance.method === "delete") {
-        routeInstance.method = "del";
+    if (route.method === "delete") {
+        route.method = "del";
     }
     // verify the method is a valid uWS route method before registering
-    if (typeof this.uws[routeInstance.method] !== "function") {
-        console.warn(`Invalid method (${routeInstance.method}) for route handler [${routeInstance.path}]\nSkipping route..`);
+    if (typeof this.uws[route.method] !== "function") {
+        console.warn(`Invalid method (${route.method}) for route handler [${route.path}]\nSkipping route..`);
         return;
     }
     this.registers.add({
-        kind: routeInstance.kind,
-        method: routeInstance.method,
-        path: routeInstance.path,
-        useContexts: routeInstance.useContexts,
-        useMiddlewares: routeInstance.useMiddlewares,
-        _source_file: routeInstance._source_file,
-        handler: routeInstance.handler,
+        kind: route.kind,
+        method: route.method,
+        path: route.path,
+        useContexts: route.useContexts,
+        useMiddlewares: route.useMiddlewares,
+        _source_file: route._source_file,
+        handler: route.handler,
     });
-    this.uws[routeInstance.method](routeInstance.path, (res, req) => this.on_request(req, res, routeInstance));
+    if (route.kind === "http") {
+        this.uws[route.method](route.path, (res, req) => this.on_request(req, res, route));
+    }
 }

package/lib/utils.d.ts

@@ -10,5 +10,5 @@ declare function wrap_object(original: any, target: any): void;
  * @param {BufferEncoding} encoding
  * @returns {String} String
  */
-declare function array_buffer_to_string(array_buffer: ArrayBuffer, encoding?: BufferEncoding): any;
+declare function array_buffer_to_string(array_buffer: ArrayBuffer, encoding?: BufferEncoding): string;
 export { array_buffer_to_string, wrap_object };

package/lib/ws/Websocket.d.ts

@@ -1,173 +1,125 @@
 import { EventEmitter } from "tseep/lib/ee-safe.js";
-import { Readable, Writable } from "stream";
-export default class Websocket extends EventEmitter {
+import { Readable, Writable } from "node:stream";
+import type { uWebsockets } from "../uws.js";
+/** Any payload accepted by uWebSockets or produced by streams. */
+export type WebsocketMessage = string | Buffer | ArrayBuffer | ArrayBufferView;
+/** Events emitted by the websocket polyfill. */
+export type WebsocketEventMap = {
+    [event in string | symbol]: (...args: any[]) => void;
+} & {
+    message: (message: WebsocketMessage, is_binary: boolean) => void;
+    close: (code: number, message: WebsocketMessage) => void;
+    drain: () => void;
+    ping: (message: WebsocketMessage) => void;
+    pong: (message: WebsocketMessage) => void;
+};
+/**
+ * Raw uws websocket with the context and polyfill attached by the engine.
+ * The native wrapper merges the upgrade user data into the socket object.
+ */
+export interface WebsocketRaw<TContext = Record<string, any>> extends uWebsockets.WebSocket<{
+    context?: TContext;
+}> {
+    context?: TContext;
+    poly?: Websocket<TContext>;
+}
+declare const FRAGMENTS: {
+    readonly FIRST: "FIRST";
+    readonly MIDDLE: "MIDDLE";
+    readonly LAST: "LAST";
+};
+type Fragment = (typeof FRAGMENTS)[keyof typeof FRAGMENTS];
+export default class Websocket<TContext = Record<string, any>> extends EventEmitter<WebsocketEventMap> {
     #private;
-    constructor(ws: any);
-    /**
-     * Binds an event listener to this `Websocket` instance.
-     * See the Node.js `EventEmitter` documentation for more details on this extended method.
-     * @param {('message'|'close'|'drain'|'ping'|'pong')} eventName
-     * @param {Function} listener
-     * @returns {Websocket}
-     */
-    on(eventName: ('message' | 'close' | 'drain' | 'ping' | 'pong'), listener: Function): Websocket;
-    /**
-     * Binds a `one-time` event listener to this `Websocket` instance.
-     * See the Node.js `EventEmitter` documentation for more details on this extended method.
-     * @param {('message'|'close'|'drain'|'ping'|'pong')} eventName
-     * @param {Function} listener
-     * @returns {Websocket}
-     */
-    once(eventName: ('message' | 'close' | 'drain' | 'ping' | 'pong'), listener: Function): Websocket;
+    constructor(ws: WebsocketRaw<TContext>);
     /**
-     * Alias of uWS.cork() method. Accepts a callback with multiple operations for network efficiency.
-     *
-     * @param {Function} callback
-     * @returns {Websocket}
+     * Alias of uws cork, used to batch multiple operations for efficiency.
      */
-    atomic(callback: Function): Websocket;
+    atomic(callback: () => void): Websocket<TContext> | uWebsockets.WebSocket<{
+        context?: TContext;
+    }>;
     /**
-     * Sends a message to websocket connection.
-     * Returns true if message was sent successfully.
-     * Returns false if message was not sent due to buil up backpressure.
-     *
-     * @param {String|Buffer|ArrayBuffer} message
-     * @param {Boolean=} is_binary
-     * @param {Boolean=} compress
-     * @returns {Boolean}
+     * Sends a message over the connection.
+     * Returns the uws send status, or false when the socket is closed.
      */
-    send(message: string | Buffer | ArrayBuffer, is_binary?: boolean | undefined, compress?: boolean | undefined): boolean;
+    send(message: WebsocketMessage, is_binary?: boolean, compress?: boolean): number | false;
     /**
      * Sends a ping control message.
-     * Returns Boolean depending on backpressure similar to send().
-     *
-     * @param {String|Buffer|ArrayBuffer=} message
-     * @returns {Boolean}
      */
-    ping(message?: (string | Buffer | ArrayBuffer) | undefined): boolean;
+    ping(message?: WebsocketMessage): number | false;
     /**
-     * Destroys this polyfill Websocket component and derefernces the underlying ws object
+     * Destroys this polyfill and dereferences the underlying socket.
      * @private
      */
-    private _destroy;
+    _destroy(): void;
     /**
-     * Gracefully closes websocket connection by sending specified code and short message.
-     *
-     * @param {Number=} code
-     * @param {(String|Buffer|ArrayBuffer)=} message
+     * Gracefully closes the connection, sending an optional code and message.
      */
-    close(code?: number | undefined, message?: (string | Buffer | ArrayBuffer) | undefined): void;
+    close(code?: number, message?: WebsocketMessage): void;
     /**
-     * Forcefully closes websocket connection.
-     * No websocket close code/message is sent.
-     * This will immediately emit the 'close' event.
+     * Forcefully closes the connection without a close message.
      */
     destroy(): void;
     /**
-     * Returns whether this `Websocket` is subscribed to the specified topic.
-     *
-     * @param {String} topic
-     * @returns {Boolean}
+     * Returns whether this connection is subscribed to the topic.
      */
     is_subscribed(topic: string): boolean;
     /**
-     * Subscribe to a topic in MQTT syntax.
-     * MQTT syntax includes things like "root/child/+/grandchild" where "+" is a wildcard and "root/#" where "#" is a terminating wildcard.
-     *
-     * @param {String} topic
-     * @returns {Boolean}
+     * Subscribes to a topic in mqtt syntax.
      */
     subscribe(topic: string): boolean;
     /**
-     * Unsubscribe from a topic.
-     * Returns true on success, if the WebSocket was subscribed.
-     *
-     * @param {String} topic
-     * @returns {Boolean}
+     * Unsubscribes from a topic.
      */
     unsubscribe(topic: string): boolean;
     /**
-     * Publish a message to a topic in MQTT syntax.
-     * You cannot publish using wildcards, only fully specified topics.
-     *
-     * @param {String} topic
-     * @param {String|Buffer|ArrayBuffer} message
-     * @param {Boolean=} is_binary
-     * @param {Boolean=} compress
+     * Publishes a message to a topic in mqtt syntax.
      */
-    publish(topic: string, message: string | Buffer | ArrayBuffer, is_binary?: boolean | undefined, compress?: boolean | undefined): any;
+    publish(topic: string, message: WebsocketMessage, is_binary?: boolean, compress?: boolean): boolean;
     /**
-     * Buffers the provided fragment and returns the last buffered fragment.
-     *
-     * @param {String|Buffer|ArrayBuffer} fragment
-     * @returns {String|Buffer|ArrayBuffer|undefined}
+     * Buffers the provided fragment and returns the previously buffered one.
      */
-    _buffer_fragment(fragment: string | Buffer | ArrayBuffer): string | Buffer | ArrayBuffer | undefined;
+    _buffer_fragment(fragment?: WebsocketMessage): WebsocketMessage | undefined;
     /**
-     * Initiates fragment based message writing with uWS and writes appropriate chunk based on provided type parameter.
-     *
-     * @param {String} type
-     * @param {String|Buffer|ArrayBuffer} chunk
-     * @param {Boolean=} is_binary
-     * @param {Boolean=} compress
-     * @param {Function=} callback
-     * @returns {Boolean}
+     * Writes a fragment using the appropriate uws fragment method.
      */
-    _write(type: string, chunk: string | Buffer | ArrayBuffer, is_binary?: boolean | undefined, compress?: boolean | undefined, callback?: Function | undefined): boolean;
+    _write(type: Fragment, chunk: WebsocketMessage, is_binary?: boolean, compress?: boolean, callback?: () => void): number;
     /**
-     * Streams the provided chunk while pausing the stream being consumed during backpressure.
-     *
-     * @param {Readable} stream
-     * @param {String} type
-     * @param {Buffer|ArrayBuffer} chunk
-     * @param {Boolean} is_binary
+     * Streams a chunk, pausing the source stream while under backpressure.
      */
-    _stream_chunk(stream: Readable, type: string, chunk: Buffer | ArrayBuffer, is_binary: boolean): void;
+    _stream_chunk(stream: Readable, type: Fragment, chunk: WebsocketMessage, is_binary: boolean): void;
     /**
-     * This method is used to stream a message to the receiver.
-     * Note! The data is by default streamed as Binary due to how partial fragments are sent.
-     * This is done to prevent processing errors depending on client's receiver's incoming fragment processing strategy.
-     *
-     * @param {Readable} readable A Readable stream which will be consumed as message
-     * @param {Boolean=} is_binary Whether data being streamed is in binary. Default: true
-     * @returns {Promise}
+     * Streams a readable as a single fragmented message.
      */
-    stream(readable: Readable, is_binary?: boolean | undefined): Promise<any>;
+    stream(readable: Readable, is_binary?: boolean): Promise<void>;
     /**
-     * Underlying uWS.Websocket object
+     * Underlying uws websocket object.
      */
-    get raw(): any;
+    get raw(): WebsocketRaw<TContext> | null;
     /**
-     * Returns IP address of this websocket connection.
-     * @returns {String}
+     * Remote ip address of this connection.
      */
     get ip(): string;
     /**
-     * Returns context values from the response.update(context) connection upgrade call.
-     * @returns {Object}
+     * Context values attached during the upgrade.
      */
-    get context(): Object;
+    get context(): TContext;
     /**
-     * Returns whether is websocket connection is closed.
-     * @returns {Boolean}
+     * Whether this connection is closed.
      */
     get closed(): boolean;
     /**
-     * Returns the bytes buffered in backpressure.
-     * This is similar to the bufferedAmount property in the browser counterpart.
-     * @returns {Number}
+     * Bytes currently buffered in backpressure.
      */
     get buffered(): number;
     /**
-     * Returns a list of topics this websocket is subscribed to.
-     * @returns {Array<String>}
+     * Topics this connection is subscribed to.
      */
-    get topics(): Array<string>;
+    get topics(): string[];
     /**
-     * Returns a Writable stream associated with this response to be used for piping streams.
-     * Note! You can only retrieve/use only one writable at any given time.
-     *
-     * @returns {Writable}
+     * Writable stream bound to this connection for piping.
+     * Only one writable can be used at a time.
      */
     get writable(): Writable;
 }
+export {};