ts-procedures 1.0.0 → 1.1.1

package/build/schema/parser.test.js

@@ -0,0 +1,102 @@
+import { describe, expect, test } from 'vitest';
+import { extractSingleJsonSchema, v } from 'suretype';
+import { schemaParser } from './parser.js';
+import { Type } from 'typebox';
+describe('schemaParser', () => {
+    test('it parses params to json-schema', async () => {
+        let done = () => void 0;
+        const promise = new Promise((r) => {
+            done = r;
+        });
+        const params = v.object({
+            name: v.string(),
+            age: v.number(),
+        });
+        const result = schemaParser({
+            params: params,
+        }, (errors) => {
+            throw new Error(JSON.stringify(errors));
+        });
+        expect(result.jsonSchema.params).toEqual(extractSingleJsonSchema(params)?.schema);
+        done();
+        await promise;
+        await promise;
+    });
+    test('it parses params and generates a validator function', async () => {
+        let done = () => void 0;
+        const promise = new Promise((r) => {
+            done = r;
+        });
+        const params = v.object({
+            name: v.string(),
+            age: v.number().required(),
+        });
+        const result = schemaParser({
+            params: params,
+        }, (errors) => {
+            throw new Error(JSON.stringify(errors));
+        });
+        expect(result.validation.params?.({
+            name: 'John',
+            age: 30,
+        })?.errors).toBeUndefined();
+        expect(result.validation.params?.({
+            name: { name: '' },
+            age: 'poop',
+        })?.errors).toBeDefined();
+        expect(result.validation.params?.({
+            name: { name: '' },
+            age: 'poop',
+        })?.errors?.length).toEqual(2);
+        done();
+        await promise;
+    });
+    test('it parses returnType to json-schema', async () => {
+        let done = () => void 0;
+        const promise = new Promise((r) => {
+            done = r;
+        });
+        const returnType = v.object({
+            name: v.string(),
+            age: v.number(),
+        });
+        const result = schemaParser({
+            returnType: returnType,
+        }, (errors) => {
+            throw new Error(JSON.stringify(errors));
+        });
+        expect(result.jsonSchema.returnType).toEqual(extractSingleJsonSchema(returnType)?.schema);
+        done();
+        await promise;
+    });
+    test('it throws a meaningful error to the dev', async () => {
+        schemaParser(
+        // invalid params schema
+        { params: { test: Type.String() } }, (errors) => {
+            expect(errors.params).toMatch(/Error extracting json schema schema.params/);
+        });
+        schemaParser(
+        // invalid returnType schema
+        { returnType: 'string value' }, (errors) => {
+            expect(errors.returnType).toMatch(/Error extracting json schema schema.returnType/);
+        });
+    });
+    test('it parses multiple schemas correct', async () => {
+        const schema = schemaParser({
+            params: Type.Object({ a: Type.String() }),
+            returnType: Type.Object({ b: Type.Null() }),
+        }, (error) => {
+            throw new Error(JSON.stringify(error));
+        });
+        const schema2 = schemaParser({
+            params: Type.Object({ c: Type.String() }),
+            returnType: Type.Object({ d: Type.Number() }),
+        }, (error) => {
+            throw new Error(JSON.stringify(error));
+        });
+        expect(schema.validation.params?.({}).errors?.[0]?.message).toMatch(/must have required property 'a'/);
+        expect(schema2.validation.params?.({ c: 'test' })).toMatchObject({});
+        expect(schema.validation.params?.({}).errors?.[0]?.message).toMatch(/must have required property 'a'/);
+    });
+});
+//# sourceMappingURL=parser.test.js.map

package/build/schema/parser.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.test.js","sourceRoot":"","sources":["../../src/schema/parser.test.ts"],"names":[],"mappings":"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"}

package/build/schema/resolve-schema-lib.d.ts

@@ -0,0 +1,12 @@
+import { CoreValidator } from 'suretype';
+import { Type } from 'typebox';
+export type IsTypeboxSchema<TSchema> = TSchema extends {
+    static: unknown;
+    params: unknown;
+} ? true : false;
+export declare function isTypeboxSchema(schema: any): schema is Type.TSchema;
+export type IsSuretypeSchema<TSchema> = TSchema extends {
+    required: () => object;
+    nullable?: never;
+} ? true : false;
+export declare function isSuretypeSchema(schema: any): schema is CoreValidator<any>;

package/build/schema/resolve-schema-lib.js

@@ -0,0 +1,11 @@
+export function isTypeboxSchema(schema) {
+    return (
+    //  typebox v1
+    (typeof schema === 'object' && '~kind' in schema) ||
+        // @sinclair/typebox v0.3x
+        (typeof schema === 'object' && Symbol.for('TypeBox.Kind') in schema));
+}
+export function isSuretypeSchema(schema) {
+    return typeof schema === 'object' && 'getJsonSchemaObject' in schema;
+}
+//# sourceMappingURL=resolve-schema-lib.js.map

package/build/schema/resolve-schema-lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-schema-lib.js","sourceRoot":"","sources":["../../src/schema/resolve-schema-lib.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,eAAe,CAAC,MAAW;IACzC,OAAO;IACL,cAAc;IACd,CAAC,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,IAAI,MAAM,CAAC;QACjD,0BAA0B;QAC1B,CAAC,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,MAAM,CAAC,CACrE,CAAA;AACH,CAAC;AASD,MAAM,UAAU,gBAAgB,CAAC,MAAW;IAC1C,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,qBAAqB,IAAI,MAAM,CAAA;AACtE,CAAC"}

package/build/schema/resolve-schema-lib.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/schema/resolve-schema-lib.test.js

@@ -0,0 +1,17 @@
+import { describe, expect, test } from 'vitest';
+import { isSuretypeSchema, isTypeboxSchema } from './resolve-schema-lib.js';
+import { Type } from 'typebox';
+import { v } from 'suretype';
+describe('lib schema resolvers', () => {
+    const typebox = Type.Object({ name: Type.String() });
+    const suretype = v.object({ name: v.string() });
+    test('it recognizes TypeBox schema', async () => {
+        expect(isTypeboxSchema(typebox)).toBe(true);
+        expect(isTypeboxSchema(suretype)).toBe(false);
+    });
+    test('it recognizes Suretype schema', async () => {
+        expect(isSuretypeSchema(suretype)).toBe(true);
+        expect(isSuretypeSchema(typebox)).toBe(false);
+    });
+});
+//# sourceMappingURL=resolve-schema-lib.test.js.map

package/build/schema/resolve-schema-lib.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-schema-lib.test.js","sourceRoot":"","sources":["../../src/schema/resolve-schema-lib.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC3E,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAC9B,OAAO,EAAE,CAAC,EAAE,MAAM,UAAU,CAAA;AAE5B,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACpD,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAE/C,IAAI,CAAC,8BAA8B,EAAE,KAAK,IAAI,EAAE;QAC9C,MAAM,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC3C,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAC/C,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,+BAA+B,EAAE,KAAK,IAAI,EAAE;QAC/C,MAAM,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC7C,MAAM,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAC/C,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/build/schema/types.d.ts

@@ -0,0 +1,7 @@
+import { CoreValidator, TypeOf } from 'suretype';
+import { Static, TSchema } from 'typebox';
+export type TSchemaLib<SchemaLibType> = SchemaLibType extends CoreValidator<any> ? TypeOf<SchemaLibType> : SchemaLibType extends TSchema ? Static<SchemaLibType> : unknown;
+export type TJSONSchema = Record<string, any>;
+export type Prettify<TObject> = {
+    [Key in keyof TObject]: TObject[Key];
+} & {};

package/build/schema/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/schema/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/schema/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,27 +1,32 @@
 {
   "name": "ts-procedures",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "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",
+  "main": "build/exports.js",
+  "types": "build/exports.d.ts",
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/exports.d.ts",
-      "import": "./dist/exports.js"
+      "types": "./build/exports.d.ts",
+      "import": "./build/exports.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./express": {
+      "types": "./build/implementations/http/express/index.d.ts",
+      "import": "./build/implementations/http/express/index.js"
+    }
   },
   "scripts": {
     "build": "tsc",
     "lint": "npx eslint src/ --quiet",
+    "prepublishOnly": "npm run lint && npm run build",
     "test": "vitest run"
   },
   "author": "coryrobinson42@gmail.com",
   "license": "MIT",
   "files": [
     "assets",
-    "dist",
+    "build",
     "src"
   ],
   "keywords": [
@@ -33,15 +38,23 @@
     "api",
     "framework"
   ],
+  "optionalDependencies": {
+    "express": "^5.2.1"
+  },
   "dependencies": {
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
-    "typebox": "^1.0.30",
-    "suretype": "^3.3.1"
+    "suretype": "^3.3.1",
+    "typebox": "^1.0.30"
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
+    "@types/express": "^5.0.6",
+    "@types/supertest": "^6.0.3",
     "eslint": "^9.17.0",
+    "express": "^5.2.1",
+    "prettier": "^3.8.1",
+    "supertest": "^7.2.2",
     "suretype": "^3.3.1",
     "typebox": "^1.0.77",
     "typescript-eslint": "^8.53.0",

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

@@ -0,0 +1,351 @@
+# 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

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,24 @@
+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

@@ -0,0 +1,32 @@
+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'
+      },
+    }
+})