geonix 1.23.8 → 1.30.2

package/index.d.ts

@@ -1,266 +1,321 @@
-export function encode(data: any): Uint8Array<ArrayBuffer>;
-export function decode(data: any): unknown;
-export const codec: import("nats").Codec<unknown>;
-export const connection: Connection;
-export function stopConnection(): void;
+/// <reference types="node" />
+import type { Readable } from "stream";
+import type { IncomingMessage } from "http";
+import type { EventEmitter } from "events";
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+export interface ServiceOptions {
+    /** Override the class name used to identify the service on the bus. */
+    name?: string;
+    /** Override the service version. Falls back to GX_VERSION env var, then a dev default. */
+    version?: string;
+    /** Optional static ID for targeting a specific instance via Remote("#<id>"). */
+    id?: string;
+    /** Toggle built-in Express body parsers. All default to true. */
+    middleware?: {
+        json?: boolean;
+        raw?: boolean;
+        cookies?: boolean;
+    };
+    /**
+     * When false, only the instance ID is sent in beacon messages (saves bandwidth).
+     * Default: true.
+     */
+    fullBeacon?: boolean;
+    /** Express route handlers injected before / after each service endpoint handler. */
+    handlers?: {
+        before?: ((...args: any[]) => any)[];
+        after?: ((...args: any[]) => any)[];
+    };
+}
+
 /**
- * Connection class is responsible for starting a connection to a NATS server and provides shortcut
- * methods for publish, subscribe and request methods of the NATS client.
+ * Base class for all Geonix services. Extend this and call `Service.start()` to register on
+ * the NATS bus, expose HTTP endpoints, and begin sending presence beacons.
  *
- * It is implemented as an singleton so that multiple services can be implemented in the same
- * process while using just a single connection to the NATS server.
+ * @example
+ * class GreetingService extends Service {
+ *     async greet(name: string) {
+ *         return `Hello, ${name}!`;
+ *     }
+ * }
+ * GreetingService.start();
  */
-declare class Connection {
+export declare class Service {
     /**
-     * Initiates connection to transport
-     * @param {string} transport
+     * Override to hard-code the service version. Ignored when GX_VERSION / VERSION env vars
+     * are set, or when `options.version` is passed to `start()`.
      */
-    start(transport?: string): Promise<void>;
-    monitorStatus(): Promise<void>;
-    /**
-     * Wait for the connection to be safely closed
-     */
-    waitUntilClosed(): Promise<void>;
+    version?: string;
+    /** Called once after the service has connected and registered on the bus. */
+    onStart?(): void | Promise<void>;
+    /** Creates an instance of the subclass and starts it on the NATS bus. */
+    static start(options?: ServiceOptions): void;
+}
+
+// ---------------------------------------------------------------------------
+// Remote
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a proxy that forwards property-access calls to a named remote service.
+ * Without a type parameter the proxy is fully dynamic (`any`). Pass a service
+ * interface as the type parameter for IDE autocompletion and type checking.
+ *
+ * @param service - Service name, optionally with version (`@^1.2`) or static ID (`#<id>`).
+ * @param context - Optional context values forwarded to every remote method call.
+ *
+ * @example
+ * // Fully dynamic — no types required, `as` casts work freely
+ * const svc = Remote("GreetingService");
+ * const result = await svc.greet("Alice");
+ *
+ * @example
+ * // Typed — opt-in
+ * interface GreetingService { greet(name: string): Promise<string> }
+ * const svc = Remote<GreetingService>("GreetingService");
+ */
+export declare function Remote<T = any>(
+    service: string,
+    ...context: any[]
+): T;
+
+// ---------------------------------------------------------------------------
+// Stream
+// ---------------------------------------------------------------------------
+
+/** A Geonix stream descriptor — the wire representation of a streaming value. */
+export interface StreamDescriptor {
+    $: "stream";
+    id: string;
+    /** HTTP addresses (host:port) where the stream can be fetched. */
+    a?: string[];
+}
+
+/** Map of in-process stream IDs to their active Readable instances. */
+export declare const activeStreams: Record<string, Readable>;
+
+/**
+ * Wraps data in a Geonix stream descriptor for transport over NATS or HTTP.
+ * Buffers, strings, and Readables are accepted. Already-wrapped descriptors
+ * are returned unchanged.
+ */
+export declare function Stream(data: Buffer | string | Readable | object): StreamDescriptor;
+
+/** Returns `true` if `object` is a Geonix stream descriptor. */
+export declare function isStream(object: unknown): object is StreamDescriptor;
+
+/**
+ * Resolves a stream descriptor to a Node.js Readable.
+ * Prefers HTTP; falls back to NATS. Non-descriptor values are returned as-is.
+ */
+export declare function getReadable(object: StreamDescriptor | any): Promise<Readable>;
+
+/** Reads a stream or descriptor fully into memory and returns a Buffer. */
+export declare function streamToBuffer(object: Readable | StreamDescriptor): Promise<Buffer>;
+
+/** Reads a stream or descriptor fully into memory and returns a string. */
+export declare function streamToString(object: Readable | StreamDescriptor, encoding?: BufferEncoding): Promise<string>;
+
+/** Reads a stream or descriptor fully into memory and parses the result as JSON. */
+export declare function streamToJSON(object: Readable | StreamDescriptor): Promise<any>;
+
+// ---------------------------------------------------------------------------
+// Gateway
+// ---------------------------------------------------------------------------
+
+export interface GatewayOptions {
     /**
-     * Wait for the connection to be fully established
+     * CORS mode:
+     * - omitted / `false` — no CORS headers set
+     * - `"*"` — wildcard, all origins, no credentials
+     * - `true` — reflect any origin with credentials
+     * - `string[]` — allow-list; credentials only for listed origins
      */
+    cors?: boolean | "*" | string[];
+    beforeRequest?: (req: any, res: any) => void;
+    afterRequest?: (req: any, res: any) => void;
+}
+
+/**
+ * HTTP / WebSocket gateway that auto-discovers services via the registry and reverse-proxies
+ * incoming requests to the appropriate instance.
+ */
+export declare class Gateway {
+    static start(opts?: GatewayOptions): Gateway;
+    stop(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Connection
+// ---------------------------------------------------------------------------
+
+interface Connection {
+    start(transport?: string): Promise<void>;
+    monitorStatus(): void;
     waitUntilReady(): Promise<void>;
-    /**
-     * Publish JSON
-     *
-     * @param {string} subject
-     * @param {object} json
-     * @returns void
-     */
+    waitUntilClosed(): Promise<void>;
     publish(subject: string, json: object): Promise<void>;
-    /**
-     * Publish RAW
-     *
-     * @param {string} subject
-     * @param {string | Buffer} data
-     * @returns void
-     */
-    publishRaw(subject: string, data: string | Buffer): Promise<void>;
-    /**
-     * Request/Reply pattern on top of pub/sub
-     *
-     * @param {string} subject
-     * @param {object} json
-     * @param {object} options
-     * @returns any
-     */
-    request(subject: string, json: object, opts?: {}): Promise<unknown>;
-    subscribe(subject: any, options: any): Promise<any>;
-    unsubscribe(subscription: any): Promise<void>;
-    /**
-     *
-     * @returns {number}
-     */
+    publishRaw(subject: string, data?: string | Buffer): Promise<void>;
+    subscribe(subject: string, options?: object): Promise<AsyncIterable<any>>;
+    unsubscribe(subscription: AsyncIterable<any>): void;
+    request(subject: string, json: object, opts?: object): Promise<any>;
     getMaxPayloadSize(): number;
     isClosed(): boolean;
     drain(): Promise<void>;
-    #private;
 }
-export {};
-export class Gateway {
-    static start(opts: any): Gateway;
-    constructor(opts: any);
-    #private;
+
+/** Singleton NATS connection pool shared across the process. */
+export declare const connection: Connection;
+
+/** Initiates a graceful shutdown by draining all NATS connections. */
+export declare function stopConnection(): void;
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+/** A live service entry as seen by the local registry. */
+export interface RegistryEntry {
+    /** Unique instance ID (re-generated on each start) */
+    i: string;
+    /** Service name */
+    n: string;
+    /** Service version */
+    v: string;
+    /** Exposed method names */
+    m: string[];
+    /** Network addresses in `host:port` form */
+    a: string[];
+    /** Geonix version the service is running */
+    gx: string;
+    /** Optional static service ID */
+    id?: string;
 }
-export class Logger {
-    constructor(options: any);
-    info(...args: any[]): void;
-    error(...args: any[]): void;
-    debug(...args: any[]): void;
-    #private;
-}
-export const logger: Logger;
-export const registry: Registry;
-/**
- * Registry maintains a local list of available services and their versions.
- */
-declare class Registry {
-    getEntries(): {};
-    getIdentifier(service: any, version: any, id: any): any;
-    #private;
+
+interface Registry extends EventEmitter {
+    stop(): void;
+    getEntries(): Record<string, RegistryEntry>;
+    getEntriesForIdentifier(identifier: string): RegistryEntry[];
+    getIdentifier(service: string, version?: string, id?: string): string | undefined;
+    on(event: "added" | "removed", listener: (entry: RegistryEntry) => void): this;
+    once(event: "added" | "removed", listener: (entry: RegistryEntry) => void): this;
+    off(event: "added" | "removed", listener: (entry: RegistryEntry) => void): this;
 }
-export {};
-export function Remote(service: string, ...context: (string | Stream | Object)[]): string | Stream | Object;
-/**
- * Send a request to a service
- *
- * @param {string} service
- * @param {string} method
- * @param {any[]} args
- * @param {any[]} context
- * @param {object} options
- * @returns
- */
-export function Request(service: string, method: string, args: any[], context: any[], options: object): Promise<any>;
-/**
- * Send a request to a service
- *
- * @param {string} identifier
- * @param {string} method
- * @param {any[]} args
- * @param {any[]} context
- * @param {object} options
- * @returns
- */
-export function directRequest(identifier: string, method: string, args: any[], context: any[], options: object, service: any): Promise<any>;
+
+/** Singleton Registry instance — local view of all live services on the bus. */
+export declare const registry: Registry;
+
+// ---------------------------------------------------------------------------
+// Request / Subscribe / Publish
+// ---------------------------------------------------------------------------
+
 /**
- * Publish payload to a subject
+ * Sends a request to a named service, waiting in the registry if the service is not yet up.
  *
- * @param {string} subject
- * @param {string|number} payload
+ * @param service - Service name, optionally with version (`@^1.2`) or instance ID (`#<id>`).
+ * @param method  - Method name to invoke on the remote service.
+ * @param args    - Arguments. The first element may be a `RequestOptions` sentinel.
+ * @param context - Optional context forwarded to the remote method.
  */
-export function Publish(subject: string, payload: string | number): Promise<void>;
+export declare function Request(
+    service: string,
+    method: string,
+    args: any[],
+    context?: any[]
+): Promise<any>;
+
+/** Subscribes to a NATS subject and calls `callback` with raw message data for each message. */
+export declare function Subscribe(subject: string, callback: (data: Buffer) => void): Promise<void>;
+
+/** Publishes a raw payload to a NATS subject. Fire-and-forget. */
+export declare function Publish(subject: string, payload: string | Buffer): Promise<void>;
+
+// ---------------------------------------------------------------------------
+// RequestOptions
+// ---------------------------------------------------------------------------
+
+export interface RequestOptionsInput {
+    /** Max time in ms to wait for the service to appear in the registry. Default: 300 000. */
+    timeout?: number;
+    /** Max time in ms to wait for the HTTP RPC response. Default: 5 000. */
+    httpTimeout?: number;
+}
+
 /**
- * Subscribe to subject
+ * Wraps per-call options in a sentinel that `Request` (and `Remote`) detects and extracts
+ * when passed as the first argument of a service method call.
  *
- * @param {string} subject
- * @param {function} callback
- * @returns
+ * @example
+ * const result = await myService.compute(RequestOptions({ timeout: 60_000 }), payload);
  */
-export function Subscribe(subject: string, callback: Function): Promise<void>;
-export class RequestOptionsClass {
-    constructor(options: any);
-    options: any;
+export declare function RequestOptions(options: RequestOptionsInput): object;
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+/** The installed Geonix package version string. Equals `"N/A"` if metadata is unavailable. */
+export declare const GeonixVersion: string;
+
+/** Generates a cryptographically random Base62-encoded ID string. */
+export declare function randomID(size?: number): string;
+
+// ---------------------------------------------------------------------------
+// parseMultipart
+// ---------------------------------------------------------------------------
+
+export interface ParseMultipartOptions {
+    /** Buffer parts in memory instead of writing to temp files. Default: false. */
+    useMemory?: boolean;
+    /** Maximum allowed size in bytes for a single part. */
+    maxFileSize?: number;
+    /** Maximum number of parts allowed. */
+    maxFiles?: number;
 }
-export function RequestOptions(options: any): RequestOptionsClass;
-export class Service {
-    static serviceClasses: any[];
-    /**
-     *
-     * @param {ServiceOptions} options
-     */
-    static start(options?: ServiceOptions): void;
-    connections: Map<any, any>;
-    $createConnection(streamId: any): Promise<boolean>;
-    $getEnv(): {
-        geonix: string;
-        node: {
-            version: any;
-            platform: any;
-            arch: any;
-        };
-        env: any;
-        mem: any;
-        rss: any;
-        cpu: any;
-    };
-    $getServiceInfo(): {};
-    #private;
+
+export interface MultipartPart {
+    /** Field name from Content-Disposition, or `null` if absent. */
+    name: string | null;
+    /** Filename from Content-Disposition, or `null` if absent. */
+    filename: string | null;
+    /** Parsed part headers (lowercase keys). */
+    headers: Record<string, string>;
+    /** Readable stream of the part body. */
+    body: Readable;
+    /** Part body size in bytes. */
+    size: number;
 }
+
 /**
- * Converts data to stream
+ * Parses a `multipart/form-data` request body into an array of part objects.
  *
- * @param {*} data
- * @param {*} automated
- * @returns
+ * @throws If the content-type is not `multipart/form-data` or a size/count limit is exceeded.
  */
-export function Stream(data: any, tag?: string): any;
-export function isStream(object: any): any;
-export function getReadable(object: any): Promise<any>;
-export function streamToBuffer(object: any): Promise<any>;
-export function streamToString(object: any, encoding: any): Promise<any>;
-export function streamToJSON(object: any): Promise<any>;
-export const stats: {};
-export const activeStreams: {};
-type parseMultipartOptions = {
-    maxFileSize: number;
-    maxFiles: number;
-    useMemory: boolean;
-};
-type ParsedMultiPart = {
-    /**
-     * Field name of the part (extracted from Content-Disposition)
-     */
-    "name-": string;
-    /**
-     * - Filename of the part (extracted from Content-Disposition)
-     */
-    filename: string;
-    /**
-     * - Headers of the part
-     */
-    headers: Object;
-    /**
-     * - Path to the file when useMemory is false
-     */
-    bodyFile: string;
-    /**
-     * - Readable stream of the part
-     */
-    body: Readable;
-};
-type ServiceOptions = {
-    middleware?: {
-        /**
-         * Enable JSON middleware
-         */
-        json?: boolean | undefined;
-        /**
-         * Enable RAW middleware
-         */
-        raw?: boolean | undefined;
-        /**
-         * Enable cookies middleware
-         */
-        cookies?: boolean | undefined;
-    } | undefined;
-    /**
-     * Enable full beacon
-     */
-    fullBeacon?: boolean | undefined;
-};
-/**
- * Parse nats:// URL
- * @param {string} url
- * @returns
- */
-export function parseURL(url: string): any;
-export function getFirstItemFromAsyncIterable(asyncIterable: any): Promise<any>;
-export function getNetworkAddresses(): any[];
-export function isIterable(obj: any): any;
+export declare function parseMultipart(
+    req: IncomingMessage,
+    options?: ParseMultipartOptions
+): Promise<MultipartPart[]>;
+
+// ---------------------------------------------------------------------------
+// ServeStatic
+// ---------------------------------------------------------------------------
+
+export interface ServeStaticOptions {
+    /** URL prefix to strip before resolving the file path. */
+    root?: string;
+    /** If `true`, respond with `index.html` for all 404s — useful for SPAs. */
+    indexOn404?: boolean;
+    [key: string]: any;
+}
+
 /**
+ * Creates an Express router that serves static files from `root`.
  *
- *
- * @param {Request} req
- * @param {parseMultipartOptions} options
- * @returns ParsedMultiPart[]
+ * @param root    - Filesystem path to the directory containing static assets.
+ * @param options - Options forwarded to `express.static`, plus `root` prefix strip and `indexOn404`.
  */
-export function parseMultipart(req: Request, _options: any): Promise<{
-    headers: {};
-    bodyFile: any;
-    body: any;
-}[]>;
-export function tempFilename(): any;
-export function randomSafeId(size?: number): string;
-export function deepMerge(target: any, ...source: any[]): any;
-export function sleep(delay: number): Promise<any>;
-export function nextTick(): Promise<any>;
-export function picoid(size?: number): any;
-export function hash(data: string | Buffer): any;
-export function createServerAtPort(port: number, pkg: Object, handler: Function): Promise<any>;
-export function createServerAtFreePort(pkg: Object, handler: Function, start?: number, poolSize?: number): Promise<any>;
-export function createTCPServer(handler: Function, start?: number, poolSize?: number): Promise<any>;
-export function createHTTPServer(handler: Function, start?: number, poolSize?: number): Promise<any>;
-export function getSecondsSinceMidnight(): number;
-export function getFunctionParams(fn: any): any;
-export function proxyHttp(target: any, req: any, res: any): Promise<any>;
-export function OverlayObject(object: any, overlay: any): any;
-export const GeonixVersion: string;
-export function StreamChunker(chunkSize?: number): any;
-export const HEALTH_CHECK_ENDPOINT: "/pA4vY7fT9oG5aI8cA4yV3qW5fP9qR1vI";
-export function ServeStatic(root: any, options?: {}): any;
-export const webserver: WebServer;
-declare class WebServer {
-    start(): Promise<void>;
-    getPort(): any;
-    router(): any;
-    waitUntilReady(): Promise<void>;
-    stop(): void;
-    #private;
-}
-export {};
+export declare function ServeStatic(root: string, options?: ServeStaticOptions): any;

package/package.json

@@ -1,17 +1,17 @@
 {
     "name": "geonix",
-    "version": "1.23.8",
+    "version": "1.30.2",
     "type": "module",
     "description": "",
     "bin": {
         "gateway": "./.bin/gateway.js"
     },
     "main": "exports.js",
+    "types": "index.d.ts",
     "scripts": {
-        "test": "node --test --test-reporter=spec 'tests/unit/*.test.js' && node --test-concurrency=1 --test-reporter=spec 'tests/integration/*.test.js'",
-        "test:unit": "node --test --test-reporter=spec 'tests/unit/*.test.js'",
-        "test:integration": "node --test-concurrency=1 --test-reporter=spec 'tests/integration/*.test.js'",
-        "build": "npx tsc && cat build/* > index.d.ts && rm -rf build",
+        "test": "npm run test:unit && npm run test:integration",
+        "test:unit": "GX_LOG_LEVEL=none node --test --test-reporter=spec tests/unit/*.test.js",
+        "test:integration": "GX_LOG_LEVEL=none node --test --test-concurrency=1 --test-reporter=spec tests/integration/*.test.js",
         "lint": "npx eslint src",
         "deploy": "npm run build && npm publish"
     },
@@ -19,18 +19,19 @@
     "license": "MIT",
     "dependencies": {
         "cookie-parser": "1.4.7",
-        "express": "^4.21.2",
+        "express": "^4.22.1",
         "express-async-errors": "3.1.1",
         "express-ws": "5.0.2",
-        "nats": "2.28.2",
-        "semver": "7.6.3",
+        "nats": "^2.29.3",
+        "semver": "^7.7.4",
         "ws": "8.18.0"
     },
     "publishConfig": {
         "registry": "https://registry.npmjs.org/"
     },
     "devDependencies": {
-        "eslint": "^9.36.0",
-        "typescript": "^5.5.4"
+        "@eslint/js": "^10.0.1",
+        "eslint": "^10.1.0",
+        "globals": "^17.4.0"
     }
 }

package/src/Codec.js

@@ -1,20 +1,33 @@
 import { JSONCodec } from "nats";
 
+/**
+ * Shared NATS JSON codec instance used to serialise and deserialise message payloads.
+ *
+ * @type {import('nats').Codec<any>}
+ */
 export const codec = JSONCodec();
 
+/**
+ * Serialises `data` to a NATS-compatible `Uint8Array` using the JSON codec.
+ *
+ * @param {any} data - Value to encode.
+ * @returns {Uint8Array}
+ */
 export function encode(data) {
     return codec.encode(data);
 }
 
+/**
+ * Deserialises a `Uint8Array` NATS payload back to a JavaScript value using the JSON codec.
+ *
+ * @param {Uint8Array|Buffer} data - Raw bytes to decode.
+ * @returns {any}
+ * @throws {Error} If the bytes cannot be decoded as JSON.
+ */
 export function decode(data) {
-    // check if data is json
-    if (Buffer.isBuffer(data) && data.readUInt8(0) === "{".charCodeAt(0)) {
-        return codec.decode(data);
-    }
-
     try {
         return codec.decode(data);
-    } catch {
-        throw new Error("Codec.decode: unknown data type");
+    } catch (e) {
+        throw new Error(`Codec.decode: ${e.message}`, { cause: e });
     }
 }