ts-procedures 3.0.2 → 3.2.0

package/build/stack-utils.js

@@ -0,0 +1,95 @@
+/**
+ * Internal ts-procedures files that should be skipped when finding user code.
+ * Only skip the core library files, not test files or user code.
+ */
+const INTERNAL_FILES = [
+    '/index.ts',
+    '/index.js',
+    '/errors.ts',
+    '/errors.js',
+    '/stack-utils.ts',
+    '/stack-utils.js',
+    '/compute-schema.ts',
+    '/compute-schema.js',
+    '/parser.ts',
+    '/parser.js',
+];
+/**
+ * Captures the stack trace at the call site and extracts the definition location.
+ * Finds the first stack frame outside of ts-procedures internal files.
+ */
+export function captureDefinitionInfo() {
+    const err = new Error();
+    const stack = err.stack;
+    if (!stack) {
+        return {};
+    }
+    const lines = stack.split('\n');
+    // Find the first frame that's not from ts-procedures internals
+    // Skip the first line (Error message) and frames from this module
+    let userFrame;
+    for (let i = 1; i < lines.length; i++) {
+        const rawLine = lines[i];
+        if (!rawLine)
+            continue;
+        const line = rawLine.trim();
+        // Skip empty or invalid frames
+        if (!line.startsWith('at ')) {
+            continue;
+        }
+        // Skip frames from ts-procedures internal source files
+        const isInternalFile = INTERNAL_FILES.some(file => line.includes(file));
+        if (isInternalFile) {
+            continue;
+        }
+        // Skip frames from ts-procedures in node_modules (when used as a dependency)
+        if (line.includes('/node_modules/ts-procedures/') || line.includes('\\node_modules\\ts-procedures\\')) {
+            continue;
+        }
+        // Skip internal node frames
+        if (line.includes('node:') || line.startsWith('at Module.') || line.startsWith('at Object.<anonymous> (node:')) {
+            continue;
+        }
+        userFrame = line;
+        break;
+    }
+    if (!userFrame) {
+        return { definitionStack: stack };
+    }
+    const definedAt = parseStackFrame(userFrame);
+    return {
+        definedAt,
+        definitionStack: stack,
+    };
+}
+/**
+ * Parses a V8 stack frame line to extract file, line, and column info.
+ * Handles formats like:
+ * - "at Object.<anonymous> (/path/to/file.ts:10:5)"
+ * - "at functionName (/path/to/file.ts:10:5)"
+ * - "at /path/to/file.ts:10:5"
+ */
+function parseStackFrame(frame) {
+    // Match patterns like "(path:line:column)" or just "path:line:column"
+    const match = frame.match(/\(([^)]+):(\d+):(\d+)\)$/) || frame.match(/at ([^:]+):(\d+):(\d+)$/);
+    if (match && match[1] && match[2] && match[3]) {
+        return {
+            file: match[1],
+            line: parseInt(match[2], 10),
+            column: parseInt(match[3], 10),
+            raw: frame,
+        };
+    }
+    return undefined;
+}
+/**
+ * Formats definition info for appending to error stacks.
+ */
+export function formatDefinitionInfo(info, procedureName) {
+    if (!info.definedAt) {
+        return undefined;
+    }
+    const { file, line, column } = info.definedAt;
+    return `\n--- Procedure "${procedureName}" defined at ---\n    at ${file}:${line}:${column}`;
+}
+//# sourceMappingURL=stack-utils.js.map

package/build/stack-utils.js.map

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

package/build/stack-utils.test.d.ts

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

package/build/stack-utils.test.js

@@ -0,0 +1,80 @@
+import { describe, expect, test } from 'vitest';
+import { captureDefinitionInfo, formatDefinitionInfo } from './stack-utils.js';
+describe('Stack Utils', () => {
+    describe('captureDefinitionInfo', () => {
+        test('returns definition info with definedAt', () => {
+            const info = captureDefinitionInfo();
+            // Should capture the call site in this test file
+            expect(info).toBeDefined();
+            expect(info.definitionStack).toBeDefined();
+            expect(typeof info.definitionStack).toBe('string');
+        });
+        test('definedAt contains file, line, column when available', () => {
+            const info = captureDefinitionInfo();
+            // The definedAt should be present since we're calling from user code (test file)
+            if (info.definedAt) {
+                expect(info.definedAt.file).toBeDefined();
+                expect(typeof info.definedAt.file).toBe('string');
+                expect(info.definedAt.line).toBeDefined();
+                expect(typeof info.definedAt.line).toBe('number');
+                expect(info.definedAt.line).toBeGreaterThan(0);
+                expect(info.definedAt.column).toBeDefined();
+                expect(typeof info.definedAt.column).toBe('number');
+                expect(info.definedAt.column).toBeGreaterThan(0);
+                expect(info.definedAt.raw).toBeDefined();
+                expect(typeof info.definedAt.raw).toBe('string');
+            }
+        });
+        test('definitionStack contains Error stack trace', () => {
+            const info = captureDefinitionInfo();
+            expect(info.definitionStack).toContain('Error');
+            expect(info.definitionStack).toContain('at ');
+        });
+    });
+    describe('formatDefinitionInfo', () => {
+        test('returns undefined when definedAt is not present', () => {
+            const info = {};
+            const result = formatDefinitionInfo(info, 'TestProcedure');
+            expect(result).toBeUndefined();
+        });
+        test('returns formatted string when definedAt is present', () => {
+            const info = {
+                definedAt: {
+                    file: '/app/procedures/test.ts',
+                    line: 42,
+                    column: 5,
+                    raw: 'at Object.<anonymous> (/app/procedures/test.ts:42:5)',
+                },
+            };
+            const result = formatDefinitionInfo(info, 'TestProcedure');
+            expect(result).toBeDefined();
+            expect(result).toContain('--- Procedure "TestProcedure" defined at ---');
+            expect(result).toContain('/app/procedures/test.ts:42:5');
+        });
+        test('includes procedure name in formatted output', () => {
+            const info = {
+                definedAt: {
+                    file: '/path/to/file.ts',
+                    line: 10,
+                    column: 3,
+                    raw: 'at /path/to/file.ts:10:3',
+                },
+            };
+            const result = formatDefinitionInfo(info, 'MyCustomProcedure');
+            expect(result).toContain('"MyCustomProcedure"');
+        });
+    });
+    describe('integration with procedure creation', () => {
+        test('captures location from calling code', () => {
+            // Helper to simulate what happens in Create()
+            function simulateCreate() {
+                return captureDefinitionInfo();
+            }
+            const info = simulateCreate();
+            // Should have captured the location of the simulateCreate() call
+            expect(info).toBeDefined();
+            expect(info.definitionStack).toBeDefined();
+        });
+    });
+});
+//# sourceMappingURL=stack-utils.test.js.map

package/build/stack-utils.test.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "3.0.2",
+  "version": "3.2.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": "build/exports.js",
   "types": "build/exports.d.ts",

package/src/errors.test.ts

@@ -4,6 +4,7 @@ import {
   ProcedureValidationError,
   ProcedureRegistrationError,
 } from './errors.js'
+import { DefinitionInfo } from './stack-utils.js'
 
 describe('Error Classes', () => {
   test('ProcedureError has correct properties', () => {
@@ -51,3 +52,112 @@ describe('Error Classes', () => {
     expect(registrationErr.procedureName).toBe('Proc3')
   })
 })
+
+describe('Error Classes - Definition Info', () => {
+  const mockDefinitionInfo: DefinitionInfo = {
+    definedAt: {
+      file: '/app/procedures/user.ts',
+      line: 25,
+      column: 3,
+      raw: 'at Object.<anonymous> (/app/procedures/user.ts:25:3)',
+    },
+    definitionStack: 'Error\n    at Object.<anonymous> (/app/procedures/user.ts:25:3)',
+  }
+
+  test('ProcedureError includes definedAt when provided', () => {
+    const err = new ProcedureError('TestProc', 'Something failed', undefined, mockDefinitionInfo)
+
+    expect(err.definedAt).toBeDefined()
+    expect(err.definedAt?.file).toBe('/app/procedures/user.ts')
+    expect(err.definedAt?.line).toBe(25)
+    expect(err.definedAt?.column).toBe(3)
+  })
+
+  test('ProcedureError includes definitionStack when provided', () => {
+    const err = new ProcedureError('TestProc', 'Something failed', undefined, mockDefinitionInfo)
+
+    expect(err.definitionStack).toBeDefined()
+    expect(err.definitionStack).toContain('/app/procedures/user.ts')
+  })
+
+  test('ProcedureError works without definitionInfo (backward compat)', () => {
+    const err = new ProcedureError('TestProc', 'Something failed', { code: 123 })
+
+    expect(err.definedAt).toBeUndefined()
+    expect(err.definitionStack).toBeUndefined()
+    expect(err.procedureName).toBe('TestProc')
+    expect(err.message).toBe('Something failed')
+    expect(err.meta).toEqual({ code: 123 })
+  })
+
+  test('ProcedureValidationError includes definedAt when provided', () => {
+    const err = new ProcedureValidationError('TestProc', 'Validation failed', [], mockDefinitionInfo)
+
+    expect(err.definedAt).toBeDefined()
+    expect(err.definedAt?.file).toBe('/app/procedures/user.ts')
+    expect(err.definedAt?.line).toBe(25)
+  })
+
+  test('ProcedureValidationError works without definitionInfo (backward compat)', () => {
+    const err = new ProcedureValidationError('TestProc', 'Validation failed', [])
+
+    expect(err.definedAt).toBeUndefined()
+    expect(err.definitionStack).toBeUndefined()
+    expect(err.name).toBe('ProcedureValidationError')
+  })
+
+  test('ProcedureRegistrationError includes definedAt when provided', () => {
+    const err = new ProcedureRegistrationError('TestProc', 'Registration failed', mockDefinitionInfo)
+
+    expect(err.definedAt).toBeDefined()
+    expect(err.definedAt?.file).toBe('/app/procedures/user.ts')
+  })
+
+  test('ProcedureRegistrationError works without definitionInfo (backward compat)', () => {
+    const err = new ProcedureRegistrationError('TestProc', 'Registration failed')
+
+    expect(err.definedAt).toBeUndefined()
+    expect(err.definitionStack).toBeUndefined()
+    expect(err.name).toBe('ProcedureRegistrationError')
+  })
+
+  test('getDefinitionLocation returns formatted location string', () => {
+    const err = new ProcedureError('TestProc', 'Something failed', undefined, mockDefinitionInfo)
+
+    const location = err.getDefinitionLocation()
+
+    expect(location).toBe('/app/procedures/user.ts:25:3')
+  })
+
+  test('getDefinitionLocation returns undefined when no definedAt', () => {
+    const err = new ProcedureError('TestProc', 'Something failed')
+
+    const location = err.getDefinitionLocation()
+
+    expect(location).toBeUndefined()
+  })
+
+  test('enhanced stack contains definition location', () => {
+    const err = new ProcedureError('TestProc', 'Something failed', undefined, mockDefinitionInfo)
+
+    expect(err.stack).toContain('--- Procedure "TestProc" defined at ---')
+    expect(err.stack).toContain('/app/procedures/user.ts:25:3')
+  })
+
+  test('stack is not modified when no definitionInfo', () => {
+    const err = new ProcedureError('TestProc', 'Something failed')
+
+    expect(err.stack).toBeDefined()
+    expect(err.stack).not.toContain('--- Procedure')
+  })
+
+  test('all error types enhance stack with definition location', () => {
+    const baseErr = new ProcedureError('Proc1', 'message', undefined, mockDefinitionInfo)
+    const validationErr = new ProcedureValidationError('Proc2', 'message', [], mockDefinitionInfo)
+    const registrationErr = new ProcedureRegistrationError('Proc3', 'message', mockDefinitionInfo)
+
+    expect(baseErr.stack).toContain('--- Procedure "Proc1" defined at ---')
+    expect(validationErr.stack).toContain('--- Procedure "Proc2" defined at ---')
+    expect(registrationErr.stack).toContain('--- Procedure "Proc3" defined at ---')
+  })
+})

package/src/errors.ts

@@ -1,19 +1,58 @@
 import { TSchemaValidationError } from './schema/parser.js'
+import { DefinitionInfo, DefinitionLocation, formatDefinitionInfo } from './stack-utils.js'
 
 export class ProcedureError extends Error {
   cause?: unknown
+  readonly definedAt?: DefinitionLocation
+  readonly definitionStack?: string
 
   constructor(
     readonly procedureName: string,
     readonly message: string,
     readonly meta?: object,
+    // Used for error stack trace details
+    definitionInfo?: DefinitionInfo
   ) {
     super(message)
     this.name = 'ProcedureError'
 
+    if (definitionInfo) {
+      this.definedAt = definitionInfo.definedAt
+      this.definitionStack = definitionInfo.definitionStack
+      this.enhanceStack()
+    }
+
     // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
     Object.setPrototypeOf(this, ProcedureError.prototype)
   }
+
+  /**
+   * Returns a formatted string showing where the procedure was defined.
+   */
+  getDefinitionLocation(): string | undefined {
+    if (!this.definedAt) {
+      return undefined
+    }
+    return `${this.definedAt.file}:${this.definedAt.line}:${this.definedAt.column}`
+  }
+
+  /**
+   * Enhances the error stack with definition location information.
+   */
+  private enhanceStack(): void {
+    if (!this.stack || !this.definedAt) {
+      return
+    }
+
+    const definitionSection = formatDefinitionInfo(
+      { definedAt: this.definedAt, definitionStack: this.definitionStack },
+      this.procedureName
+    )
+
+    if (definitionSection) {
+      this.stack = this.stack + definitionSection
+    }
+  }
 }
 
 export class ProcedureValidationError extends ProcedureError {
@@ -21,8 +60,10 @@ export class ProcedureValidationError extends ProcedureError {
     readonly procedureName: string,
     message: string,
     readonly errors?: TSchemaValidationError[],
+    // Used for error stack trace details
+    definitionInfo?: DefinitionInfo
   ) {
-    super(procedureName, message)
+    super(procedureName, message, undefined, definitionInfo)
     this.name = 'ProcedureValidationError'
 
     // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
@@ -31,8 +72,13 @@ export class ProcedureValidationError extends ProcedureError {
 }
 
 export class ProcedureRegistrationError extends ProcedureError {
-  constructor(readonly procedureName: string, message: string) {
-    super(procedureName, message)
+  constructor(
+    readonly procedureName: string,
+    message: string,
+    // Used for error stack trace details
+    definitionInfo?: DefinitionInfo
+  ) {
+    super(procedureName, message, undefined, definitionInfo)
     this.name = 'ProcedureRegistrationError'
 
     // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/

package/src/exports.ts

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

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

@@ -626,6 +626,231 @@ describe('ExpressRPCAppBuilder', () => {
     })
   })
 
+  // --------------------------------------------------------------------------
+  // extendProcedureDoc Tests
+  // --------------------------------------------------------------------------
+  describe('extendProcedureDoc', () => {
+    test('adds custom properties to generated documentation', () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('GetUser', { scope: 'users', version: 1 }, async () => ({ name: 'test' }))
+
+      builder.register(
+        RPC,
+        () => ({}),
+        ({ base, procedure }) => ({
+          summary: `Get user endpoint`,
+          tags: ['users'],
+          operationId: procedure.name,
+        })
+      )
+      builder.build()
+
+      const doc = builder.docs[0]!
+      expect(doc).toHaveProperty('summary', 'Get user endpoint')
+      expect(doc).toHaveProperty('tags', ['users'])
+      expect(doc).toHaveProperty('operationId', 'GetUser')
+    })
+
+    test('receives correct base and procedure parameters', () => {
+      const extendFn = vi.fn(() => ({}))
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      const paramsSchema = v.object({ id: v.string() })
+      RPC.Create(
+        'GetItem',
+        { scope: 'items', version: 2, schema: { params: paramsSchema } },
+        async () => ({})
+      )
+
+      builder.register(RPC, () => ({}), extendFn)
+      builder.build()
+
+      expect(extendFn).toHaveBeenCalledTimes(1)
+      const callArg = extendFn.mock.calls[0]![0 as any] as any
+
+      // Verify base properties
+      expect(callArg.base).toHaveProperty('name', 'GetItem')
+      expect(callArg.base).toHaveProperty('version', 2)
+      expect(callArg.base).toHaveProperty('scope', 'items')
+      expect(callArg.base).toHaveProperty('path', '/items/get-item/2')
+      expect(callArg.base).toHaveProperty('method', 'post')
+      expect(callArg.base.jsonSchema).toHaveProperty('body')
+
+      // Verify procedure properties
+      expect(callArg.procedure).toHaveProperty('name', 'GetItem')
+      expect(callArg.procedure).toHaveProperty('handler')
+      expect(callArg.procedure.config).toHaveProperty('scope', 'items')
+      expect(callArg.procedure.config).toHaveProperty('version', 2)
+    })
+
+    test('base properties take precedence over extended properties', () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({}))
+
+      builder.register(
+        RPC,
+        () => ({}),
+        () => ({
+          name: 'OverriddenName',
+          path: '/overridden/path',
+          method: 'get',
+          customField: 'custom-value',
+        })
+      )
+      builder.build()
+
+      const doc = builder.docs[0]!
+      // Base properties should NOT be overridden
+      expect(doc.name).toBe('Test')
+      expect(doc.path).toBe('/test/test/1')
+      expect(doc.method).toBe('post')
+      // Custom field should be present
+      expect(doc).toHaveProperty('customField', 'custom-value')
+    })
+
+    test('different factories can have different extendProcedureDoc functions', () => {
+      const builder = new ExpressRPCAppBuilder()
+
+      const PublicRPC = Procedures<{}, RPCConfig>()
+      const AdminRPC = Procedures<{}, RPCConfig>()
+
+      PublicRPC.Create('GetPublic', { scope: 'public', version: 1 }, async () => ({}))
+      AdminRPC.Create('GetAdmin', { scope: 'admin', version: 1 }, async () => ({}))
+
+      builder
+        .register(
+          PublicRPC,
+          () => ({}),
+          () => ({
+            security: [],
+            tags: ['public'],
+          })
+        )
+        .register(
+          AdminRPC,
+          () => ({}),
+          () => ({
+            security: [{ bearerAuth: [] }],
+            tags: ['admin'],
+          })
+        )
+
+      builder.build()
+
+      const publicDoc = builder.docs.find((d) => d.name === 'GetPublic')!
+      const adminDoc = builder.docs.find((d) => d.name === 'GetAdmin')!
+
+      expect(publicDoc).toHaveProperty('security', [])
+      expect(publicDoc).toHaveProperty('tags', ['public'])
+      expect(adminDoc).toHaveProperty('security', [{ bearerAuth: [] }])
+      expect(adminDoc).toHaveProperty('tags', ['admin'])
+    })
+
+    test('extendProcedureDoc is called for each procedure in factory', () => {
+      const extendFn = vi.fn(() => ({ extended: true }))
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Method1', { scope: 'm1', version: 1 }, async () => ({}))
+      RPC.Create('Method2', { scope: 'm2', version: 1 }, async () => ({}))
+      RPC.Create('Method3', { scope: 'm3', version: 1 }, async () => ({}))
+
+      builder.register(RPC, () => ({}), extendFn)
+      builder.build()
+
+      expect(extendFn).toHaveBeenCalledTimes(3)
+
+      const procedureNames = extendFn.mock.calls.map((call: any) => call[0].procedure.name)
+      expect(procedureNames).toContain('Method1')
+      expect(procedureNames).toContain('Method2')
+      expect(procedureNames).toContain('Method3')
+    })
+
+    test('not providing extendProcedureDoc results in base documentation only', () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({}))
+
+      builder.register(RPC, () => ({})) // No extendProcedureDoc
+      builder.build()
+
+      const doc = builder.docs[0]!
+      expect(doc.name).toBe('Test')
+      expect(doc.path).toBe('/test/test/1')
+      expect(doc.method).toBe('post')
+      // Should not have any extra properties
+      expect(Object.keys(doc)).toEqual(['name', 'version', 'scope', 'path', 'method', 'jsonSchema'])
+    })
+
+    test('extendProcedureDoc can access procedure config for conditional logic', () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('PublicEndpoint', { scope: 'public', version: 1 }, async () => ({}))
+      RPC.Create('PrivateEndpoint', { scope: 'private', version: 1 }, async () => ({}))
+
+      builder.register(
+        RPC,
+        () => ({}),
+        ({ procedure }) => ({
+          isPublic: procedure.config.scope === 'public',
+          description: `This is a ${procedure.config.scope} endpoint`,
+        })
+      )
+      builder.build()
+
+      const publicDoc = builder.docs.find((d) => d.name === 'PublicEndpoint')!
+      const privateDoc = builder.docs.find((d) => d.name === 'PrivateEndpoint')!
+
+      expect(publicDoc).toHaveProperty('isPublic', true)
+      expect(publicDoc).toHaveProperty('description', 'This is a public endpoint')
+      expect(privateDoc).toHaveProperty('isPublic', false)
+      expect(privateDoc).toHaveProperty('description', 'This is a private endpoint')
+    })
+
+    test('extendProcedureDoc can use base jsonSchema for OpenAPI-style docs', () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      const paramsSchema = v.object({ userId: v.string() })
+      const returnSchema = v.object({ name: v.string(), email: v.string() })
+
+      RPC.Create(
+        'GetUser',
+        { scope: 'users', version: 1, schema: { params: paramsSchema, returnType: returnSchema } },
+        async () => ({ name: 'test', email: 'test@example.com' })
+      )
+
+      builder.register(
+        RPC,
+        () => ({}),
+        ({ base }) => ({
+          requestBody: base.jsonSchema.body
+            ? { content: { 'application/json': { schema: base.jsonSchema.body } } }
+            : undefined,
+          responses: {
+            200: base.jsonSchema.response
+              ? { content: { 'application/json': { schema: base.jsonSchema.response } } }
+              : { description: 'Success' },
+          },
+        })
+      )
+      builder.build()
+
+      const doc = builder.docs[0] as any
+      expect(doc).toHaveProperty('requestBody')
+      expect(doc.requestBody).toHaveProperty('content')
+      expect(doc).toHaveProperty('responses')
+      expect(doc.responses).toHaveProperty('200')
+    })
+  })
+
   // --------------------------------------------------------------------------
   // Integration Test
   // --------------------------------------------------------------------------