rpc-express-toolkit 4.1.0 → 4.2.1

package/src/safe.d.ts

@@ -2,6 +2,38 @@ import type { Router } from 'express';
 import type { RpcEndpoint, RpcClient, RpcEndpointOptions, RpcClientOptions } from './index';
 
 /**
+ * RPC Client with safe serialization enabled by default.
+ * Extends RpcClient with safeEnabled: true preset.
+ */
+export class RpcSafeClient extends RpcClient {
+  constructor(
+    endpoint: string,
+    defaultHeaders?: Record<string, string>,
+    options?: RpcClientOptions
+  );
+}
+
+/**
+ * RPC Endpoint with safe serialization enabled by default.
+ * Extends RpcEndpoint with safeEnabled: true and strictMode: true presets.
+ */
+export class RpcSafeEndpoint<C = any> extends RpcEndpoint<C> {
+  constructor(
+    router: Router,
+    context: C,
+    endpoint?: string,
+    options?: RpcEndpointOptions
+  );
+  
+  constructor(
+    router: Router,
+    context: C,
+    options?: RpcEndpointOptions
+  );
+}
+
+/**
+ * @deprecated Use `new RpcSafeEndpoint(...)` instead.
  * Factory: create a RpcEndpoint with safe defaults (safeEnabled=true, strictMode=true).
  */
 export function createSafeEndpoint<C = any>(
@@ -18,6 +50,7 @@ export function createSafeEndpoint<C = any>(
 ): RpcEndpoint<C>;
 
 /**
+ * @deprecated Use `new RpcSafeClient(...)` instead.
  * Factory: create a RpcClient with safe defaults (safeEnabled=true).
  */
 export function createSafeClient(

package/src/safe.js

@@ -1,14 +1,72 @@
+/* eslint-disable max-classes-per-file */
 const Main = require('./index');
 
-// Default safe options applied unless explicitly overridden
-const defaultSafeOptions = {
-  safeEnabled: true,
-  strictMode: true,
-};
+/**
+ * RPC Client with safe serialization enabled by default.
+ * Extends RpcClient with safeEnabled: true preset.
+ *
+ * This class automatically enables safe prefixes for strings (S:) and dates (D:)
+ * to avoid ambiguity with BigInt and ISO date strings.
+ *
+ * @example
+ * const client = new RpcSafeClient('http://localhost:3000/api');
+ * const result = await client.call('add', { a: 10n, b: 20n });
+ */
+class RpcSafeClient extends Main.RpcClient {
+  /**
+   * @param {string} endpoint The JSON-RPC endpoint URL.
+   * @param {Object} [defaultHeaders={}] Optional default headers to include in requests.
+   * @param {Object} [options={}] Optional configuration options (safeEnabled will be set to true).
+   */
+  constructor(endpoint, defaultHeaders = {}, options = {}) {
+    super(endpoint, defaultHeaders, { safeEnabled: true, ...options });
+  }
+}
+
+/**
+ * RPC Endpoint with safe serialization enabled by default.
+ * Extends RpcEndpoint with safeEnabled: true and strictMode: true presets.
+ *
+ * This class automatically enables safe prefixes for strings (S:) and dates (D:)
+ * and enforces strict compatibility checking with clients.
+ *
+ * @example
+ * const app = express();
+ * const rpc = new RpcSafeEndpoint(app, {});
+ * rpc.addMethod('add', {
+ *   handler: (req, ctx, params) => params.a + params.b,
+ * });
+ *
+ * @template C
+ */
+class RpcSafeEndpoint extends Main.RpcEndpoint {
+  /**
+   * @param {import('express').Router} router Express router or app
+   * @param {C} context Context object passed to handlers
+   * @param {string|object} [endpointOrOptions='/api'] Endpoint path or options object
+   * @param {object} [options] Options object (when endpointOrOptions is a string)
+   */
+  constructor(router, context, endpointOrOptions = '/api', options = {}) {
+    const defaultSafeOptions = {
+      safeEnabled: true,
+      strictMode: true,
+    };
+
+    if (typeof endpointOrOptions === 'string') {
+      // String endpoint with options object
+      const finalOptions = { ...defaultSafeOptions, ...options };
+      super(router, context, endpointOrOptions, finalOptions);
+    } else {
+      // Options object form
+      const finalOptions = { ...defaultSafeOptions, ...endpointOrOptions };
+      super(router, context, finalOptions);
+    }
+  }
+}
 
 /**
+ * @deprecated Use `new RpcSafeEndpoint(...)` instead.
  * Create a RpcEndpoint with safe defaults (safeEnabled=true, strictMode=true).
- * Preserves both constructor signatures supported by RpcEndpoint.
  *
  * @param {import('express').Router} router
  * @param {any} context
@@ -21,34 +79,34 @@ function createSafeEndpoint(
   endpointOrOptions = '/api',
   options = {}
 ) {
-  if (typeof endpointOrOptions === 'string') {
-    const finalOptions = { ...defaultSafeOptions, ...options };
-    return new Main.RpcEndpoint(
-      router,
-      context,
-      endpointOrOptions,
-      finalOptions
-    );
-  }
-  // options object form
-  const final = { ...defaultSafeOptions, ...endpointOrOptions };
-  return new Main.RpcEndpoint(router, context, final);
+  console.warn(
+    'createSafeEndpoint() is deprecated. Use `new RpcSafeEndpoint(...)` instead.'
+  );
+  return new RpcSafeEndpoint(router, context, endpointOrOptions, options);
 }
 
 /**
+ * @deprecated Use `new RpcSafeClient(...)` instead.
  * Create a RpcClient with safe defaults (safeEnabled=true).
+ *
  * @param {string} endpoint
  * @param {Record<string,string>} [defaultHeaders]
  * @param {object} [options]
  */
 function createSafeClient(endpoint, defaultHeaders = {}, options = {}) {
-  const finalOptions = { safeEnabled: true, ...options };
-  return new Main.RpcClient(endpoint, defaultHeaders, finalOptions);
+  console.warn(
+    'createSafeClient() is deprecated. Use `new RpcSafeClient(...)` instead.'
+  );
+  return new RpcSafeClient(endpoint, defaultHeaders, options);
 }
 
 module.exports = {
   // Re-export everything for convenience
   ...Main,
+  // New class-based API
+  RpcSafeClient,
+  RpcSafeEndpoint,
+  // Deprecated factory functions (kept for backward compatibility)
   createSafeEndpoint,
   createSafeClient,
 };

package/src/validation.js

@@ -1,221 +1,222 @@
-/* eslint max-classes-per-file: off */
-const Ajv = require('ajv');
-const addFormats = require('ajv-formats');
-
-/**
- * JSON-RPC 2.0 Schema Validation Error
- */
-class SchemaValidator {
-  constructor(options = {}) {
-    this.ajv = new Ajv({
-      allErrors: true,
-      removeAdditional: options.removeAdditional || false,
-      useDefaults: options.useDefaults !== false,
-      coerceTypes: options.coerceTypes || false,
-      ...options.ajvOptions,
-    });
-
-    addFormats(this.ajv);
-
-    // Add custom formats
-    this.addCustomFormats();
-  }
-
-  /**
-   * Add custom format validators
-   */
-  addCustomFormats() {
-    // BigInt format
-    this.ajv.addFormat('bigint', {
-      type: 'string',
-      validate: (data) => /^-?\d+n?$/.test(data),
-    });
-
-    // ObjectId format (MongoDB style)
-    this.ajv.addFormat('objectid', {
-      type: 'string',
-      validate: (data) => /^[0-9a-fA-F]{24}$/.test(data),
-    });
-  }
-
-  /**
-   * Validate parameters against a schema
-   * @param {any} params
-   * @param {Object} schema
-   * @returns {Object} validation result
-   */
-  validate(params, schema) {
-    const validator = this.ajv.compile(schema);
-    const valid = validator(params);
-
-    return {
-      valid,
-      errors: valid ? null : validator.errors,
-      data: params,
-    };
-  }
-
-  /**
-   * Create a validation middleware
-   * @param {Object} schema
-   * @returns {Function}
-   */
-  middleware(schema) {
-    return async (context) => {
-      const { params } = context;
-      const result = this.validate(params, schema);
-
-      if (!result.valid) {
-        const error = new Error('Validation failed');
-        error.code = -32602; // Invalid params
-        error.data = {
-          validationErrors: result.errors.map((err) => ({
-            field: err.instancePath || err.schemaPath,
-            message: err.message,
-            value: err.data,
-          })),
-        };
-        throw error;
-      }
-
-      // Update params with validated/coerced data
-      context.params = result.data;
-      return context;
-    };
-  }
-
-  /**
-   * Add a custom keyword
-   * @param {string} name
-   * @param {Object} definition
-   */
-  addKeyword(name, definition) {
-    this.ajv.addKeyword(name, definition);
-  }
-}
-
-/**
- * Common schema definitions
- */
-const commonSchemas = {
-  // Pagination parameters
-  pagination: {
-    type: 'object',
-    properties: {
-      page: { type: 'integer', minimum: 1, default: 1 },
-      limit: { type: 'integer', minimum: 1, maximum: 100, default: 10 },
-      sort: { type: 'string' },
-      order: { type: 'string', enum: ['asc', 'desc'], default: 'asc' },
-    },
-  },
-
-  // User identification
-  userId: {
-    oneOf: [
-      { type: 'string', format: 'objectid' },
-      { type: 'string', format: 'uuid' },
-      { type: 'integer', minimum: 1 },
-    ],
-  },
-
-  // Email validation
-  email: {
-    type: 'string',
-    format: 'email',
-    maxLength: 255,
-  },
-
-  // Password requirements
-  password: {
-    type: 'string',
-    minLength: 8,
-    maxLength: 128,
-    pattern: '^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)',
-  },
-
-  // BigInt validation
-  bigintString: {
-    type: 'string',
-    format: 'bigint',
-  },
-
-  // Date validation
-  dateString: {
-    type: 'string',
-    format: 'date-time',
-  },
-};
-
-/**
- * Schema builder helper
- */
-class SchemaBuilder {
-  constructor() {
-    this.schema = {
-      type: 'object',
-      properties: {},
-      required: [],
-    };
-  }
-
-  /**
-   * Add a property to the schema
-   * @param {string} name
-   * @param {Object} definition
-   * @param {boolean} required
-   * @returns {SchemaBuilder}
-   */
-  property(name, definition, required = false) {
-    this.schema.properties[name] = definition;
-    if (required) {
-      this.schema.required.push(name);
-    }
-    return this;
-  }
-
-  /**
-   * Add multiple properties
-   * @param {Object} properties
-   * @returns {SchemaBuilder}
-   */
-  properties(properties) {
-    Object.entries(properties).forEach(([name, definition]) => {
-      this.property(name, definition);
-    });
-    return this;
-  }
-
-  /**
-   * Set required fields
-   * @param {string[]} fields
-   * @returns {SchemaBuilder}
-   */
-  required(fields) {
-    this.schema.required = [...new Set([...this.schema.required, ...fields])];
-    return this;
-  }
-
-  /**
-   * Add additional properties setting
-   * @param {boolean} allowed
-   * @returns {SchemaBuilder}
-   */
-  additionalProperties(allowed) {
-    this.schema.additionalProperties = allowed;
-    return this;
-  }
-
-  /**
-   * Build and return the schema
-   * @returns {Object}
-   */
-  build() {
-    return this.schema;
-  }
-}
-
-module.exports = {
-  SchemaValidator,
-  commonSchemas,
-  SchemaBuilder,
-};
+/* eslint max-classes-per-file: off */
+const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
+
+/**
+ * JSON-RPC 2.0 Schema Validation Error
+ */
+class SchemaValidator {
+  constructor(options = {}) {
+    this.ajv = new Ajv({
+      allErrors: true,
+      removeAdditional: options.removeAdditional || false,
+      useDefaults: options.useDefaults !== false,
+      coerceTypes: options.coerceTypes || false,
+      strict: false, // Allow unknown keywords like exposeSchema in method options
+      ...options.ajvOptions,
+    });
+
+    addFormats(this.ajv);
+
+    // Add custom formats
+    this.addCustomFormats();
+  }
+
+  /**
+   * Add custom format validators
+   */
+  addCustomFormats() {
+    // BigInt format
+    this.ajv.addFormat('bigint', {
+      type: 'string',
+      validate: (data) => /^-?\d+n?$/.test(data),
+    });
+
+    // ObjectId format (MongoDB style)
+    this.ajv.addFormat('objectid', {
+      type: 'string',
+      validate: (data) => /^[0-9a-fA-F]{24}$/.test(data),
+    });
+  }
+
+  /**
+   * Validate parameters against a schema
+   * @param {any} params
+   * @param {Object} schema
+   * @returns {Object} validation result
+   */
+  validate(params, schema) {
+    const validator = this.ajv.compile(schema);
+    const valid = validator(params);
+
+    return {
+      valid,
+      errors: valid ? null : validator.errors,
+      data: params,
+    };
+  }
+
+  /**
+   * Create a validation middleware
+   * @param {Object} schema
+   * @returns {Function}
+   */
+  middleware(schema) {
+    return async (context) => {
+      const { params } = context;
+      const result = this.validate(params, schema);
+
+      if (!result.valid) {
+        const error = new Error('Validation failed');
+        error.code = -32602; // Invalid params
+        error.data = {
+          validationErrors: result.errors.map((err) => ({
+            field: err.instancePath || err.schemaPath,
+            message: err.message,
+            value: err.data,
+          })),
+        };
+        throw error;
+      }
+
+      // Update params with validated/coerced data
+      context.params = result.data;
+      return context;
+    };
+  }
+
+  /**
+   * Add a custom keyword
+   * @param {string} name
+   * @param {Object} definition
+   */
+  addKeyword(name, definition) {
+    this.ajv.addKeyword(name, definition);
+  }
+}
+
+/**
+ * Common schema definitions
+ */
+const commonSchemas = {
+  // Pagination parameters
+  pagination: {
+    type: 'object',
+    properties: {
+      page: { type: 'integer', minimum: 1, default: 1 },
+      limit: { type: 'integer', minimum: 1, maximum: 100, default: 10 },
+      sort: { type: 'string' },
+      order: { type: 'string', enum: ['asc', 'desc'], default: 'asc' },
+    },
+  },
+
+  // User identification
+  userId: {
+    oneOf: [
+      { type: 'string', format: 'objectid' },
+      { type: 'string', format: 'uuid' },
+      { type: 'integer', minimum: 1 },
+    ],
+  },
+
+  // Email validation
+  email: {
+    type: 'string',
+    format: 'email',
+    maxLength: 255,
+  },
+
+  // Password requirements
+  password: {
+    type: 'string',
+    minLength: 8,
+    maxLength: 128,
+    pattern: '^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)',
+  },
+
+  // BigInt validation
+  bigintString: {
+    type: 'string',
+    format: 'bigint',
+  },
+
+  // Date validation
+  dateString: {
+    type: 'string',
+    format: 'date-time',
+  },
+};
+
+/**
+ * Schema builder helper
+ */
+class SchemaBuilder {
+  constructor() {
+    this.schema = {
+      type: 'object',
+      properties: {},
+      required: [],
+    };
+  }
+
+  /**
+   * Add a property to the schema
+   * @param {string} name
+   * @param {Object} definition
+   * @param {boolean} required
+   * @returns {SchemaBuilder}
+   */
+  property(name, definition, required = false) {
+    this.schema.properties[name] = definition;
+    if (required) {
+      this.schema.required.push(name);
+    }
+    return this;
+  }
+
+  /**
+   * Add multiple properties
+   * @param {Object} properties
+   * @returns {SchemaBuilder}
+   */
+  properties(properties) {
+    Object.entries(properties).forEach(([name, definition]) => {
+      this.property(name, definition);
+    });
+    return this;
+  }
+
+  /**
+   * Set required fields
+   * @param {string[]} fields
+   * @returns {SchemaBuilder}
+   */
+  required(fields) {
+    this.schema.required = [...new Set([...this.schema.required, ...fields])];
+    return this;
+  }
+
+  /**
+   * Add additional properties setting
+   * @param {boolean} allowed
+   * @returns {SchemaBuilder}
+   */
+  additionalProperties(allowed) {
+    this.schema.additionalProperties = allowed;
+    return this;
+  }
+
+  /**
+   * Build and return the schema
+   * @returns {Object}
+   */
+  build() {
+    return this.schema;
+  }
+}
+
+module.exports = {
+  SchemaValidator,
+  commonSchemas,
+  SchemaBuilder,
+};