ts-procedures 2.1.1 → 3.0.0

package/src/implementations/http/hono-rpc/index.ts

@@ -0,0 +1,202 @@
+import { Hono, Context } from 'hono'
+import { kebabCase } from 'es-toolkit/string'
+import { Procedures, TProcedureRegistration } from '../../../index.js'
+import { RPCConfig, RPCHttpRouteDoc } from '../../types.js'
+import { castArray } from 'es-toolkit/compat'
+import { HonoFactoryItem, ExtractContext, ProceduresFactory } from './types.js'
+
+export type { RPCConfig, RPCHttpRouteDoc }
+
+export type HonoRPCAppBuilderConfig = {
+  /**
+   * An existing Hono application instance to use.
+   * If not provided, a new instance will be created.
+   */
+  app?: Hono
+  /** Optional path prefix for all RPC routes. */
+  pathPrefix?: string
+  onRequestStart?: (c: Context) => void
+  onRequestEnd?: (c: Context) => void
+  onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
+  error?: (
+    procedure: TProcedureRegistration,
+    c: Context,
+    error: Error
+  ) => Response | Promise<Response>
+}
+
+/**
+ * Builder class for creating a Hono application with RPC routes.
+ *
+ * Usage:
+ *   const PublicRPC = Procedures<PublicRPCContext, RPCConfig>()
+ *   const ProtectedRPC = Procedures<ProtectedRPCContext, RPCConfig>()
+ *
+ *   const rpcApp = new HonoRPCAppBuilder()
+ *     .register(PublicRPC, (c): Promise<PublicRPCContext> => { /* context resolution logic * / })
+ *     .register(ProtectedRPC, (c): Promise<ProtectedRPCContext> => { /* context resolution logic * / })
+ *     .build();
+ *
+ *   const app = rpcApp.app; // Hono application
+ *   const docs = rpcApp.docs; // RPC route documentation
+ */
+export class HonoRPCAppBuilder {
+  /**
+   * Constructor for HonoRPCAppBuilder.
+   *
+   * @param config
+   */
+  constructor(readonly config?: HonoRPCAppBuilderConfig) {
+    if (config?.app) {
+      this._app = config.app
+    }
+
+    if (config?.onRequestStart) {
+      this._app.use('*', async (c, next) => {
+        config.onRequestStart!(c)
+        await next()
+      })
+    }
+
+    if (config?.onRequestEnd) {
+      this._app.use('*', async (c, next) => {
+        await next()
+        config.onRequestEnd!(c)
+      })
+    }
+  }
+
+  /**
+   * Generates the RPC route path based on the RPC configuration.
+   * The RPCConfig name can be a string or an array of strings to form nested paths.
+   *
+   * Example
+   *  name: ['string', 'string-string', 'string']
+   *  path: /string/string-string/string/version
+   * @param config
+   */
+  static makeRPCHttpRoutePath({
+    name,
+    config,
+    prefix,
+  }: {
+    name: string
+    prefix?: string
+    config: RPCConfig
+  }) {
+    const normalizedPrefix = prefix ? (prefix.startsWith('/') ? prefix : `/${prefix}`) : ''
+
+    return `${normalizedPrefix}/${castArray(config.scope).map(kebabCase).join('/')}/${kebabCase(name)}/${String(config.version).trim()}`
+  }
+
+  /**
+   * Instance method wrapper for makeRPCHttpRoutePath that uses the builder's pathPrefix.
+   * @param config - The RPC configuration
+   */
+  makeRPCHttpRoutePath(name: string, config: RPCConfig): string {
+    return HonoRPCAppBuilder.makeRPCHttpRoutePath({
+      name,
+      config,
+      prefix: this.config?.pathPrefix,
+    })
+  }
+
+  private factories: HonoFactoryItem<any>[] = []
+
+  private _app: Hono = new Hono()
+  private _docs: RPCHttpRouteDoc[] = []
+
+  get app(): Hono {
+    return this._app
+  }
+
+  get docs(): RPCHttpRouteDoc[] {
+    return this._docs
+  }
+
+  /**
+   * Registers a procedure factory with its context.
+   * @param factory - The procedure factory created by Procedures<Context, RPCConfig>()
+   * @param factoryContext - The context for procedure handlers. Can be a direct value,
+   *                         a sync function (c) => Context, or an async function (c) => Promise<Context>
+   */
+  register<TFactory extends ProceduresFactory>(
+    factory: TFactory,
+    factoryContext:
+      | ExtractContext<TFactory>
+      | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>)
+  ): this {
+    this.factories.push({ factory, factoryContext } as HonoFactoryItem<any>)
+    return this
+  }
+
+  /**
+   * Builds and returns the Hono application with registered RPC routes.
+   * @return Hono
+   */
+  build(): Hono {
+    this.factories.forEach(({ factory, factoryContext }) => {
+      factory.getProcedures().map((procedure: TProcedureRegistration<any, RPCConfig>) => {
+        const route = this.buildRpcHttpRouteDoc(procedure)
+
+        this._docs.push(route)
+
+        this._app.post(route.path, async (c) => {
+          try {
+            const context =
+              typeof factoryContext === 'function'
+                ? await factoryContext(c)
+                : (factoryContext as ExtractContext<typeof factory>)
+
+            // Hono uses c.req.json() for body parsing
+            const body = await c.req.json().catch(() => ({}))
+            const result = await procedure.handler(context, body)
+
+            if (this.config?.onSuccess) {
+              this.config.onSuccess(procedure, c)
+            }
+
+            // Hono returns Response objects via c.json()
+            return c.json(result)
+          } catch (error) {
+            if (this.config?.error) {
+              return this.config.error(procedure, c, error as Error)
+            }
+            // Default error handling
+            return c.json({ error: (error as Error).message }, 500)
+          }
+        })
+      })
+    })
+
+    return this._app
+  }
+
+  /**
+   * Generates the RPC HTTP route for the given procedure.
+   * @param procedure
+   */
+  private buildRpcHttpRouteDoc(procedure: TProcedureRegistration<any, RPCConfig>): RPCHttpRouteDoc {
+    const { config } = procedure
+    const path = HonoRPCAppBuilder.makeRPCHttpRoutePath({
+      name: procedure.name,
+      config,
+      prefix: this.config?.pathPrefix,
+    })
+    const method = 'post' // RPCs use POST method
+    const jsonSchema: { body?: object; response?: object } = {}
+
+    if (config.schema?.params) {
+      jsonSchema.body = config.schema.params
+    }
+    if (config.schema?.returnType) {
+      jsonSchema.response = config.schema.returnType
+    }
+
+    return {
+      path,
+      method,
+      jsonSchema,
+    }
+  }
+}

package/src/implementations/http/hono-rpc/types.ts

@@ -0,0 +1,33 @@
+import { RPCConfig } from '../../types.js'
+import { Procedures } from '../../../index.js'
+import { Context } from 'hono'
+
+/**
+ * Extracts the TContext type from a Procedures factory return type.
+ * Uses the first parameter of the handler function to infer the context type.
+ */
+export type ExtractContext<TFactory> = TFactory extends {
+  getProcedures: () => Array<{ handler: (ctx: infer TContext, ...args: any[]) => any }>
+}
+  ? TContext
+  : never
+
+/**
+ * Minimal structural type for a Procedures factory.
+ * Uses explicit `any` types to avoid variance issues with generic constraints.
+ */
+export type ProceduresFactory = {
+  getProcedures: () => Array<{
+    name: string
+    config: any
+    handler: (ctx: any, params?: any) => Promise<any>
+  }>
+  Create: (...args: any[]) => any
+}
+
+export type HonoFactoryItem<TFactory = ReturnType<typeof Procedures<any, RPCConfig>>> = {
+  factory: TFactory
+  factoryContext:
+    | ExtractContext<TFactory>
+    | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>)
+}

package/src/implementations/types.ts

@@ -1,7 +1,8 @@
 import { Procedures } from '../index.js'
 
 export interface RPCConfig {
-  name: string | string[]
+  // Scope or scopes (scope segments) required to access the RPC
+  scope: string | string[]
   version: number
 }
 

package/src/index.test.ts

@@ -363,4 +363,87 @@ describe('Procedures', () => {
       CheckIsAuthenticated({ authToken: 'not-valid-token' }, {}),
     ).rejects.toThrowError(ProcedureError)
   })
+
+  test('Procedures - duplicate registration throws before schema computation', () => {
+    const { Create } = Procedures()
+
+    Create('DuplicateTest', {}, async () => 'first')
+
+    expect(() => {
+      Create('DuplicateTest', {}, async () => 'second')
+    }).toThrow('Procedure with name DuplicateTest is already registered')
+  })
+
+  test('Procedures - wrapped errors preserve cause', async () => {
+    const { Create } = Procedures()
+    const originalError = new Error('Database connection failed')
+    ;(originalError as any).code = 'ECONNREFUSED'
+
+    const { TestCause } = Create('TestCause', {}, async () => {
+      throw originalError
+    })
+
+    try {
+      await TestCause({}, {})
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureError)
+      expect(e.cause).toBe(originalError)
+      expect(e.cause.code).toBe('ECONNREFUSED')
+    }
+  })
+
+  test('Procedures - getProcedure returns specific procedure', () => {
+    const { Create, getProcedure } = Procedures()
+
+    Create('FindMe', {}, async () => 'found')
+
+    const proc = getProcedure('FindMe')
+    expect(proc).toBeDefined()
+    expect(proc?.name).toBe('FindMe')
+
+    expect(getProcedure('NotFound')).toBeUndefined()
+  })
+
+  test('Procedures - removeProcedure allows re-registration', () => {
+    const { Create, removeProcedure, getProcedure } = Procedures()
+
+    Create('Removable', {}, async () => 'v1')
+    expect(getProcedure('Removable')).toBeDefined()
+
+    const removed = removeProcedure('Removable')
+    expect(removed).toBe(true)
+    expect(getProcedure('Removable')).toBeUndefined()
+
+    // Can now re-register
+    Create('Removable', {}, async () => 'v2')
+    expect(getProcedure('Removable')).toBeDefined()
+  })
+
+  test('Procedures - clear removes all procedures', () => {
+    const { Create, getProcedures, clear } = Procedures()
+
+    Create('One', {}, async () => '1')
+    Create('Two', {}, async () => '2')
+    expect(getProcedures().length).toBe(2)
+
+    clear()
+    expect(getProcedures().length).toBe(0)
+  })
+
+  test('Procedures - ctx.error still works after optimization', async () => {
+    const { Create } = Procedures()
+
+    const { ErrorTest } = Create('ErrorTest', {}, async (ctx) => {
+      throw ctx.error('Custom error message', { code: 'ERR_001' })
+    })
+
+    try {
+      await ErrorTest({}, {})
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureError)
+      expect(e.message).toBe('Custom error message')
+      expect(e.procedureName).toBe('ErrorTest')
+      expect(e.meta).toEqual({ code: 'ERR_001' })
+    }
+  })
 })

package/src/index.ts

@@ -68,8 +68,18 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
       params: TSchemaLib<TParams>
     ) => Promise<TSchemaLib<TReturnType>>
   ) {
+    // BEFORE computeSchema - fail fast on duplicate
+    if (procedures.has(name)) {
+      throw new Error(`Procedure with name ${name} is already registered`)
+    }
+
     const { jsonSchema, validations } = computeSchema(name, config.schema)
 
+    // Create error factory once at registration time (outside handler)
+    const errorFactory = (message: string, meta?: object) => {
+      return new ProcedureError(name, message, meta)
+    }
+
     const registeredProcedure = {
       name,
       config: {
@@ -97,12 +107,10 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
           }
 
           const localCtx: TLocalContext = {
-            error: (message: string, meta?: object) => {
-              return new ProcedureError(name, message, meta)
-            },
+            error: errorFactory,  // Reuse pre-created factory
           }
 
-          return handler(
+          return await handler(
             {
               ...ctx,
               ...localCtx,
@@ -114,6 +122,7 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
             throw error
           } else {
             const err = new ProcedureError(name, `Error in handler for ${name} - ${error?.message}`)
+            err.cause = error  // Preserve original error
             err.stack = error.stack
             throw err
           }
@@ -121,10 +130,6 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
       },
     }
 
-    if (procedures.has(name)) {
-      throw new Error(`Procedure with name ${name} is already registered`)
-    }
-
     procedures.set(name, registeredProcedure)
 
     if (builder?.onCreate) {
@@ -167,6 +172,27 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
       return Array.from(procedures.values())
     },
 
+    /**
+     * Get a specific procedure by name
+     */
+    getProcedure: (name: string) => {
+      return procedures.get(name)
+    },
+
+    /**
+     * Remove a procedure by name
+     */
+    removeProcedure: (name: string) => {
+      return procedures.delete(name)
+    },
+
+    /**
+     * Clear all registered procedures
+     */
+    clear: () => {
+      procedures.clear()
+    },
+
     Create,
   }
 }

package/src/schema/parser.test.ts

@@ -153,4 +153,30 @@ describe('schemaParser', () => {
     ).toMatchObject({})
     expect(schema.validation.params?.({}).errors?.[0]?.message).toMatch(/must have required property 'a'/)
   })
+
+  test('validation returns error if validator fails to initialize', async () => {
+    // Create a schema that will pass extraction but creates a validation function
+    // that handles the uninitialized case gracefully
+    let parseErrorCalled = false
+    
+    const result = schemaParser(
+      {
+        // Using a valid schema to get through extraction, but we'll test the guard
+        params: Type.Object({ name: Type.String() }),
+      },
+      () => {
+        parseErrorCalled = true
+      },
+    )
+
+    // The validator should be initialized for valid schemas
+    expect(result.validation.params).toBeDefined()
+    
+    // Test that the validation function works correctly
+    const validResult = result.validation.params?.({ name: 'test' })
+    expect(validResult?.errors).toBeUndefined()
+    
+    const invalidResult = result.validation.params?.({})
+    expect(invalidResult?.errors).toBeDefined()
+  })
 })

package/src/schema/parser.ts

@@ -45,7 +45,7 @@ export function schemaParser(
         params: `Error extracting json schema schema.params - schema.params might be empty or it is not a valid suretype or typebox type`,
       })
     } else {
-      let paramsValidator: AJV.ValidateFunction
+      let paramsValidator: AJV.ValidateFunction | undefined
 
       try {
         paramsValidator = ajv.compile(jsonSchema.params as TJSONSchema)
@@ -56,6 +56,10 @@ export function schemaParser(
       }
 
       validation.params = (params: any) => {
+        if (!paramsValidator) {
+          return { errors: [{ message: 'Validator not initialized', keyword: 'internal' } as TSchemaValidationError] }
+        }
+
         const valid = paramsValidator(params)
 
         if (!valid) {