@wishcore/wish-rpc 0.6.13 → 0.6.15

package/dist/src/index.d.ts

@@ -1,6 +1,37 @@
 export interface MethodMap {
     [endpoint: string]: any;
 }
+export interface EndpointConfig {
+    doc?: string;
+    args?: string;
+    validate?: (args: any[], context: any) => any;
+    validateResult?: (result: any) => any;
+    fullname?: string;
+    [key: string]: any;
+}
+export interface BaseEndpointConfig {
+    doc?: string;
+    args?: string;
+    fullname?: string;
+    [key: string]: any;
+}
+export interface EndpointHandler {
+    (req: RpcRequest, res: RpcResponse, context?: any): any;
+}
+export interface RpcRequest {
+    args: any[];
+    id?: number;
+    op?: string;
+    context?: any;
+    end?: any;
+    send?: any;
+}
+export interface RpcResponse {
+    send(data?: any): void;
+    emit(data?: any): void;
+    error(data?: any): void;
+    close(data?: any): void;
+}
 export interface RequestMessage {
     op: string;
     args?: any[];
@@ -18,11 +49,22 @@ export interface ResponseMessage {
     end?: number;
     push?: number;
     data?: any;
+    fin?: number;
+}
+export interface RequestContext {
+    id?: number;
+    op?: string;
+    args?: any[];
+    context?: any;
+    end?: any;
+    send?: any;
+    data?: any;
 }
 export interface RequestMap {
     [clientId: string]: {
-        [requestId: string]: any;
+        [requestId: string]: RequestContext;
     };
 }
 export * from './rpc-client';
 export * from './rpc-server';
+export * from './method-registry';

package/dist/src/index.js

@@ -12,4 +12,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./rpc-client"), exports);
 __exportStar(require("./rpc-server"), exports);
+__exportStar(require("./method-registry"), exports);
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AA+BA,+CAA6B;AAC7B,+CAA6B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AA+EA,+CAA6B;AAC7B,+CAA6B;AAC7B,oDAAkC"}

package/dist/src/method-registry.d.ts

@@ -0,0 +1,60 @@
+import { EndpointConfig, EndpointHandler, MethodMap, BaseEndpointConfig } from './index';
+/**
+ * Manages RPC method registration and retrieval
+ */
+export declare class MethodRegistry<T extends BaseEndpointConfig = EndpointConfig> {
+    private modules;
+    private methods;
+    /**
+     * Register a new endpoint with modern syntax
+     */
+    registerEndpoint(name: string, config: T, handler: EndpointHandler): void;
+    /**
+     * Register methods using legacy underscore-prefixed structure
+     */
+    registerLegacyMethods(methodMap: MethodMap): void;
+    /**
+     * Get all registered modules
+     */
+    getModules(): Record<string, T>;
+    /**
+     * Get all registered methods
+     */
+    getMethods(): Record<string, EndpointHandler>;
+    /**
+     * Get a specific method by name
+     */
+    getMethod(name: string): EndpointHandler | undefined;
+    /**
+     * Get a specific module config by name
+     */
+    getModule(name: string): T | undefined;
+    /**
+     * Check if a method exists
+     */
+    hasMethod(name: string): boolean;
+    /**
+     * Get method listing excluding internal fields
+     */
+    getMethodListing(): Record<string, Partial<T>>;
+    /**
+     * Recursively processes method map with underscore-prefixed descriptors
+     */
+    private processMethodMap;
+    /**
+     * Registers a single method using legacy format
+     */
+    private registerLegacyMethod;
+    /**
+     * Creates a copy of config object excluding specified fields
+     */
+    private copyConfig;
+    /**
+     * Checks if a key represents module metadata
+     */
+    private isModuleMeta;
+    /**
+     * Checks if a key is a descriptor (starts with underscore)
+     */
+    private isDescriptor;
+}

package/dist/src/method-registry.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MethodRegistry = void 0;
+/**
+ * Manages RPC method registration and retrieval
+ */
+class MethodRegistry {
+    constructor() {
+        this.modules = {};
+        this.methods = {};
+    }
+    /**
+     * Register a new endpoint with modern syntax
+     */
+    registerEndpoint(name, config, handler) {
+        if (!name || typeof name !== 'string') {
+            throw new Error('Endpoint name must be a non-empty string');
+        }
+        if (typeof handler !== 'function') {
+            throw new Error('Endpoint handler must be a function');
+        }
+        this.modules[name] = Object.assign(Object.assign({}, config), { fullname: name });
+        this.methods[name] = handler;
+    }
+    /**
+     * Register methods using legacy underscore-prefixed structure
+     */
+    registerLegacyMethods(methodMap) {
+        this.processMethodMap('', methodMap);
+    }
+    /**
+     * Get all registered modules
+     */
+    getModules() {
+        return Object.assign({}, this.modules);
+    }
+    /**
+     * Get all registered methods
+     */
+    getMethods() {
+        return Object.assign({}, this.methods);
+    }
+    /**
+     * Get a specific method by name
+     */
+    getMethod(name) {
+        return this.methods[name];
+    }
+    /**
+     * Get a specific module config by name
+     */
+    getModule(name) {
+        return this.modules[name];
+    }
+    /**
+     * Check if a method exists
+     */
+    hasMethod(name) {
+        return name in this.methods;
+    }
+    /**
+     * Get method listing excluding internal fields
+     */
+    getMethodListing() {
+        const result = {};
+        const excludeFields = new Set(['fullname']);
+        for (const methodName in this.modules) {
+            const config = this.modules[methodName];
+            result[methodName] = this.copyConfig(config, excludeFields);
+        }
+        return result;
+    }
+    /**
+     * Recursively processes method map with underscore-prefixed descriptors
+     */
+    processMethodMap(path, methodMap) {
+        const prefix = path ? `${path}.` : '';
+        for (const key in methodMap) {
+            if (this.isModuleMeta(key) || this.isDescriptor(key)) {
+                continue;
+            }
+            const descriptor = methodMap[`_${key}`];
+            if (!descriptor) {
+                continue;
+            }
+            const item = methodMap[key];
+            if (typeof item === 'function') {
+                this.registerLegacyMethod(prefix, key, descriptor, item);
+            }
+            else if (typeof item === 'object' && item !== null) {
+                this.processMethodMap(`${prefix}${key}`, item);
+            }
+        }
+    }
+    /**
+     * Registers a single method using legacy format
+     */
+    registerLegacyMethod(prefix, name, descriptor, handler) {
+        const fullName = prefix + (descriptor.name || name);
+        const config = Object.assign(Object.assign({}, descriptor), { fullname: fullName });
+        try {
+            this.modules[fullName] = config;
+            this.methods[fullName] = handler;
+        }
+        catch (error) {
+            console.error(`Failed to register method ${fullName}:`, error);
+        }
+    }
+    /**
+     * Creates a copy of config object excluding specified fields
+     */
+    copyConfig(source, excludeFields) {
+        const result = {};
+        for (const key in source) {
+            if (!excludeFields.has(key) && Object.prototype.hasOwnProperty.call(source, key)) {
+                result[key] = source[key];
+            }
+        }
+        return result;
+    }
+    /**
+     * Checks if a key represents module metadata
+     */
+    isModuleMeta(key) {
+        return key === '_';
+    }
+    /**
+     * Checks if a key is a descriptor (starts with underscore)
+     */
+    isDescriptor(key) {
+        return key.startsWith('_');
+    }
+}
+exports.MethodRegistry = MethodRegistry;
+//# sourceMappingURL=method-registry.js.map

package/dist/src/method-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"method-registry.js","sourceRoot":"","sources":["../../src/method-registry.ts"],"names":[],"mappings":"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"}

package/dist/src/rpc-server.d.ts

@@ -1,39 +1,91 @@
+import { MethodMap, RequestMessage, EndpointConfig, EndpointHandler, BaseEndpointConfig } from './index';
 /**
- * The idea is to be able to easily register methods/functions to be called
- * remotely, to enable access control and return data directly, asynchronously or
- * opening a stream which delivers data for long running tasks or large data
- * transfers.
+ * RPC Server for registering and handling remote procedure calls.
  *
- * When registerCore is run with the wish core instance, it reads all objects
- * that have a property named "_". It scans those properties for properties
- * which have a descriptor property with the same name prepended with "_".
+ * Supports both modern endpoint registration and legacy underscore-prefixed methods.
+ * Provides real-time communication with support for streaming, events, and async operations.
  *
- * Sub modules are not implemented yet, but an example should look like the
- * relay, module below.
+ * Type-safe endpoint registration with custom configuration:
+ * ```typescript
+ * interface ReasonEndpoint extends BaseEndpointConfig {
+ *     validateArgs?: (args: any[], context: any) => boolean;
+ *     permissions?: string[];
+ *     rateLimit?: number;
+ * }
  *
- * Ex.
- *   rpc.insertMethods({
- *       _doThis: {
- *           doc: "This function does this, and emits progress each second and end.",
- *       },
- *       doThis: function(req,res) {
- *           ...
- *       },
- *       _relay: {
- *           doc: "A bunch of relay related functions"
- *       },
- *       relay: {
- *           _test: {},
- *           test: function() {},
- *           _list: {},
- *           list: function() {}
- *       }
- *   });
+ * const server = new Server<ReasonEndpoint>();
+ * server.endpoint('user.get', {
+ *     doc: 'Get user by ID',
+ *     args: 'userId: string',
+ *     validateArgs: (args, context) => validateUserArgs(args),
+ *     permissions: ['user', 'admin'],
+ *     rateLimit: 100
+ * }, async (req, res) => {
+ *     const user = await getUserById(req.args[0]);
+ *     res.send(user);
+ * });
+ * ```
+ *
+ * Default usage (backwards compatible):
+ * ```typescript
+ * const server = new Server();
+ * server.endpoint('user.get', {
+ *     doc: 'Get user by ID',
+ *     args: 'userId: string',
+ *     validate: (args, context) => validateUserArgs(args)
+ * }, async (req, res) => {
+ *     const user = await getUserById(req.args[0]);
+ *     res.send(user);
+ * });
+ * ```
+ *
+ * Legacy method registration (backwards compatibility):
+ * ```typescript
+ * server.insertMethods({
+ *     _getUser: {
+ *         doc: 'Get user by ID',
+ *         args: 'userId: string'
+ *     },
+ *     getUser: async (req, res) => {
+ *         const user = await getUserById(req.args[0]);
+ *         res.send(user);
+ *     }
+ * });
+ * ```
+ *
+ * Accessing metadata for custom validation and introspection:
+ * ```typescript
+ * // Get method metadata and check for custom validation properties
+ * const meta = server.getMethodMeta('user.get');
+ * if (meta?.validateArgs) {
+ *     const isValid = meta.validateArgs(args, context);
+ * }
+ * if (meta?.schema) {
+ *     const result = meta.schema.safeParse(args); // e.g., Zod
+ * }
+ * if (meta?.validator) {
+ *     meta.validator.validate(args); // e.g., Joi
+ * }
+ *
+ * // Generate documentation from all methods
+ * const allMeta = server.getAllMethodMeta();
+ * for (const [name, config] of Object.entries(allMeta)) {
+ *     console.log(`${name}: ${config.doc || 'No documentation'}`);
+ *     if (config.args) console.log(`  Args: ${config.args}`);
+ * }
+ * ```
+ *
+ * Features:
+ * - Type-safe endpoint registration with TypeScript
+ * - Streaming support for large data transfers
+ * - Real-time events and signals
+ * - Request validation and error handling
+ * - Session management and cleanup
+ * - Method discovery and documentation
+ * - Metadata access for external validation and introspection
  */
-import { MethodMap, RequestMessage } from './index';
-export declare class Server {
-    private modules;
-    private methods;
+export declare class Server<T extends BaseEndpointConfig = EndpointConfig> {
+    private registry;
     private requests;
     private clientIdCounter;
     /** internal request id counter */
@@ -42,14 +94,60 @@ export declare class Server {
     private invokeId;
     constructor(methods?: MethodMap);
     destroy(): void;
-    insertMethods(o: any): void;
-    addMethods(path: string, o: MethodMap): void;
-    listMethods(args: any, context: any, cb: any): void;
+    /**
+     * Legacy method for backwards compatibility
+     * Registers methods using the old underscore-prefixed structure
+     */
+    insertMethods(methodMap: MethodMap): void;
+    /**
+     * Lists all available methods and their configurations
+     */
+    listMethods(args: any[], context: any, callback: (error: any, result?: any) => void): void;
+    /**
+     * Cleanup when a client goes offline
+     */
     clientOffline(clientId: number): void;
+    /**
+     * Close all active connections and cleanup
+     */
     closeAll(): void;
-    parse(msg: RequestMessage, respond: any, context: any, clientId: number): void;
+    /**
+     * Safely cleanup a specific request
+     */
+    private cleanupRequest;
+    /**
+     * Parse and handle incoming RPC messages
+     */
+    parse(msg: RequestMessage, respond: (data: any) => void, context: any, clientId: number): void;
     emit(op: string, data: any): void;
-    invokeRaw(msg: RequestMessage, respond: any, context: any, clientId: any): void;
+    /**
+     * Process raw RPC invocation
+     */
+    invokeRaw(msg: RequestMessage, respond: (data: any) => void, context: any, clientId: number): void;
+    /**
+     * Handle push (streaming data) messages
+     */
+    private handlePushMessage;
+    /**
+     * Handle signal (streaming) messages
+     */
+    private handleSignalMessage;
+    /**
+     * Create response handlers for signal messages
+     */
+    private createSignalResponseHandlers;
+    /**
+     * Handle event messages (no response expected)
+     */
+    private handleEventMessage;
+    /**
+     * Handle regular RPC requests
+     */
+    private handleRegularRequest;
+    /**
+     * Create response handlers for regular requests
+     */
+    private createRegularResponseHandlers;
     close(clientId: number): void;
     open(): number;
     /**
@@ -58,10 +156,16 @@ export declare class Server {
      * @param config - Configuration object with doc, args, validate, etc.
      * @param handler - The endpoint handler function
      */
-    endpoint(name: string, config: {
-        doc?: string;
-        args?: string;
-        validate?: (args: any[], context: any) => any;
-        validateResult?: (result: any) => any;
-    }, handler: (req: any, res: any, context?: any) => any): void;
+    endpoint(name: string, config: T, handler: EndpointHandler): void;
+    /**
+     * Get metadata for a specific method (including all custom properties)
+     * @param name - Method name
+     * @returns The complete method configuration or undefined if not found
+     */
+    getMethodMeta(name: string): T | undefined;
+    /**
+     * Get metadata for all registered methods
+     * @returns Object containing all method configurations
+     */
+    getAllMethodMeta(): Record<string, T>;
 }