ts-procedures 7.3.0 → 8.0.0

package/src/create.test.ts

@@ -0,0 +1,658 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { describe, expect, it, 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 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) => {
+            const validation = (config as any).validation
+            if (validation?.params) {
+              const { errors } = 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) => {
+            const validation = (config as any).validation
+            if (validation?.params) {
+              const { errors } = 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 - 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
+    )
+  })
+
+  test('Procedures - wrapped errors preserve cause', async () => {
+    const { Create } = Procedures()
+    const originalError = new Error('Database connection failed')
+    ;(originalError as any).code = 'ECONNREFUSED'
+
+    const { TestCause } = Create('TestCause', {}, async () => {
+      throw originalError
+    })
+
+    try {
+      await TestCause({}, {})
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureError)
+      expect(e.cause).toBe(originalError)
+      expect(e.cause.code).toBe('ECONNREFUSED')
+    }
+  })
+
+  test('Procedures - ctx.error still works after optimization', async () => {
+    const { Create } = Procedures()
+
+    const { ErrorTest } = Create('ErrorTest', {}, async (ctx) => {
+      throw ctx.error('Custom error message', { code: 'ERR_001' })
+    })
+
+    try {
+      await ErrorTest({}, {})
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureError)
+      expect(e.message).toBe('Custom error message')
+      expect(e.procedureName).toBe('ErrorTest')
+      expect(e.meta).toEqual({ code: 'ERR_001' })
+    }
+  })
+
+  test('Create passes through external signal from context', async () => {
+    const { Create } = Procedures<{ signal: AbortSignal }>()
+    const externalAc = new AbortController()
+    let capturedSignal: AbortSignal | null = null
+
+    const { WithSignal } = Create('WithSignal', {}, async (ctx) => {
+      capturedSignal = ctx.signal!
+      return 'done'
+    })
+
+    await WithSignal({ signal: externalAc.signal }, {})
+    expect(capturedSignal).toBe(externalAc.signal)
+    expect(capturedSignal!.aborted).toBe(false)
+  })
+
+  test('Create external signal reflects abort from caller', async () => {
+    const { Create } = Procedures<{ signal: AbortSignal }>()
+    const externalAc = new AbortController()
+    let capturedSignal: AbortSignal | null = null
+
+    const { AbortedSignal } = Create('AbortedSignal', {}, async (ctx) => {
+      capturedSignal = ctx.signal!
+      expect(ctx.signal!.aborted).toBe(true)
+      return 'done'
+    })
+
+    externalAc.abort()
+    await AbortedSignal({ signal: externalAc.signal }, {})
+    expect(capturedSignal!.aborted).toBe(true)
+  })
+
+  test('Create external signal cancels in-flight async work', async () => {
+    const { Create } = Procedures<{ signal: AbortSignal }>()
+    const externalAc = new AbortController()
+    let wasAbortedDuringWork = false
+    const ready = Promise.withResolvers<void>()
+
+    const { LongWork } = Create('LongWork', {}, async (ctx) => {
+      ready.resolve()
+      await new Promise<void>((resolve) => {
+        ctx.signal!.addEventListener('abort', () => {
+          wasAbortedDuringWork = true
+          resolve()
+        })
+      })
+      return 'done'
+    })
+
+    const p = LongWork({ signal: externalAc.signal }, {})
+    await ready.promise
+    externalAc.abort()
+    await p
+    expect(wasAbortedDuringWork).toBe(true)
+  })
+})
+
+describe('Procedures - Definition Location in Errors', () => {
+  test('ProcedureValidationError includes definition location', async () => {
+    const { Create } = Procedures()
+
+    const { TestValidation } = Create(
+      'TestValidation',
+      {
+        schema: {
+          params: v.object({ name: v.string().required() }),
+        },
+      },
+      async (ctx, params) => {
+        return params.name
+      }
+    )
+
+    try {
+      // @ts-expect-error - intentionally passing invalid params
+      await TestValidation({}, {}) // Missing required 'name' param
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureValidationError)
+      expect(e.definedAt).toBeDefined()
+      expect(e.definedAt.file).toContain('create.test.ts')
+      expect(e.definedAt.line).toBeGreaterThan(0)
+      expect(e.definedAt.column).toBeGreaterThan(0)
+      expect(e.stack).toContain('--- Procedure "TestValidation" defined at ---')
+    }
+  })
+
+  test('ctx.error() includes definition location', async () => {
+    const { Create } = Procedures()
+
+    const { TestCtxError } = Create('TestCtxError', {}, async (ctx) => {
+      throw ctx.error('Custom error')
+    })
+
+    try {
+      await TestCtxError({}, {})
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureError)
+      expect(e.definedAt).toBeDefined()
+      expect(e.definedAt.file).toContain('create.test.ts')
+      expect(e.getDefinitionLocation()).toBeDefined()
+      expect(e.stack).toContain('--- Procedure "TestCtxError" defined at ---')
+    }
+  })
+
+  test('wrapped errors include definition location', async () => {
+    const { Create } = Procedures()
+
+    const { TestWrappedError } = Create('TestWrappedError', {}, async () => {
+      throw new Error('Original error')
+    })
+
+    try {
+      await TestWrappedError({}, {})
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureError)
+      expect(e.definedAt).toBeDefined()
+      expect(e.definedAt.file).toContain('create.test.ts')
+      expect(e.message).toContain('Error in handler for TestWrappedError')
+      expect(e.cause).toBeInstanceOf(Error)
+      expect(e.cause.message).toBe('Original error')
+    }
+  })
+
+  test('getDefinitionLocation returns formatted string', async () => {
+    const { Create } = Procedures()
+
+    const { TestGetLocation } = Create(
+      'TestGetLocation',
+      {
+        schema: {
+          params: v.object({ id: v.number().required() }),
+        },
+      },
+      async (ctx, params) => {
+        return params.id
+      }
+    )
+
+    try {
+      // @ts-expect-error - intentionally passing invalid params
+      await TestGetLocation({}, {}) // Missing required 'id' param
+    } catch (e: any) {
+      const location = e.getDefinitionLocation()
+      expect(location).toBeDefined()
+      expect(location).toMatch(/create\.test\.ts:\d+:\d+/)
+    }
+  })
+
+  test('error stack shows procedure definition location at the end', async () => {
+    const { Create } = Procedures()
+
+    const { TestStackFormat } = Create(
+      'TestStackFormat',
+      {
+        schema: {
+          params: v.object({ value: v.string().required() }),
+        },
+      },
+      async (ctx, params) => {
+        return params.value
+      }
+    )
+
+    try {
+      // @ts-expect-error - intentionally passing invalid params
+      await TestStackFormat({}, {})
+    } catch (e: any) {
+      // Verify it's a validation error
+      expect(e.name).toBe('ProcedureValidationError')
+      expect(e).toBeInstanceOf(ProcedureValidationError)
+      // Stack should contain the error message and definition location
+      expect(e.stack).toContain('Validation error for TestStackFormat')
+      expect(e.stack).toContain('--- Procedure "TestStackFormat" defined at ---')
+      // The definition section should be at the end of the stack
+      const stackLines = e.stack.split('\n')
+      const definitionIndex = stackLines.findIndex((line: string) =>
+        line.includes('--- Procedure "TestStackFormat" defined at ---')
+      )
+      expect(definitionIndex).toBeGreaterThan(0)
+    }
+  })
+})
+
+describe('isPrevalidated context property', () => {
+  test('Create skips validation when ctx.isPrevalidated is true', async () => {
+    const { Create } = Procedures()
+
+    const { SkipValidation } = Create(
+      'SkipValidation',
+      {
+        schema: {
+          params: v.object({ name: v.string().required() }),
+        },
+      },
+      async (ctx, params) => {
+        return params
+      }
+    )
+
+    // Without isPrevalidated, missing required param would throw
+    // With isPrevalidated: true, validation is skipped
+    const result = await SkipValidation({ isPrevalidated: true }, {} as any)
+    expect(result).toEqual({})
+  })
+
+  test('Create validates when ctx.isPrevalidated is false', async () => {
+    const { Create } = Procedures()
+
+    const { ValidateParams } = Create(
+      'ValidateParams',
+      {
+        schema: {
+          params: v.object({ name: v.string().required() }),
+        },
+      },
+      async (ctx, params) => {
+        return params
+      }
+    )
+
+    // With isPrevalidated: false, validation should still run
+    try {
+      await ValidateParams({ isPrevalidated: false }, {} as any)
+      expect.fail('Should have thrown validation error')
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureValidationError)
+    }
+  })
+
+  test('Create validates when ctx.isPrevalidated is undefined', async () => {
+    const { Create } = Procedures()
+
+    const { ValidateUndefined } = Create(
+      'ValidateUndefined',
+      {
+        schema: {
+          params: v.object({ id: v.number().required() }),
+        },
+      },
+      async (ctx, params) => {
+        return params
+      }
+    )
+
+    // Without isPrevalidated property, validation should run
+    try {
+      await ValidateUndefined({}, {} as any)
+      expect.fail('Should have thrown validation error')
+    } catch (e: any) {
+      expect(e).toBeInstanceOf(ProcedureValidationError)
+    }
+  })
+
+  test('isPrevalidated is not exposed in handler context type', async () => {
+    const { Create } = Procedures()
+
+    Create('CheckCtxType', {}, async (ctx) => {
+      // @ts-expect-error - isPrevalidated should not be on handler context type
+      void ctx.isPrevalidated
+      return 'done'
+    })
+  })
+})
+
+describe('builder.config.noRuntimeValidation', () => {
+  test('Create skips params validation when noRuntimeValidation is true', async () => {
+    const { Create } = Procedures({ config: { noRuntimeValidation: true } })
+
+    const { SkipParams } = Create(
+      'SkipParams',
+      {
+        schema: {
+          params: Type.Object({ name: Type.String() }),
+        },
+      },
+      async (_ctx, params) => params
+    )
+
+    // Missing required `name` would normally throw ProcedureValidationError
+    const result = await SkipParams({}, {} as any)
+    expect(result).toEqual({})
+  })
+
+  // migrated to schema.req in Phase 3+
+  test.todo('Create skips input channel validation when noRuntimeValidation is true')
+
+  test('Create still validates when noRuntimeValidation is omitted', async () => {
+    const { Create } = Procedures({ config: {} })
+
+    const { ValidateDefault } = Create(
+      'ValidateDefault',
+      {
+        schema: {
+          params: Type.Object({ name: Type.String() }),
+        },
+      },
+      async (_ctx, params) => params
+    )
+
+    await expect(ValidateDefault({}, {} as any)).rejects.toBeInstanceOf(ProcedureValidationError)
+  })
+
+  test('Create validates when builder is omitted entirely', async () => {
+    const { Create } = Procedures()
+
+    const { ValidateNoBuilder } = Create(
+      'ValidateNoBuilder',
+      {
+        schema: {
+          params: Type.Object({ name: Type.String() }),
+        },
+      },
+      async (_ctx, params) => params
+    )
+
+    await expect(ValidateNoBuilder({}, {} as any)).rejects.toBeInstanceOf(
+      ProcedureValidationError
+    )
+  })
+})