ts-procedures 1.0.0

package/src/index.test.ts

@@ -0,0 +1,364 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { describe, expect, test } from 'vitest'
+import { Procedures } from './index.js'
+import { v } from 'suretype'
+import { Type } from 'typebox'
+import {
+  ProcedureError,
+  ProcedureValidationError,
+} from './errors.js'
+
+describe('Procedures', () => {
+  test('Procedures', () => {
+    const result = Procedures({
+      onCreate: () => {
+        return undefined
+      },
+    })
+
+    expect(result).toHaveProperty('Create')
+  })
+
+  test('Procedures generic context & extended config', () => {
+    interface CustomContext {
+      authToken: string
+    }
+
+    interface ExtendedConfig {
+      customProp: string
+      optionalProp?: number
+    }
+
+    const { Create } = Procedures<CustomContext, ExtendedConfig>()
+
+    const {info} = Create(
+      'TestProcedure',
+      {
+        // should not throw type errors
+        customProp: 'customProp',
+      },
+      async (ctx) => {
+        // should not throw type errors
+        return ctx.authToken
+      },
+    )
+
+    expect(info.customProp).toEqual('customProp')
+    expect(info.optionalProp).toEqual(undefined)
+  })
+
+  test('Create Single Procedures', () => {
+    const { procedure: procedure1, info: info1 } = Procedures().Create(
+      'test1',
+      {},
+      async () => {
+        return '1'
+      },
+    )
+    const { procedure: procedure2, info: info2 } = Procedures().Create(
+      'test2',
+      {},
+      async () => {
+        return '2'
+      },
+    )
+
+    expect(procedure1).toBeDefined()
+    expect(info1).toBeDefined()
+    expect(procedure2).toBeDefined()
+    expect(info2).toBeDefined()
+  })
+
+  test('Procedures - Create call', () =>
+    new Promise<void>((done) => {
+      let mockHttpCall: any
+
+      const { Create } = Procedures({
+        onCreate: ({ handler }) => {
+          mockHttpCall = handler
+        },
+      })
+
+      Create(
+        'Handler',
+        {
+          schema: {
+            params: v.object({ name: v.string() }),
+            returnType: v.string(),
+          },
+        },
+        async (ctx, params) => {
+          expect(params).toEqual({ name: 'name' })
+          done()
+          return 'name'
+        },
+      )
+
+      mockHttpCall({}, { name: 'name' })
+    }))
+
+  test('Procedures - Create call w/ Typebox', () =>
+    new Promise<void>((done) => {
+      let mockHttpCall: any
+
+      const { Create } = Procedures({
+        onCreate: ({ handler, config, name }) => {
+          mockHttpCall = handler
+        },
+      })
+
+      Create(
+        'Handler',
+        {
+          schema: {
+            params: Type.Object({ name: Type.Optional(Type.String()) }),
+            returnType: Type.String(),
+          },
+        },
+        async (ctx, params) => {
+          expect(params).toEqual({ name: 'name' })
+          done()
+          return 'name'
+        },
+      )
+
+      mockHttpCall({}, { name: 'name' })
+    }))
+
+  test('Procedures - Create returns a handler to call/test the Procedure registration', async () => {
+    let ProcedureRegisteredCbHandler: any
+
+    const { Create } = Procedures({
+      onCreate: (Procedure) => {
+        ProcedureRegisteredCbHandler = Procedure.handler
+      },
+    })
+
+    const { NamedExportHandler, procedure, info } = Create(
+      'NamedExportHandler',
+      {
+        description: 'Handler description',
+        schema: {
+          params: v.object({ number: v.number() }),
+        },
+      },
+      async (ctx, params) => {
+        return params.number
+      },
+    )
+
+    expect(NamedExportHandler).toBeDefined()
+    expect(procedure).toBeDefined()
+    expect(ProcedureRegisteredCbHandler).toEqual(NamedExportHandler)
+    expect(ProcedureRegisteredCbHandler).toEqual(procedure)
+
+    const result = NamedExportHandler({}, { number: 1 })
+
+    expect(result).toBeDefined()
+    expect(result).toBeInstanceOf(Promise)
+    await expect(result).resolves.toEqual(1)
+
+    expect(info).toBeDefined()
+    expect(info).toBeInstanceOf(Object)
+    expect(info.schema).toHaveProperty('params')
+    expect(info.schema.params).toEqual({
+      type: 'object',
+      properties: { number: { type: 'number' } },
+    })
+    expect(info).toHaveProperty('description')
+    expect(info.description).toEqual('Handler description')
+  })
+
+  test('Procedures - Create params validation w/ no params provided', () =>
+    new Promise<void>((done) => {
+      let mockHttpCall: any
+
+      const { Create } = Procedures({
+        onCreate: ({ handler, config, name }) => {
+          mockHttpCall = (callParams: any) => {
+            if (config.validation?.params) {
+              const { errors } = config.validation.params(callParams)
+
+              if (errors && 'message' in errors[0]) {
+                expect(errors[0].message).toEqual('must be object')
+                done()
+                return
+              }
+            }
+
+            handler(callParams, {})
+          }
+        },
+      })
+
+      Create(
+        'test',
+        {
+          schema: {
+            params: v.object({}),
+          },
+        },
+        async () => {
+          done()
+        },
+      )
+
+      mockHttpCall()
+    }))
+
+  test('Procedures - Create params validation w/ missing params', async () =>
+    new Promise<void>((done) => {
+      let mockHttpCall: any
+
+      const { Create } = Procedures({
+        onCreate: async ({ handler, config, name }) => {
+          mockHttpCall = async (callParams: any) => {
+            if (config.validation?.params) {
+              const { errors } = config.validation.params(callParams)
+              expect(errors).toBeDefined()
+              expect(errors?.length).toEqual(2)
+            }
+
+            try {
+              await handler(callParams, {})
+            } catch (e: any) {
+              expect(e).instanceof(ProcedureValidationError)
+              expect(e.errors.length).toEqual(2)
+              done()
+            }
+          }
+        },
+      })
+
+      Create(
+        'test',
+        {
+          schema: {
+            params: v.object({
+              name: v.string().required(),
+              id: v.number().required(),
+              email: v.string(),
+            }),
+          },
+        },
+        async () => {
+          return
+        },
+      )
+
+      mockHttpCall({})
+    }))
+
+  test('Procedures - Create call provides ctx to handler', () =>
+    new Promise<void>((done) => {
+      let mockHttpCall: any
+
+      const { Create } = Procedures<{
+        testCtx: string
+      }>({
+        onCreate: ({ handler }) => {
+          mockHttpCall = () => handler({ testCtx: 'testCtx' })
+        },
+      })
+
+      Create('test', {}, async (ctx, params) => {
+        expect(ctx.testCtx).toEqual('testCtx')
+        done()
+      })
+
+      mockHttpCall()
+    }))
+
+  test('Procedure handler can throw local ctx error and is caught', async () => {
+    const { Create } = Procedures()
+
+    const { TestProcedureHandlerError } = Create(
+      'TestProcedureHandlerError',
+      {},
+      async (ctx) => {
+        throw ctx.error( 'Local context error')
+      },
+    )
+
+    try {
+      await TestProcedureHandlerError({}, {})
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureError)
+
+      expect(e.message).toEqual('Local context error')
+      expect(e.procedureName).toEqual('TestProcedureHandlerError')
+    }
+  })
+
+  test('Procedures - getRegisteredProcedures', () => {
+    const { Create, getProcedures } = Procedures({
+      onCreate: () => {
+        return undefined
+      },
+    })
+
+    Create(
+      'test-docs',
+      {
+        schema: {
+          params: v.object({ name: v.string().required() }),
+          returnType: v.string(),
+        },
+      },
+      async () => {
+        return 'test-docs'
+      },
+    )
+
+    expect(getProcedures().get('test-docs')).toBeDefined()
+    expect(getProcedures().get('test-docs')?.config?.schema).toEqual({
+      params: {
+        type: 'object',
+        properties: {
+          name: {
+            type: 'string',
+          },
+        },
+        required: ['name'],
+      },
+      returnType: {
+        type: 'string',
+      },
+    })
+  })
+
+  test('Procedures - context() throws', async () => {
+    interface CustomContext {
+      authToken: string
+    }
+
+    const { Create } = Procedures<CustomContext>()
+
+    function validateAuthToken(token: string) {
+      return token === 'valid-token'
+    }
+
+    const { CheckIsAuthenticated } = Create(
+      'CheckIsAuthenticated',
+      {
+        schema: {
+          returnType: v.string(),
+        },
+      },
+      async (ctx) => {
+        if (!validateAuthToken(ctx.authToken)) {
+          throw ctx.error('Invalid auth token')
+        }
+
+        return 'User authentication is valid'
+      },
+    )
+
+    await expect(
+      CheckIsAuthenticated({ authToken: 'valid-token' }, {}),
+    ).resolves.toEqual('User authentication is valid')
+    await expect(
+      CheckIsAuthenticated({ authToken: 'not-valid-token' }, {}),
+    ).rejects.toThrowError(ProcedureError)
+  })
+})

package/src/index.ts

@@ -0,0 +1,180 @@
+import { ProcedureError, ProcedureValidationError } from './errors.js'
+import { computeSchema } from './schema/compute-schema.js'
+import { Prettify, TJSONSchema, TSchemaLib } from './schema/types.js'
+
+export type TNoContextProvided = unknown
+
+export type TLocalContext = {
+  error: (message: string, meta?: object) => ProcedureError
+}
+
+export type TProcedureRegistration<TContext = unknown, TExtendedConfig = unknown> = {
+  name: string
+  config: {
+    description?: string
+    schema?: {
+      params?: TJSONSchema
+      returnType?: TJSONSchema
+    }
+    validation?: {
+      params?: (params: any) => { errors?: any[] }
+    }
+  } & TExtendedConfig
+
+  handler: (ctx: TContext, params?: any) => Promise<any>
+}
+
+export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unknown>(
+  /**
+   * Optionally provided builder to register Procedures
+   */
+  builder?: {
+    onCreate?: (
+      procedure: Prettify<{
+        name: string
+        handler: (ctx: Prettify<TContext>, params?: any) => Promise<any>
+        config: Prettify<
+          {
+            description?: string
+            schema?: {
+              params?: TJSONSchema
+              returnType?: TJSONSchema
+            }
+            validation?: {
+              params?: (params: any) => { errors?: any[] }
+            }
+          } & TExtendedConfig
+        >
+      }>
+    ) => void
+  }
+) {
+  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>
+    }
+  > = new Map()
+
+  function Create<TName extends string, TParams, TReturnType>(
+    name: TName,
+    config: {
+      description?: string
+      schema?: {
+        params?: TParams
+        returnType?: TReturnType
+      }
+    } & TExtendedConfig,
+    handler: (
+      ctx: Prettify<TContext & TLocalContext>,
+      params: TSchemaLib<TParams>
+    ) => Promise<TSchemaLib<TReturnType>>
+  ) {
+    const { jsonSchema, validations } = computeSchema(name, config.schema)
+
+    const registeredProcedure = {
+      name,
+      config: {
+        // ctx: config.hook, ??? why was this here
+        ...config,
+        description: config.description,
+        schema: jsonSchema,
+        validation: {
+          params: validations.params,
+        },
+      },
+
+      handler: async (ctx: Prettify<TContext>, params: TSchemaLib<TParams>) => {
+        try {
+          if (validations?.params) {
+            const { errors } = validations.params(params)
+
+            if (errors) {
+              throw new ProcedureValidationError(
+                name,
+                `Validation error for ${name} - ${errors.map((e) => e.message).join(', ')}`,
+                errors
+              )
+            }
+          }
+
+          const localCtx: TLocalContext = {
+            error: (message: string, meta?: object) => {
+              return new ProcedureError(name, message, meta)
+            },
+          }
+
+          return handler(
+            {
+              ...ctx,
+              ...localCtx,
+            } as Prettify<TContext & TLocalContext>,
+            params
+          )
+        } catch (error: any) {
+          if (error instanceof ProcedureError) {
+            throw error
+          } else {
+            const err = new ProcedureError(name, `Error in handler for ${name} - ${error?.message}`)
+            err.stack = error.stack
+            throw err
+          }
+        }
+      },
+    }
+
+    procedures.set(name, registeredProcedure)
+
+    if (builder?.onCreate) {
+      builder.onCreate(registeredProcedure)
+    }
+
+    const info = {
+      name,
+      ...registeredProcedure.config,
+    }
+
+    // return so can be called directly (ie: int/unit tests)
+    return {
+      [name]: registeredProcedure.handler,
+      procedure: registeredProcedure.handler,
+      info,
+    } as {
+      [K in TName]: (ctx: Prettify<TContext>, params: TSchemaLib<TParams>) => Promise<TSchemaLib<TReturnType>>
+    } & {
+      procedure: (ctx: Prettify<TContext>, params: TSchemaLib<TParams>) => Promise<TSchemaLib<TReturnType>>
+      info: {
+        name: TName
+        description?: string
+        schema: {
+          params?: TParams
+          returnType?: TReturnType
+        }
+        validation?: {
+          params?: (params: any) => { errors?: any[] }
+        }
+      } & TExtendedConfig
+    }
+  }
+
+  return {
+    getProcedures: () => {
+      return procedures
+    },
+
+    Create,
+  }
+}

package/src/schema/compute-schema.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from 'vitest'
+import { Type } from 'typebox'
+import { v } from 'suretype'
+import { computeSchema } from './compute-schema.js'
+import { ProcedureRegistrationError } from '../errors.js'
+
+describe('computeSchema', () => {
+  it('should return empty schema and validations when no schema provided', () => {
+    const result = computeSchema('test-procedure')
+
+    expect(result).toEqual({
+      jsonSchema: { params: undefined, returnType: undefined },
+      validations: {}
+    })
+  })
+
+  describe('with Typebox schema', () => {
+    it('should correctly process params schema', () => {
+      const schema = {
+        params: Type.Object({
+          name: Type.String(),
+          age: Type.Number()
+        })
+      }
+
+      const result = computeSchema('test-procedure', schema)
+
+      expect(result.jsonSchema.params).toBeDefined()
+      expect(result.validations.params).toBeDefined()
+
+      // Test validation function
+      const validInput = { name: 'John', age: 30 }
+      expect(result.validations.params?.(validInput).errors).toBeUndefined()
+
+      // Test invalid input
+      const invalidInput = { name: 123, age: 'invalid' }
+      expect(result.validations.params?.(invalidInput).errors).toBeDefined()
+    })
+
+    it('should correctly process returnType schema', () => {
+      const schema = {
+        returnType: Type.Object({
+          result: Type.Boolean()
+        })
+      }
+
+      const result = computeSchema('test-procedure', schema)
+
+      expect(result.jsonSchema.returnType).toBeDefined()
+      expect(result.validations.params).toBeUndefined()
+    })
+  })
+
+  describe('with Suretype schema', () => {
+    it('should correctly process params schema', () => {
+      const schema = {
+        params: v.object({
+          name: v.string(),
+          age: v.number()
+        })
+      }
+
+      const result = computeSchema('test-procedure', schema)
+
+      expect(result.jsonSchema.params).toBeDefined()
+      expect(result.validations.params).toBeDefined()
+
+      // Test validation function
+      const validInput = { name: 'John', age: 30 }
+      expect(result.validations.params?.(validInput).errors).toBeUndefined()
+
+      // Test invalid input
+      const invalidInput = { name: 123, age: 'invalid' }
+      expect(result.validations.params?.(invalidInput).errors).toBeDefined()
+    })
+  })
+
+  describe('error handling', () => {
+    it('should throw ProcedureRegistrationError for invalid schema', () => {
+      const invalidSchema = {
+        params: {
+          type: 'invalid-schema-type'
+        }
+      }
+
+      expect(() => computeSchema('test-procedure', invalidSchema))
+        .toThrow(ProcedureRegistrationError)
+    })
+
+    it('should include procedure name in error message', () => {
+      const invalidSchema = {
+        params: {
+          type: 'invalid-schema-type'
+        }
+      }
+
+      try {
+        computeSchema('test-procedure', invalidSchema)
+      } catch (error: any) {
+        expect(error instanceof ProcedureRegistrationError).toBe(true)
+        expect(error.message).toContain('test-procedure')
+      }
+    })
+  })
+
+  describe('combined schemas', () => {
+    it('should handle both params and returnType schemas', () => {
+      const schema = {
+        params: Type.Object({
+          input: Type.String()
+        }),
+        returnType: Type.Object({
+          output: Type.Boolean()
+        })
+      }
+
+      const result = computeSchema('test-procedure', schema)
+
+      expect(result.jsonSchema.params).toBeDefined()
+      expect(result.jsonSchema.returnType).toBeDefined()
+      expect(result.validations.params).toBeDefined()
+
+      // Test params validation
+      const validInput = { input: 'test' }
+      expect(result.validations.params?.(validInput).errors).toBeUndefined()
+    })
+  })
+})