ts-procedures 5.9.1 → 5.10.2

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

@@ -0,0 +1,238 @@
+import { Hono, Context } from 'hono'
+import { kebabCase } from 'es-toolkit/string'
+import { TProcedureRegistration } from '../../../index.js'
+import {
+  ExtractConfig,
+  ExtractContext,
+  ProceduresFactory,
+  RPCConfig,
+  RPCHttpRouteDoc,
+} from '../../types.js'
+import { castArray } from 'es-toolkit/compat'
+import { HonoFactoryItem } 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 handler called when a procedure throws an error.
+   * @param procedure
+   * @param c
+   * @param error
+   */
+  onError?: (
+    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 & object)[] = []
+
+  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>
+   * @param extendProcedureDoc - A custom function to extend the generated RPC route documentation for each procedure.
+   */
+  register<TFactory extends ProceduresFactory>(
+    factory: TFactory,
+    factoryContext:
+      | ExtractContext<TFactory>
+      | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>),
+    extendProcedureDoc?: (params: {
+      /* RPC App builder base http route doc */
+      base: RPCHttpRouteDoc
+      /* Procedure registration */
+      procedure: TProcedureRegistration<any, ExtractConfig<TFactory>>
+    }) => Record<string, any>
+  ): this {
+    this.factories.push({ factory, factoryContext, extendProcedureDoc } as HonoFactoryItem<any>)
+    return this
+  }
+
+  /**
+   * Builds and returns the Hono application with registered RPC routes.
+   * @return Hono
+   */
+  build(): Hono {
+    this.factories.forEach(({ factory, factoryContext, extendProcedureDoc }) => {
+      factory.getProcedures().map((procedure: TProcedureRegistration<any, RPCConfig>) => {
+        const route = this.buildRpcHttpRouteDoc(procedure, extendProcedureDoc)
+
+        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, signal: c.req.raw.signal }, 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?.onError) {
+              return this.config.onError(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>,
+    extendProcedureDoc: HonoFactoryItem['extendProcedureDoc']
+  ): RPCHttpRouteDoc {
+    const { config } = procedure
+    const path = HonoRPCAppBuilder.makeRPCHttpRoutePath({
+      name: procedure.name,
+      config,
+      prefix: this.config?.pathPrefix,
+    })
+    const method = 'post' as const // RPCs use POST method
+    const jsonSchema: { body?: Record<string, unknown>; response?: Record<string, unknown> } = {}
+
+    if (config.schema?.params) {
+      jsonSchema.body = config.schema.params
+    }
+    if (config.schema?.returnType) {
+      jsonSchema.response = config.schema.returnType
+    }
+
+    const base = {
+      kind: 'rpc' as const,
+      name: procedure.name,
+      version: config.version,
+      scope: config.scope,
+      path,
+      method,
+      jsonSchema,
+    }
+    let extendedDoc: object = {}
+
+    if (extendProcedureDoc) {
+      extendedDoc = extendProcedureDoc({ base, procedure })
+    }
+
+    return {
+      ...extendedDoc,
+      ...base,
+    }
+  }
+}

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

@@ -0,0 +1,16 @@
+import { ExtractConfig, ExtractContext, RPCConfig, RPCHttpRouteDoc } from '../../types.js'
+import { Procedures, TProcedureRegistration } from '../../../index.js'
+import { Context } from 'hono'
+
+export type HonoFactoryItem<TFactory = ReturnType<typeof Procedures<any, RPCConfig>>> = {
+  factory: TFactory
+  factoryContext:
+    | ExtractContext<TFactory>
+    | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>)
+  extendProcedureDoc?: (params: {
+    /* RPC App builder base http route doc */
+    base: RPCHttpRouteDoc
+    /* Procedure registration */
+    procedure: TProcedureRegistration<any, ExtractConfig<TFactory>>
+  }) => Record<string, any>
+}

package/src/implementations/http/hono-stream/README.md

@@ -37,7 +37,7 @@ StreamRPC.CreateStream(
     scope: ['user', 'notifications'],
     version: 1,
     schema: {
-      yieldType: v.object({ id: v.number(), message: v.string() }),
+      yieldType: Type.Object({ id: Type.Number(), message: Type.String() }),
     },
   },
   async function* (ctx) {
@@ -344,19 +344,19 @@ StreamRPC.CreateStream('WatchEvents', {
   scope: 'events',
   version: 1,
   schema: {
-    params: v.object({ roomId: v.string() }),
+    params: Type.Object({ roomId: Type.String() }),
     // Union type: clients know exactly what to expect
-    yieldType: v.union([
-      v.object({
-        type: v.literal('event'),
-        eventType: v.string(),
-        data: v.any()
+    yieldType: Type.Union([
+      Type.Object({
+        type: Type.Literal('event'),
+        eventType: Type.String(),
+        data: Type.Any()
       }),
-      v.object({
-        type: v.literal('error'),
-        code: v.string(),
-        message: v.string(),
-        retryable: v.boolean()
+      Type.Object({
+        type: Type.Literal('error'),
+        code: Type.String(),
+        message: Type.String(),
+        retryable: Type.Boolean()
       })
     ])
   }