ts-procedures 3.1.0 → 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.1.0",
+  "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/index.test.ts

@@ -447,3 +447,129 @@ describe('Procedures', () => {
     }
   })
 })
+
+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('index.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('index.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('index.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(/index\.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)
+    }
+  })
+})

package/src/index.ts

@@ -1,6 +1,7 @@
 import { ProcedureError, ProcedureValidationError } from './errors.js'
 import { computeSchema } from './schema/compute-schema.js'
 import { Prettify, TJSONSchema, TSchemaLib } from './schema/types.js'
+import { captureDefinitionInfo } from './stack-utils.js'
 
 export type TNoContextProvided = unknown
 
@@ -68,16 +69,19 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
       params: TSchemaLib<TParams>
     ) => Promise<TSchemaLib<TReturnType>>
   ) {
+    // Capture definition location as first action
+    const definitionInfo = captureDefinitionInfo()
+
     // BEFORE computeSchema - fail fast on duplicate
     if (procedures.has(name)) {
       throw new Error(`Procedure with name ${name} is already registered`)
     }
 
-    const { jsonSchema, validations } = computeSchema(name, config.schema)
+    const { jsonSchema, validations } = computeSchema(name, config.schema, definitionInfo)
 
     // Create error factory once at registration time (outside handler)
     const errorFactory = (message: string, meta?: object) => {
-      return new ProcedureError(name, message, meta)
+      return new ProcedureError(name, message, meta, definitionInfo)
     }
 
     const registeredProcedure = {
@@ -101,7 +105,8 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
               throw new ProcedureValidationError(
                 name,
                 `Validation error for ${name} - ${errors.map((e) => e.message).join(', ')}`,
-                errors
+                errors,
+                definitionInfo
               )
             }
           }
@@ -121,9 +126,20 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
           if (error instanceof ProcedureError) {
             throw error
           } else {
-            const err = new ProcedureError(name, `Error in handler for ${name} - ${error?.message}`)
+            const err = new ProcedureError(
+              name,
+              `Error in handler for ${name} - ${error?.message}`,
+              undefined,
+              definitionInfo
+            )
             err.cause = error  // Preserve original error
-            err.stack = error.stack
+            // Preserve original stack but append definition info
+            if (error.stack && definitionInfo.definedAt) {
+              const { file, line, column } = definitionInfo.definedAt
+              err.stack = error.stack + `\n--- Procedure "${name}" defined at ---\n    at ${file}:${line}:${column}`
+            } else if (error.stack) {
+              err.stack = error.stack
+            }
             throw err
           }
         }

package/src/schema/compute-schema.ts

@@ -1,6 +1,7 @@
 import { schemaParser, TSchemaValidationError } from './parser.js'
 import { ProcedureRegistrationError } from '../errors.js'
 import { TJSONSchema } from './types.js'
+import { DefinitionInfo } from '../stack-utils.js'
 
 /**
  * This function is used to compute the JSON schema and validation functions
@@ -8,6 +9,7 @@ import { TJSONSchema } from './types.js'
  *
  * @param name The name of the procedure
  * @param schema Procedure schema
+ * @param definitionInfo Optional definition info for error reporting
  */
 export function computeSchema<TParamsSchemaType, TReturnTypeSchemaType>(
   name: string,
@@ -15,6 +17,8 @@ export function computeSchema<TParamsSchemaType, TReturnTypeSchemaType>(
     params?: TParamsSchemaType
     returnType?: TReturnTypeSchemaType
   },
+  // Used for error stack trace details
+  definitionInfo?: DefinitionInfo
 ): {
   jsonSchema: {
     params?: TJSONSchema
@@ -43,6 +47,7 @@ export function computeSchema<TParamsSchemaType, TReturnTypeSchemaType>(
         `Error parsing schema for ${name} - ${Object.entries(errors)
           .map(([key, error]) => `${key}: ${error}`)
           .join(', ')}`,
+        definitionInfo
       )
     })