ts-procedures 3.1.0 → 3.3.0

package/build/schema/types.d.ts

@@ -1,6 +1,7 @@
 import { CoreValidator, TypeOf } from 'suretype';
 import { Static, TSchema } from 'typebox';
 export type TSchemaLib<SchemaLibType> = SchemaLibType extends CoreValidator<any> ? TypeOf<SchemaLibType> : SchemaLibType extends TSchema ? Static<SchemaLibType> : unknown;
+export type TSchemaLibGenerator<TYield, TReturn = void> = AsyncGenerator<TSchemaLib<TYield>, TSchemaLib<TReturn>, unknown>;
 export type TJSONSchema = Record<string, any>;
 export type Prettify<TObject> = {
     [Key in keyof TObject]: TObject[Key];

package/build/stack-utils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Represents a specific location in source code where a procedure was defined.
+ */
+export type DefinitionLocation = {
+    file: string;
+    line: number;
+    column: number;
+    raw: string;
+};
+/**
+ * Contains information about where a procedure was defined.
+ */
+export type DefinitionInfo = {
+    definedAt?: DefinitionLocation;
+    definitionStack?: string;
+};
+/**
+ * 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 declare function captureDefinitionInfo(): DefinitionInfo;
+/**
+ * Formats definition info for appending to error stacks.
+ */
+export declare function formatDefinitionInfo(info: DefinitionInfo, procedureName: string): string | undefined;

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.3.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,11 +72,32 @@ 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/
     Object.setPrototypeOf(this, ProcedureRegistrationError.prototype)
   }
 }
+
+export class ProcedureYieldValidationError extends ProcedureError {
+  constructor(
+    readonly procedureName: string,
+    message: string,
+    readonly errors?: TSchemaValidationError[],
+    // Used for error stack trace details
+    definitionInfo?: DefinitionInfo
+  ) {
+    super(procedureName, message, undefined, definitionInfo)
+    this.name = 'ProcedureYieldValidationError'
+
+    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
+    Object.setPrototypeOf(this, ProcedureYieldValidationError.prototype)
+  }
+}

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'