ts-procedures 1.1.0 → 2.0.0

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

@@ -0,0 +1,180 @@
+import express from 'express'
+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 { ExpressFactoryItem, ExtractContext, ProceduresFactory } from './types.js'
+
+export type { RPCConfig, RPCHttpRouteDoc }
+/**
+ * Builder class for creating an Express application with RPC routes.
+ *
+ * Usage:
+ *   const PublicRPC = Procedures<PublicRPCContext, RPCConfig>()
+ *   const ProtectedRPC = Procedures<ProtectedRPCContext, RPCConfig>()
+ *
+ *   const rpcApp = new ExpressRPCAppBuilder()
+ *     .register(PublicRPC, (req): Promise<PublicRPCContext> => { /* context resolution logic * / })
+ *     .register(ProtectedRPC, (req): Promise<ProtectedRPCContext> => { /* context resolution logic * / })
+ *     .build();
+ *
+ *   const app = rpcApp.app; // Express application
+ *   const docs = rpcApp.docs; // RPC route documentation
+ */
+export class ExpressRPCAppBuilder {
+  /**
+   * Constructor for ExpressRPCAppBuilder.
+   *
+   * @param config
+   */
+  constructor(
+    readonly config?: {
+      /**
+       * An existing Express application instance to use.
+       * When provided, ensure to set up necessary middleware (e.g., json/body parser) beforehand.
+       * If not provided, a new instance will be created.
+       */
+      app?: express.Express
+      onRequestStart?: (req: express.Request) => void
+      onRequestEnd?: (req: express.Request, res: express.Response) => void
+      onSuccess?: (
+        procedure: TProcedureRegistration,
+        req: express.Request,
+        res: express.Response
+      ) => void
+      error?: (
+        procedure: TProcedureRegistration,
+        req: express.Request,
+        res: express.Response,
+        error: Error
+      ) => void
+    }
+  ) {
+    if (config?.app) {
+      this._app = config.app
+    } else {
+      // Default middleware if no app is provided
+      this._app.use(express.json())
+    }
+
+    if (config?.onRequestStart) {
+      this._app.use((req, res, next) => {
+        config.onRequestStart!(req)
+        next()
+      })
+    }
+
+    if (config?.onRequestEnd) {
+      this._app.use((req, res, next) => {
+        res.on('finish', () => {
+          config.onRequestEnd!(req, res)
+        })
+        next()
+      })
+    }
+  }
+
+  private factories: ExpressFactoryItem<any>[] = []
+
+  private _app: express.Express = express()
+  private _docs: RPCHttpRouteDoc[] = []
+
+  get app(): express.Express {
+    return this._app
+  }
+
+  get docs(): RPCHttpRouteDoc[] {
+    return this._docs
+  }
+
+  /**
+   * Registers a procedure factory with its context resolver.
+   * @param factory
+   * @param contextResolver
+   */
+  register<TFactory extends ProceduresFactory>(
+    factory: TFactory,
+    contextResolver: (req: express.Request) => ExtractContext<TFactory>
+  ): this {
+    this.factories.push({ factory, contextResolver } as ExpressFactoryItem<any>)
+    return this
+  }
+
+  /**
+   * Builds and returns the Express application with registered RPC routes.
+   * @return express.Application
+   */
+  build(): express.Application {
+    this.factories.forEach(({ factory, contextResolver }) => {
+      factory.getProcedures().map((procedure: TProcedureRegistration<any, RPCConfig>) => {
+        const route = this.buildRpcHttpRouteDoc(procedure)
+
+        this._docs.push(route)
+
+        this._app[route.method](route.path, async (req, res) => {
+          try {
+            res.json(await procedure.handler(contextResolver(req), req.body))
+            if (this.config?.onSuccess) {
+              this.config.onSuccess(procedure, req, res)
+            }
+            // if status not set, set to 200
+            if (!res.status) {
+              res.status(200)
+            }
+          } catch (error) {
+            if (this.config?.error) {
+              this.config.error(procedure, req, res, error as Error)
+              return
+            }
+            if (!res.status) {
+              res.status(500)
+            }
+            // if no res.json set, set default error message
+            if (!res.headersSent) {
+              res.json({ error: (error as Error).message })
+            }
+          }
+        })
+      })
+    })
+
+    return this._app
+  }
+
+  /**
+   * Generates the RPC HTTP route for the given procedure.
+   * @param procedure
+   */
+  buildRpcHttpRouteDoc(procedure: TProcedureRegistration<any, RPCConfig>): RPCHttpRouteDoc {
+    const { config } = procedure
+    const path = this.makeRPCHttpRoutePath(config)
+    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,
+    }
+  }
+
+  /**
+   * 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: /rpc/string/string-string/string/version
+   * @param config
+   */
+  makeRPCHttpRoutePath(config: RPCConfig) {
+    return `/rpc/${castArray(config.name).map(kebabCase).join('/')}/${String(config.version).trim()}`
+  }
+}

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

@@ -0,0 +1,29 @@
+import { RPCConfig } from '../../types.js'
+import { Procedures } from '../../../index.js'
+import express from 'express'
+
+/**
+ * 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 ExpressFactoryItem<TFactory = ReturnType<typeof Procedures<any, RPCConfig>>> = {
+  factory: TFactory
+  contextResolver: (req: express.Request) => ExtractContext<TFactory>
+}

package/src/implementations/types.ts

@@ -0,0 +1,20 @@
+import { Procedures } from '../index.js'
+
+export interface RPCConfig {
+  name: string | string[]
+  version: number
+}
+
+export type FactoryItem<C> = {
+  factory: ReturnType<typeof Procedures<C, RPCConfig>>
+  contextResolver: (req: Request) => C
+}
+
+export interface RPCHttpRouteDoc {
+  path: string
+  method: 'post'
+  jsonSchema: {
+    body?: object
+    response?: object
+  }
+}

package/src/schema/parser.ts

@@ -1,4 +1,4 @@
-import {default as addFormats} from 'ajv-formats'
+import { default as addFormats } from 'ajv-formats'
 import * as AJV from 'ajv'
 import { extractJsonSchema } from './extract-json-schema.js'
 import { TJSONSchema } from './types.js'
@@ -10,18 +10,19 @@ export type TSchemaParsed = {
 
 export type TSchemaValidationError = AJV.ErrorObject
 
-// @ts-ignore
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-expect-error
 const ajv = addFormats(
   new AJV.Ajv({
     allErrors: true,
     coerceTypes: true,
     removeAdditional: true,
-  }),
+  })
 )
 
 export function schemaParser(
   schema: { params?: unknown; returnType?: unknown },
-  onParseError: (errors: { params?: string; returnType?: string }) => void,
+  onParseError: (errors: { params?: string; returnType?: string }) => void
 ): TSchemaParsed {
   const jsonSchema: TSchemaParsed['jsonSchema'] = {}
   const validation: TSchemaParsed['validation'] = {}

package/src/schema/types.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/ban-types */
 import { CoreValidator, TypeOf } from 'suretype'
 import { Static, TSchema } from 'typebox'
 

package/src/implementations/http/express/README.md

@@ -1,351 +0,0 @@
-# Express Integration Guide
-
-## Overview
-
-`registerExpressRoutes` is a utility function that simplifies setting up an Express server with ts-procedures. It handles:
-
-- **Automatic parameter merging** - Combines path params (`:id`), query params, and body into a single `params` object
-- **Schema validation** - Validates merged params against your procedure's schema
-- **Error handling** - Provides hooks for custom error responses
-- **Context injection** - Creates procedure context from Express request/response
-
-## Quick Start
-
-```typescript
-import express from 'express'
-import { Procedures } from 'ts-procedures'
-import { registerExpressRoutes } from 'ts-procedures/express'
-import { Type } from 'typebox'
-
-// Define extended config for HTTP routes
-interface HTTPRouteConfig {
-  path: string
-  method: 'get' | 'post' | 'put' | 'delete' | 'patch'
-}
-
-// Create factory with route config
-const { Create, getProcedures } = Procedures<{}, HTTPRouteConfig>()
-
-// Define a procedure
-Create('GetUser', {
-  path: '/users/:id',
-  method: 'get',
-  schema: {
-    params: Type.Object({ id: Type.String() }),
-    returnType: Type.Object({ id: Type.String(), name: Type.String() })
-  }
-}, async (ctx, params) => {
-  return { id: params.id, name: 'John Doe' }
-})
-
-// Register routes
-const app = express()
-app.use(express.json())
-
-registerExpressRoutes(
-  app,
-  { getContext: async (req, res) => ({}) },
-  getProcedures()
-)
-
-app.listen(3000)
-```
-
-## Architecture Pattern
-
-### Public vs Protected Factories
-
-A common pattern is to separate procedures that require authentication from public endpoints:
-
-```typescript
-// factories.ts
-import { Procedures } from 'ts-procedures'
-
-export interface ProceduresContext {
-  headers: Record<string, string>
-  ipAddress: string
-  requestId: string
-}
-
-export interface ProtectedContext extends ProceduresContext {
-  userId: string  // Required - user must be authenticated
-}
-
-export interface PublicContext extends ProceduresContext {
-  userId?: undefined  // Optional - may or may not be authenticated
-}
-
-export interface HTTPRouteConfig {
-  path: string
-  method: 'get' | 'post' | 'put' | 'delete' | 'patch'
-}
-
-export const ProtectedFactory = Procedures<ProtectedContext, HTTPRouteConfig>()
-export const PublicFactory = Procedures<PublicContext, HTTPRouteConfig>()
-```
-
-### File Organization
-
-```
-src/
-├── factories.ts           # Context interfaces and factory setup
-├── procedures/
-│   ├── auth.ts            # Public endpoints (login, register)
-│   └── users.ts           # Protected endpoints (profile, settings)
-└── server.ts              # Express app and route registration
-```
-
-## Complete Example
-
-### factories.ts
-
-```typescript
-import { Procedures } from 'ts-procedures'
-
-export interface ProceduresContext {
-  headers: Record<string, string>
-  ipAddress: string
-  requestId: string
-}
-
-export interface ProtectedContext extends ProceduresContext {
-  userId: string
-}
-
-export interface PublicContext extends ProceduresContext {
-  userId?: undefined
-}
-
-export interface HTTPRouteConfig {
-  path: string
-  method: 'get' | 'post' | 'put' | 'delete' | 'patch'
-}
-
-export const ProtectedFactory = Procedures<ProtectedContext, HTTPRouteConfig>()
-export const PublicFactory = Procedures<PublicContext, HTTPRouteConfig>()
-```
-
-### procedures/auth.ts
-
-```typescript
-import { PublicFactory } from '../factories.js'
-import { Type } from 'typebox'
-
-PublicFactory.Create('Authenticate', {
-  path: '/authenticate',
-  method: 'post',
-  schema: {
-    params: Type.Object({
-      username: Type.String({ minLength: 3 }),
-      password: Type.String({ minLength: 6 }),
-    }),
-    returnType: Type.Object({
-      token: Type.String(),
-    })
-  },
-  description: 'Authenticate as a user and obtain a token',
-}, async (ctx, params) => {
-  // Verify credentials and return token
-  return { token: 'jwt-token-here' }
-})
-```
-
-### procedures/users.ts
-
-```typescript
-import { ProtectedFactory } from '../factories.js'
-import { Type } from 'typebox'
-
-ProtectedFactory.Create('GetUserProfile', {
-  path: '/users/user-profile/:id',
-  method: 'get',
-  schema: {
-    params: Type.Object({
-      id: Type.String(),  // Mapped from :id in path
-    }),
-    returnType: Type.Object({
-      user: Type.Object({
-        id: Type.String(),
-        name: Type.String(),
-        email: Type.String(),
-      }),
-    })
-  },
-  description: 'Get the profile of a specific user',
-}, async (ctx, params) => {
-  // ctx.userId is guaranteed to exist (ProtectedContext)
-  return {
-    user: {
-      id: params.id,
-      name: 'Jane Doe',
-      email: 'jane@example.com'
-    }
-  }
-})
-```
-
-### server.ts
-
-```typescript
-import express from 'express'
-import { PublicFactory, ProtectedFactory } from './factories.js'
-import { registerExpressRoutes } from 'ts-procedures/express'
-
-// Import procedures for side effects (registers with factories)
-import './procedures/auth.js'
-import './procedures/users.js'
-
-const app = express()
-app.use(express.json())
-
-// Register public routes (no auth required)
-registerExpressRoutes(
-  app,
-  {
-    getContext: async (req, res) => ({
-      ipAddress: req.ip || '',
-      requestId: req.headers['x-request-id']?.toString() || crypto.randomUUID(),
-      headers: req.headers as Record<string, string>,
-    })
-  },
-  PublicFactory.getProcedures()
-)
-
-// Register protected routes (auth required)
-registerExpressRoutes(
-  app,
-  {
-    getContext: async (req, res) => {
-      const token = req.headers['authorization']?.replace('Bearer ', '')
-      const user = await validateToken(token)  // Your auth logic
-
-      if (!user) {
-        res.status(401).json({ error: 'Unauthorized' })
-        throw new Error('Unauthorized')
-      }
-
-      return {
-        userId: user.id,
-        ipAddress: req.ip || '',
-        requestId: req.headers['x-request-id']?.toString() || crypto.randomUUID(),
-        headers: req.headers as Record<string, string>,
-      }
-    }
-  },
-  ProtectedFactory.getProcedures()
-)
-
-app.listen(3000)
-```
-
-## API Reference
-
-```typescript
-registerExpressRoutes<ProceduresContext>(
-  app: express.Application,
-  callbacks: {
-    /** Create procedure context from Express request */
-    getContext: (req: express.Request, res: express.Response) => Promise<ProceduresContext>
-
-    /** Optional handler for procedure errors (default: 500 with error message) */
-    onHandlerError?: (error: Error, req: express.Request, res: express.Response) => void
-
-    /** Optional handler for validation errors (default: 422 with error details) */
-    onValidationError?: (
-      errors: Array<{ message: string; path: string[] }>,
-      req: express.Request,
-      res: express.Response
-    ) => void
-  },
-  procedures: Array<TProcedureRegistration<ProceduresContext, HTTPRouteConfig>>
-): void
-```
-
-## Features
-
-### Path Parameter Mapping
-
-Path parameters defined with `:paramName` are automatically extracted and merged into the params object:
-
-```typescript
-// Route: /users/:id/posts/:postId
-// URL: /users/123/posts/456
-// Params: { id: '123', postId: '456' }
-```
-
-### Parameter Merging
-
-Parameters are merged in this order (later sources override earlier):
-
-1. Path parameters (`:id`)
-2. Query parameters (`?foo=bar`)
-3. Body parameters (JSON body)
-
-### Schema Validation
-
-When validation fails, the default behavior returns a 422 response:
-
-```json
-{
-  "error": "Validation Error",
-  "details": [
-    { "message": "must be string", "path": ["username"] }
-  ]
-}
-```
-
-### Custom Error Handlers
-
-```typescript
-registerExpressRoutes(
-  app,
-  {
-    getContext: async (req, res) => ({}),
-
-    onValidationError: (errors, req, res) => {
-      res.status(400).json({
-        code: 'INVALID_INPUT',
-        errors: errors.map(e => e.message)
-      })
-    },
-
-    onHandlerError: (error, req, res) => {
-      if (error instanceof ProcedureError) {
-        res.status(error.code || 500).json({ message: error.message })
-      } else {
-        res.status(500).json({ message: 'Internal Server Error' })
-      }
-    }
-  },
-  getProcedures()
-)
-```
-
-### Authentication Pattern
-
-The `getContext` callback is the ideal place to handle authentication:
-
-```typescript
-getContext: async (req, res) => {
-  const token = req.headers['authorization']
-
-  if (!token) {
-    res.status(401).json({ error: 'No token provided' })
-    throw new Error('Unauthorized')
-  }
-
-  const user = await verifyToken(token)
-
-  if (!user) {
-    res.status(401).json({ error: 'Invalid token' })
-    throw new Error('Unauthorized')
-  }
-
-  return {
-    userId: user.id,
-    // ... other context
-  }
-}
-```
-
-When `getContext` throws, the route handler stops execution. This allows you to respond with an error and prevent the procedure from running.

package/src/implementations/http/express/example/factories.ts

@@ -1,25 +0,0 @@
-import { Procedures } from '../../../../index.js'
-
-export interface ProceduresContext {
-  headers: Record<string, string>
-  ipAddress: string
-  requestId: string
-}
-
-export interface ProtectedContext extends ProceduresContext {
-  userId: string
-}
-
-export interface PublicContext extends ProceduresContext {
-  // An authenticated client can call public endpoints so userId is optional
-  userId?: undefined
-}
-
-export const ProtectedFactory = Procedures<ProtectedContext,HTTPRouteConfig>()
-
-export const PublicFactory = Procedures<PublicContext,HTTPRouteConfig>()
-
-export interface HTTPRouteConfig {
-  path: string
-  method: 'get' | 'post' | 'put' | 'delete' | 'patch'
-}

package/src/implementations/http/express/example/procedures/auth.ts

@@ -1,24 +0,0 @@
-import { PublicFactory } from '../factories.js'
-import { Type } from 'typebox'
-
-PublicFactory.Create('Authenticate', {
-  path: '/authenticate',
-  method: 'post',
-  schema: {
-    params: Type.Object({
-      username: Type.String({ minLength: 3 }),
-      password: Type.String({ minLength: 6  }),
-    }),
-    returnType: Type.Object({
-      token: Type.String(),
-    })
-  },
-  description: 'Authenticate as a user and obtain a token',
-  },
-  async (ctx, params) => {
-    // In a real implementation, you would verify user credentials here, ie: ctx.services.userService.authenticate(params.username, params.password)
-
-    return {
-      token: 'fake-jwt-token',
-    }
-})

package/src/implementations/http/express/example/procedures/users.ts

@@ -1,32 +0,0 @@
-import { ProtectedFactory } from '../factories.js'
-import { Type } from 'typebox'
-
-ProtectedFactory.Create('Get User Profile', {
-  path: '/users/user-profile/:id',
-  method: 'get',
-  schema: {
-    params: Type.Object({
-      // Our router in this example will map :id to this param
-      id: Type.String(),
-    }),
-    returnType: Type.Object({
-      user: Type.Object({
-        id: Type.String(),
-        name: Type.String(),
-        email: Type.String(),
-      }),
-    })
-  },
-  description: 'Get the profile of a specific user',
-  },
-  async (ctx, params) => {
-    // In a real implementation, you would fetch the user profile from a database or service here, ie: ctx.services.userService.getUserProfile(params.userId)
-
-    return {
-      user: {
-        id: params.id,
-        name: 'Jane Doe',
-        email: 'test@gmail.com'
-      },
-    }
-})