ts-procedures 1.0.0 → 1.1.0

package/src/implementations/http/express/index.test.ts

@@ -0,0 +1,526 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import supertest from 'supertest'
+import express, { Express } from 'express'
+import { registerExpressRoutes, mapPathParamsToObject } from './index.js'
+import { Procedures } from '../../../index.js'
+import { Type } from 'typebox'
+
+describe('mapPathParamsToObject', () => {
+  it('extracts single path param', () => {
+    const result = mapPathParamsToObject('/users/:id', '/users/123')
+    expect(result).toEqual({ id: '123' })
+  })
+
+  it('extracts multiple path params', () => {
+    const result = mapPathParamsToObject('/users/:userId/posts/:postId', '/users/42/posts/99')
+    expect(result).toEqual({ userId: '42', postId: '99' })
+  })
+
+  it('returns empty object when no params', () => {
+    const result = mapPathParamsToObject('/users', '/users')
+    expect(result).toEqual({})
+  })
+
+  it('handles trailing slashes', () => {
+    const result = mapPathParamsToObject('/users/:id/', '/users/123/')
+    expect(result).toEqual({ id: '123' })
+  })
+
+  it('handles missing segment with empty string', () => {
+    const result = mapPathParamsToObject('/users/:id/:name', '/users/123')
+    expect(result).toEqual({ id: '123', name: '' })
+  })
+
+  it('ignores query string in URL', () => {
+    const result = mapPathParamsToObject('/users/:id', '/users/123?foo=bar')
+    expect(result).toEqual({ id: '123' })
+  })
+
+  it('handles nested paths with params', () => {
+    const result = mapPathParamsToObject('/api/v1/users/:id/profile', '/api/v1/users/abc/profile')
+    expect(result).toEqual({ id: 'abc' })
+  })
+})
+
+describe('registerExpressRoutes', () => {
+  let app: Express
+
+  beforeEach(() => {
+    app = express()
+    app.use(express.json())
+  })
+
+  describe('Route Registration', () => {
+    it('registers GET route and returns JSON response', async () => {
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create('GetUsers', { method: 'get', path: '/users' }, async () => ({
+        users: ['alice', 'bob'],
+      }))
+
+      registerExpressRoutes(app, { getContext: async () => ({ user: 'test' }) }, getProcedures())
+
+      const response = await supertest(app).get('/users')
+      expect(response.status).toBe(200)
+      expect(response.body).toEqual({ users: ['alice', 'bob'] })
+    })
+
+    it('registers POST route and returns JSON response', async () => {
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create(
+        'CreateUser',
+        {
+          method: 'post',
+          path: '/users',
+          schema: {
+            params: Type.Object({ name: Type.Optional(Type.String()) }),
+          },
+        },
+        async (_ctx, params) => ({ created: true, name: params?.name })
+      )
+
+      registerExpressRoutes(app, { getContext: async () => ({ user: 'test' }) }, getProcedures())
+
+      const response = await supertest(app).post('/users').send({ name: 'charlie' })
+      expect(response.status).toBe(200)
+      expect(response.body).toEqual({ created: true, name: 'charlie' })
+    })
+
+    it('registers PUT route', async () => {
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create(
+        'UpdateUser',
+        {
+          method: 'put',
+          path: '/users/:id',
+          schema: {
+            params: Type.Object({ id: Type.Optional(Type.String()) }),
+          },
+        },
+        async (_ctx, params) => ({ updated: true, id: params?.id })
+      )
+
+      registerExpressRoutes(app, { getContext: async () => ({ user: 'test' }) }, getProcedures())
+
+      const response = await supertest(app).put('/users/123').send({ name: 'updated' })
+      expect(response.status).toBe(200)
+      expect(response.body).toEqual({ updated: true, id: '123' })
+    })
+
+    it('registers PATCH route', async () => {
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create(
+        'PatchUser',
+        {
+          method: 'patch',
+          path: '/users/:id',
+          schema: {
+            params: Type.Object({ id: Type.Optional(Type.String()) }),
+          },
+        },
+        async (_ctx, params) => ({ patched: true, id: params?.id })
+      )
+
+      registerExpressRoutes(app, { getContext: async () => ({ user: 'test' }) }, getProcedures())
+
+      const response = await supertest(app).patch('/users/456').send({ status: 'active' })
+      expect(response.status).toBe(200)
+      expect(response.body).toEqual({ patched: true, id: '456' })
+    })
+
+    it('registers DELETE route', async () => {
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create(
+        'DeleteUser',
+        {
+          method: 'delete',
+          path: '/users/:id',
+          schema: {
+            params: Type.Object({ id: Type.Optional(Type.String()) }),
+          },
+        },
+        async (_ctx, params) => ({ deleted: true, id: params?.id })
+      )
+
+      registerExpressRoutes(app, { getContext: async () => ({ user: 'test' }) }, getProcedures())
+
+      const response = await supertest(app).delete('/users/789')
+      expect(response.status).toBe(200)
+      expect(response.body).toEqual({ deleted: true, id: '789' })
+    })
+  })
+
+  describe('Parameter Handling', () => {
+    it('passes path params to handler', async () => {
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create(
+        'GetUser',
+        {
+          method: 'get',
+          path: '/users/:userId',
+          schema: {
+            params: Type.Object({ userId: Type.Optional(Type.String()) }),
+          },
+        },
+        async (_ctx, params) => ({ userId: params?.userId })
+      )
+
+      registerExpressRoutes(app, { getContext: async () => ({ user: 'test' }) }, getProcedures())
+
+      const response = await supertest(app).get('/users/abc123')
+      expect(response.body).toEqual({ userId: 'abc123' })
+    })
+
+    it('passes query params to handler', async () => {
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create(
+        'SearchUsers',
+        {
+          method: 'get',
+          path: '/users',
+          schema: {
+            params: Type.Object({
+              q: Type.Optional(Type.String()),
+              limit: Type.Optional(Type.String()),
+            }),
+          },
+        },
+        async (_ctx, params) => ({ query: params?.q, limit: params?.limit })
+      )
+
+      registerExpressRoutes(app, { getContext: async () => ({ user: 'test' }) }, getProcedures())
+
+      const response = await supertest(app).get('/users?q=test&limit=10')
+      expect(response.body).toEqual({ query: 'test', limit: '10' })
+    })
+
+    it('passes body params to handler', async () => {
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create(
+        'CreatePost',
+        {
+          method: 'post',
+          path: '/posts',
+          schema: {
+            params: Type.Object({
+              title: Type.Optional(Type.String()),
+              content: Type.Optional(Type.String()),
+            }),
+          },
+        },
+        async (_ctx, params) => ({ title: params?.title, content: params?.content })
+      )
+
+      registerExpressRoutes(app, { getContext: async () => ({ user: 'test' }) }, getProcedures())
+
+      const response = await supertest(app)
+        .post('/posts')
+        .send({ title: 'Hello', content: 'World' })
+      expect(response.body).toEqual({ title: 'Hello', content: 'World' })
+    })
+
+    it('merges path, query, and body params', async () => {
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create(
+        'UpdatePost',
+        {
+          method: 'put',
+          path: '/users/:userId/posts/:postId',
+          schema: {
+            params: Type.Object({
+              userId: Type.Optional(Type.String()),
+              postId: Type.Optional(Type.String()),
+              filter: Type.Optional(Type.String()),
+              title: Type.Optional(Type.String()),
+            }),
+          },
+        },
+        async (_ctx, params) => ({
+          userId: params?.userId,
+          postId: params?.postId,
+          filter: params?.filter,
+          title: params?.title,
+        })
+      )
+
+      registerExpressRoutes(app, { getContext: async () => ({ user: 'test' }) }, getProcedures())
+
+      const response = await supertest(app)
+        .put('/users/u1/posts/p2?filter=active')
+        .send({ title: 'Updated Title' })
+      expect(response.body).toEqual({
+        userId: 'u1',
+        postId: 'p2',
+        filter: 'active',
+        title: 'Updated Title',
+      })
+    })
+  })
+
+  describe('Context Generation', () => {
+    it('calls getContext with req and res', async () => {
+      const getContext = vi.fn().mockResolvedValue({ user: 'testuser' })
+
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create('GetData', { method: 'get', path: '/data' }, async () => ({ ok: true }))
+
+      registerExpressRoutes(app, { getContext }, getProcedures())
+
+      await supertest(app).get('/data')
+
+      expect(getContext).toHaveBeenCalledTimes(1)
+      expect(getContext).toHaveBeenCalledWith(
+        expect.objectContaining({ method: 'GET' }),
+        expect.objectContaining({ statusCode: 200 })
+      )
+    })
+
+    it('passes context to handler', async () => {
+      const { Create, getProcedures } = Procedures<
+        { user: string; permissions: string[] },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create('GetProfile', { method: 'get', path: '/profile' }, async (ctx) => ({
+        user: ctx.user,
+        permissions: ctx.permissions,
+      }))
+
+      registerExpressRoutes(
+        app,
+        {
+          getContext: async () => ({
+            user: 'alice',
+            permissions: ['read', 'write'],
+          }),
+        },
+        getProcedures()
+      )
+
+      const response = await supertest(app).get('/profile')
+      expect(response.body).toEqual({
+        user: 'alice',
+        permissions: ['read', 'write'],
+      })
+    })
+  })
+
+  describe('Validation Error Handling', () => {
+    it('returns 422 with default handler when validation fails', async () => {
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create(
+        'CreateItem',
+        {
+          method: 'post',
+          path: '/items',
+          schema: {
+            params: Type.Object({
+              name: Type.String({ minLength: 1 }),
+              quantity: Type.Number({ minimum: 1 }),
+            }),
+          },
+        },
+        async (_ctx, params) => ({ created: params })
+      )
+
+      registerExpressRoutes(app, { getContext: async () => ({ user: 'test' }) }, getProcedures())
+
+      const response = await supertest(app).post('/items').send({ name: '', quantity: 0 })
+
+      expect(response.status).toBe(422)
+      expect(response.body.error).toBe('Validation Error')
+      expect(response.body.details).toBeDefined()
+      expect(Array.isArray(response.body.details)).toBe(true)
+    })
+
+    it('calls custom onValidationError callback', async () => {
+      const onValidationError = vi.fn((errors, _req, res) => {
+        res.status(400).json({ custom: 'validation error', errors })
+      })
+
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create(
+        'ValidateItem',
+        {
+          method: 'post',
+          path: '/validate',
+          schema: {
+            params: Type.Object({
+              required: Type.String(),
+            }),
+          },
+        },
+        async () => ({ ok: true })
+      )
+
+      registerExpressRoutes(
+        app,
+        { getContext: async () => ({ user: 'test' }), onValidationError },
+        getProcedures()
+      )
+
+      const response = await supertest(app).post('/validate').send({})
+
+      expect(onValidationError).toHaveBeenCalledTimes(1)
+      expect(response.status).toBe(400)
+      expect(response.body.custom).toBe('validation error')
+    })
+
+    it('does not call handler when validation fails', async () => {
+      const handlerFn = vi.fn().mockResolvedValue({ ok: true })
+
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create(
+        'NoCall',
+        {
+          method: 'post',
+          path: '/nocall',
+          schema: {
+            params: Type.Object({
+              required: Type.String(),
+            }),
+          },
+        },
+        handlerFn
+      )
+
+      registerExpressRoutes(app, { getContext: async () => ({ user: 'test' }) }, getProcedures())
+
+      await supertest(app).post('/nocall').send({})
+
+      expect(handlerFn).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('Handler Error Handling', () => {
+    it('returns 500 with default handler when handler throws', async () => {
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create('ThrowError', { method: 'get', path: '/error' }, async () => {
+        throw new Error('Something went wrong')
+      })
+
+      registerExpressRoutes(app, { getContext: async () => ({ user: 'test' }) }, getProcedures())
+
+      const response = await supertest(app).get('/error')
+
+      expect(response.status).toBe(500)
+      expect(response.body.error).toContain('Something went wrong')
+    })
+
+    it('calls custom onHandlerError callback', async () => {
+      const onHandlerError = vi.fn((error, _req, res) => {
+        res.status(503).json({ custom: 'error handler', message: error.message })
+      })
+
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create('CustomError', { method: 'get', path: '/custom-error' }, async () => {
+        throw new Error('Custom failure')
+      })
+
+      registerExpressRoutes(
+        app,
+        { getContext: async () => ({ user: 'test' }), onHandlerError },
+        getProcedures()
+      )
+
+      const response = await supertest(app).get('/custom-error')
+
+      expect(onHandlerError).toHaveBeenCalledTimes(1)
+      expect(response.status).toBe(503)
+      expect(response.body).toEqual({
+        custom: 'error handler',
+        message: 'Custom failure',
+      })
+    })
+  })
+
+  describe('Success Response', () => {
+    it('returns handler result as JSON', async () => {
+      const { Create, getProcedures } = Procedures<
+        { user: string },
+        { method: 'get' | 'post' | 'patch' | 'delete' | 'put'; path: string }
+      >()
+
+      Create('ComplexResult', { method: 'get', path: '/complex' }, async () => ({
+        nested: {
+          data: [1, 2, 3],
+          metadata: { count: 3 },
+        },
+        status: 'success',
+      }))
+
+      registerExpressRoutes(app, { getContext: async () => ({ user: 'test' }) }, getProcedures())
+
+      const response = await supertest(app).get('/complex')
+
+      expect(response.status).toBe(200)
+      expect(response.headers['content-type']).toMatch(/application\/json/)
+      expect(response.body).toEqual({
+        nested: {
+          data: [1, 2, 3],
+          metadata: { count: 3 },
+        },
+        status: 'success',
+      })
+    })
+  })
+})

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

@@ -0,0 +1,108 @@
+import express from 'express'
+import { TProcedureRegistration } from '../../../index.js'
+
+/**
+ * Maps path parameters from Express route to an object
+ *
+ * Path /users/:id with /users/123 => { id: '123' }
+ *
+ * @param path
+ * @param url
+ */
+export function mapPathParamsToObject(path: string, url: string): Record<string, string> {
+  const urlObj = new URL(url, 'http://localhost') // Base URL is required but irrelevant here
+  const pathSegments = path.split('/').filter(Boolean)
+  const urlSegments = urlObj.pathname.split('/').filter(Boolean)
+
+  const params: Record<string, string> = {}
+  pathSegments.forEach((segment, index) => {
+    if (segment.startsWith(':')) {
+      const paramName = segment.slice(1)
+      params[paramName] = urlSegments[index] || ''
+    }
+  })
+
+  return params
+}
+
+/**
+ * Combines path, query, and body parameters from an Express request into a single object
+ * @param req
+ */
+function getAllParamsFromExpressRequest(req: express.Request): Record<string, any> {
+  const pathParams = mapPathParamsToObject(req.route.path, req.url)
+  const queryParams = req.query || {}
+  const bodyParams = req.body || {}
+
+  return { ...pathParams, ...queryParams, ...bodyParams }
+}
+
+/**
+ * A convenience function to register multiple procedures as Express routes.
+ *
+ * Provide the Express app, a context generator function, and an array of procedure registrations.
+ *
+ * @param app
+ * @param callbacks
+ * @param procedures
+ */
+export function registerExpressRoutes<ProceduresContext>(
+  app: express.Application,
+  callbacks: {
+    /** Get procedure factory context for handler */
+    getContext: (req: express.Request, res: express.Response) => Promise<ProceduresContext>
+    /** Optional error handler for procedure handler errors */
+    onHandlerError?: (error: Error, req: express.Request, res: express.Response) => void
+    /** Optional validation error handler */
+    onValidationError?: (
+      errors: Array<{ message: string; path: string[] }>,
+      req: express.Request,
+      res: express.Response
+    ) => void
+  },
+  // The procedure extended config must include method and path
+  procedures: Array<
+    TProcedureRegistration<
+      ProceduresContext,
+      {
+        method: 'get' | 'post' | 'patch' | 'delete' | 'put'
+        path: string
+      }
+    >
+  >
+): void {
+  procedures.forEach(({ handler, config }) => {
+    const { method, path } = config
+
+    app[method](path, async (req, res) => {
+      const context = await callbacks.getContext(req, res)
+
+      const allParams = getAllParamsFromExpressRequest(req)
+
+      if (config.validation?.params) {
+        const { errors } = config.validation.params(allParams)
+
+        if (errors && errors.length > 0) {
+          if (callbacks.onValidationError) {
+            callbacks.onValidationError(errors, req, res)
+          } else {
+            res.status(422).json({ error: 'Validation Error', details: errors })
+          }
+          return
+        }
+      }
+
+      try {
+        const result = await handler(context as any, allParams)
+
+        res.json(result)
+      } catch (error) {
+        if (callbacks.onHandlerError) {
+          callbacks.onHandlerError(error as Error, req, res)
+          return
+        }
+        res.status(500).json({ error: (error as Error).message })
+      }
+    })
+  })
+}

package/src/index.test.ts

@@ -310,8 +310,10 @@ describe('Procedures', () => {
       },
     )
 
-    expect(getProcedures().get('test-docs')).toBeDefined()
-    expect(getProcedures().get('test-docs')?.config?.schema).toEqual({
+    const procedures = getProcedures()
+    const testDocsProcedure = procedures.find(p => p.name === 'test-docs')
+    expect(testDocsProcedure).toBeDefined()
+    expect(testDocsProcedure?.config?.schema).toEqual({
       params: {
         type: 'object',
         properties: {

package/src/index.ts

@@ -51,22 +51,7 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
 ) {
   const procedures: Map<
     string,
-    {
-      name: string
-      config: Prettify<
-        {
-          description?: string
-          schema?: {
-            params?: TJSONSchema
-            returnType?: TJSONSchema
-          }
-          validation?: {
-            params?: (params: any) => { errors?: any[] }
-          }
-        } & TExtendedConfig
-      >
-      handler: (ctx: Prettify<TContext>, params: any) => Promise<any>
-    }
+    TProcedureRegistration<TContext, TExtendedConfig>
   > = new Map()
 
   function Create<TName extends string, TParams, TReturnType>(
@@ -136,6 +121,10 @@ 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) {
@@ -171,8 +160,11 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
   }
 
   return {
+    /**
+     * Get all registered procedures
+     */
     getProcedures: () => {
-      return procedures
+      return Array.from(procedures.values())
     },
 
     Create,