ts-procedures 1.0.0

package/README.md

@@ -0,0 +1,459 @@
+# ts-procedures
+
+A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation and procedure documentation/configuration.
+
+## Installation
+
+```bash
+npm install ts-procedures
+```
+
+## Quick Start
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { Type } from 'typebox'
+
+// Create a procedures factory
+const { Create } = Procedures()
+
+// Define a procedure with schema validation
+const { GetUser, procedure, info } = Create(
+  'GetUser',
+  {
+    description: 'Fetches a user by ID',
+    schema: {
+      params: Type.Object({ userId: Type.String() }),
+      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+    },
+  },
+  async (ctx, params /* typed as { userId: string } */) => {
+    
+    // returnType is inferred as { id: string; name: string }
+    return { id: params.userId, name: 'John Doe' }
+  },
+)
+
+// Call the procedure directly
+const user = await GetUser({}, { userId: '123' })
+// Or use the generic reference
+const user2 = await procedure({}, { userId: '456' })
+```
+
+## Core Concepts
+
+### Procedures Factory
+
+The `Procedures()` function creates a factory for defining procedures. It accepts two generic type parameters:
+
+```typescript
+Procedures<TContext, TExtendedConfig>(builder?: {
+    onCreate?: (procedure: TProcedureRegistration<TContext, TExtendedConfig>) => void
+})
+```
+
+| Parameter | Description                                                                |
+|-----------|----------------------------------------------------------------------------|
+| `TContext` | The base context type passed to all handlers as the first parameter        |
+| `TExtendedConfig` | Additional configuration properties for all procedures `config` properties |
+| `builder.onCreate` | Optional callback invoked when each procedure is registered (runtime)      |
+
+### Create Function
+
+The `Create` function defines individual procedures:
+
+```typescript
+Create(name, config, handler)
+```
+
+**Returns:**
+- `{ [name]: handler }` - Named export for the handler
+- `procedure` - Generic reference to the handler
+- `info` - Procedure meta (name, description, schema, `TExtendedConfig` properties, etc.)
+
+## Using Generics
+
+### Base Context
+
+Define a shared context type for all procedures in your application:
+
+```typescript
+interface AppContext {
+  authToken: string
+  requestId: string
+  logger: Logger
+}
+
+const { Create } = Procedures<AppContext>()
+
+const { SecureEndpoint } = Create(
+  'SecureEndpoint',
+  {},
+  async (ctx, params) => {
+    // ctx.authToken is typed as string
+    // ctx.requestId is typed as string
+    // ctx.logger is typed as Logger
+    return { token: ctx.authToken }
+  },
+)
+
+// When calling, you must provide the context
+await SecureEndpoint({ authToken: 'abc', requestId: '123', logger: myLogger }, {})
+```
+
+### Extended Configuration
+
+Add custom properties to all procedure configs:
+
+```typescript
+interface ExtendedConfig {
+  permissions: string[]
+  rateLimit?: number
+  cacheTTL?: number
+}
+
+const { Create } = Procedures<AppContext, ExtendedConfig>()
+
+const { AdminOnly } = Create(
+  'AdminOnly',
+  {
+    permissions: ['admin'],  // Required by ExtendedConfig
+    rateLimit: 100,          // Optional
+    description: 'Admin-only endpoint',
+  },
+  async (ctx, params) => {
+    return { admin: true }
+  },
+)
+
+// Access extended config via info
+console.log(AdminOnly.info.permissions) // ['admin']
+```
+
+### Combined Example
+
+```typescript
+interface CustomContext {
+  authToken: string
+  tenantId: string
+}
+
+interface ExtendedConfig {
+  requiresAuth: boolean
+  auditLog?: boolean
+}
+
+const { Create, getProcedures } = Procedures<CustomContext, ExtendedConfig>({
+  onCreate: (procedure) => {
+    // Register with your framework
+    console.log(`Registered: ${procedure.name}`)
+    console.log(`Requires Auth: ${procedure.config.requiresAuth}`)
+  },
+})
+
+const { CreateUser } = Create(
+  'CreateUser',
+  {
+    requiresAuth: true,
+    auditLog: true,
+    description: 'Creates a new user',
+    schema: {
+      params: Type.Object({
+        email: Type.String(),
+        name: Type.String(),
+      }),
+      returnType: Type.Object({ id: Type.String() }),
+    },
+  },
+  async (ctx, params) => {
+    // Both context and params are fully typed
+    return { id: 'user-123' }
+  },
+)
+```
+
+## Schema Validation
+
+### Suretype
+
+```typescript
+import { v } from 'suretype'
+
+Create(
+  'CreatePost',
+  {
+    schema: {
+      params: Type.Object({
+        title: Type.String(),
+        content: Type.String(),
+        tags: Type.array(Type.String()),
+      }),
+      returnType: Type.Object({
+        id: Type.String(),
+        createdAt: Type.String(),
+      }),
+    },
+  },
+  async (ctx, params) => {
+    // params typed as { title: string, content: string, tags?: string[] }
+    return { id: '1', createdAt: new Date().toISOString() }
+  },
+)
+```
+
+### TypeBox
+
+```typescript
+import { Type } from 'typebox'
+
+Create(
+  'CreatePost',
+  {
+    schema: {
+      params: Type.Object({
+        title: Type.String(),
+        content: Type.String(),
+        tags: Type.Optional(Type.Array(Type.String())),
+      }),
+      returnType: Type.Object({
+        id: Type.String(),
+        createdAt: Type.String(),
+      }),
+    },
+  },
+  async (ctx, params) => {
+    // params typed as { title: string, content: string, tags?: string[] }
+    return { id: '1', createdAt: new Date().toISOString() }
+  },
+)
+```
+
+### Validation Behavior
+
+AJV is configured with:
+- `allErrors: true` - Report all validation errors
+- `coerceTypes: true` - Automatically coerce types when possible
+- `removeAdditional: true` - Strip properties not in schema
+
+**Note:** `schema.params` is validated at runtime. `schema.returnType` is for documentation/introspection only.
+
+## Error Handling
+
+### Using ctx.error()
+
+The `error()` function is injected into both hooks and handlers:
+
+```typescript
+Create(
+  'GetResource',
+  {},
+  async (ctx, params) => {
+    const resource = await db.find(params.id)
+    if (!resource) {
+      throw ctx.error(404, 'Resource not found', { id: params.id })
+    }
+    return resource
+  },
+)
+```
+
+### Error Handling
+
+| Error Class | Trigger |
+|-------------|---------|
+| ProcedureError | `ctx.error()` in handlers |
+| ProcedureValidationError | Schema validation failure |
+| ProcedureRegistrationError | Invalid schema at registration |
+
+### Error Properties
+
+```typescript
+try {
+  await MyProcedure(ctx, params)
+} catch (e) {
+  if (e instanceof ProcedureError) {
+    console.log(e.procedureName) // 'MyProcedure'
+    console.log(e.message)       // 'Resource not found'
+    console.log(e.meta)          // { id: '123' }
+  }
+}
+```
+
+## Framework Integration
+
+### onCreate Callback
+
+Register procedures with your framework (Express, Fastify, etc.):
+
+```typescript
+import express from 'express'
+
+const app = express()
+const routes: Map<string, Function> = new Map()
+
+const { Create } = Procedures<{ req: Request; res: Response }>({
+  onCreate: ({ name, handler, config }) => {
+    // Register as Express route
+    app.post(`/rpc/${name}`, async (req, res) => {
+      try {
+        const result = await handler({ req, res }, req.body)
+        res.json(result)
+      } catch (e) {
+        if (e instanceof ProcedureError) {
+          res.status(500).json({ error: e.message })
+        } else {
+          res.status(500).json({ error: 'Internal error' })
+        }
+      }
+    })
+  },
+})
+
+// Procedures are automatically registered as /rpc/GetUser, /rpc/CreateUser, etc.
+```
+
+### Introspection with getProcedures()
+
+Access all registered procedures for documentation or routing:
+
+```typescript
+const { Create, getProcedures } = Procedures()
+
+Create('GetUser', { schema: { params: Type.Object({ id: Type.String() }) } }, async () => {})
+Create('ListUsers', { schema: { params: Type.Object({}) } }, async () => {})
+
+// Get all registered procedures
+const procedures = getProcedures()
+
+// Generate OpenAPI spec
+for (const [name, { config }] of procedures) {
+  console.log(`${name}:`, config.schema)
+}
+```
+
+## Testing
+
+Procedures return handlers that can be called directly in tests:
+
+```typescript
+import { describe, test, expect } from 'vitest'
+import { Procedures } from 'ts-procedures'
+import { Type } from 'typebox'
+
+interface MyCustomContext {
+  userId?: string
+  userName?: string
+}
+
+const { Create } = Procedures<MyCustomContext>()
+
+const { GetUser, info } = Create(
+  'GetUser',
+  {
+    schema: {
+      params: Type.Object({ hideName: Type.Optional(Type.Boolean()) }),
+      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+    },
+  },
+  async (ctx, params) => {
+    if (!params.userName || !ctx.userId) {
+      throw ctx.error('User is not authenticated')
+    }
+    
+    return { 
+      id: params.userId, 
+      name: params?.hideName ? '*******' : params.userName 
+    }
+  },
+)
+
+describe('GetUser', () => {
+  test('returns user', async () => {
+    const result = await GetUser({userId:'123',userName:'Ray'}, { hideName: false })
+    expect(result).toEqual({ id: '123', name: 'Ray' })
+  })
+  
+  test('hides user name', async () => {
+    const result = await GetUser({userId:'123',userName:'Ray'}, { hideName: true })
+    expect(result).toEqual({ id: '123', name: '*******' })
+  })
+
+  test('validates params', async () => {
+    await expect(GetUser({}, {})).rejects.toThrow(ProcedureValidationError)
+  })
+
+  test('has correct schema', () => {
+    expect(info.schema.params).toEqual({
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+    })
+  })
+})
+```
+
+## API Reference
+
+### Procedures(builder?)
+
+Creates a procedure factory.
+
+**Parameters:**
+- `builder.onCreate` - Callback invoked when each procedure is registered
+
+**Returns:**
+- `Create` - Function to define procedures
+- `getProcedures()` - Returns `Map` of all registered procedures
+
+### Create(name, config, handler)
+
+Defines a procedure.
+
+**Parameters:**
+- `name` - Unique procedure name (becomes named export)
+- `config.description` - Optional description
+- `config.schema.params` - Suretype or TypeBox schema for params (validated at runtime)
+- `config.schema.returnType` - Suretype or TypeBox schema for return returnType (documentation only)
+- Additional properties from `TExtendedConfig`
+- `handler` - Async function `(ctx, params) => Promise<returnType>`
+
+**Returns:**
+- `{ [name]: handler }` - Named handler export
+- `procedure` - Generic handler reference
+- `info` - Procedure metareturnType
+
+### Type Exports
+
+```typescript
+import {
+  // Core
+  Procedures,
+
+  // Errors
+  ProcedureError,
+  ProcedureValidationError,
+  ProcedureRegistrationError,
+  
+  // Types
+  TLocalContext,
+  TProcedureRegistration,
+  TNoContextProvided,
+
+  // Schema utilities
+  extractJsonSchema,
+  schemaParser,
+  isTypeboxSchema,
+  isSuretypeSchema,
+
+  // Schema types
+  TJSONSchema,
+  TSchemaLib,
+  TSchemaParsed,
+  TSchemaValidationError,
+  Prettify,
+} from 'ts-procedures'
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "ts-procedures",
+  "version": "1.0.0",
+  "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
+  "main": "dist/exports.js",
+  "types": "dist/exports.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/exports.d.ts",
+      "import": "./dist/exports.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "npx eslint src/ --quiet",
+    "test": "vitest run"
+  },
+  "author": "coryrobinson42@gmail.com",
+  "license": "MIT",
+  "files": [
+    "assets",
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "typescript",
+    "rpc",
+    "type-safe",
+    "validation",
+    "procedures",
+    "api",
+    "framework"
+  ],
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "typebox": "^1.0.30",
+    "suretype": "^3.3.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "eslint": "^9.17.0",
+    "suretype": "^3.3.1",
+    "typebox": "^1.0.77",
+    "typescript-eslint": "^8.53.0",
+    "vitest": "^4.0.18"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,39 @@
+import { TSchemaValidationError } from './schema/parser.js'
+
+export class ProcedureError extends Error {
+  constructor(
+    readonly procedureName: string,
+    readonly message: string,
+    readonly meta?: object,
+  ) {
+    super(message)
+    this.name = 'ProcedureError'
+
+    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
+    Object.setPrototypeOf(this, ProcedureError.prototype)
+  }
+}
+
+export class ProcedureValidationError extends ProcedureError {
+  constructor(
+    readonly procedureName: string,
+    message: string,
+    readonly errors?: TSchemaValidationError[],
+  ) {
+    super(procedureName, message)
+    this.name = 'ProcedureValidationError'
+
+    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
+    Object.setPrototypeOf(this, ProcedureValidationError.prototype)
+  }
+}
+
+export class ProcedureRegistrationError extends Error {
+  constructor(readonly procedureName: string, message: string) {
+    super(message)
+    this.name = 'ProcedureRegistrationError'
+
+    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
+    Object.setPrototypeOf(this, ProcedureRegistrationError.prototype)
+  }
+}

package/src/exports.ts

@@ -0,0 +1,6 @@
+export * from './index.js'
+export * from './errors.js'
+export * from './schema/extract-json-schema.js'
+export * from './schema/parser.js'
+export * from './schema/resolve-schema-lib.js'
+export * from './schema/types.js'