tjs-lang 0.6.45 → 0.7.4

package/src/lang/runtime.test.ts

@@ -14,11 +14,15 @@ import {
   getStack,
   pushStack,
   popStack,
+  errors,
+  clearErrors,
+  getErrorCount,
   resetRuntime,
   enterUnsafe,
   exitUnsafe,
   isUnsafeMode,
   TJSError,
+  typeError,
   typeOf,
   isNativeType,
   Is,
@@ -953,3 +957,166 @@ describe('tjsEquals symbol protocol', () => {
     expect(tjsEquals).toBe(Symbol.for('tjs.equals'))
   })
 })
+
+describe('Error history ring buffer', () => {
+  beforeEach(() => {
+    resetRuntime()
+  })
+
+  afterEach(() => {
+    resetRuntime()
+  })
+
+  it('tracks errors by default', () => {
+    const err = typeError('fn.x', 'string', 42)
+    const recent = errors()
+    expect(recent).toHaveLength(1)
+    expect(recent[0]).toBe(err)
+  })
+
+  it('tracks multiple errors', () => {
+    typeError('fn.a', 'string', 1)
+    typeError('fn.b', 'number', 'x')
+    typeError('fn.c', 'boolean', null)
+    const recent = errors()
+    expect(recent).toHaveLength(3)
+    expect(recent[0].path).toBe('fn.a')
+    expect(recent[2].path).toBe('fn.c')
+  })
+
+  it('ring buffer wraps at maxErrors', () => {
+    configure({ maxErrors: 4 })
+    for (let i = 0; i < 6; i++) {
+      typeError(`fn.x${i}`, 'string', i)
+    }
+    const recent = errors()
+    expect(recent).toHaveLength(4)
+    // Should have the last 4 errors (x2..x5)
+    expect(recent[0].path).toBe('fn.x2')
+    expect(recent[3].path).toBe('fn.x5')
+  })
+
+  it('getErrorCount tracks total even after buffer wraps', () => {
+    configure({ maxErrors: 4 })
+    for (let i = 0; i < 10; i++) {
+      typeError('fn.x', 'string', i)
+    }
+    expect(getErrorCount()).toBe(10)
+    expect(errors()).toHaveLength(4)
+  })
+
+  it('clearErrors returns cleared errors and resets', () => {
+    typeError('fn.a', 'string', 1)
+    typeError('fn.b', 'number', 'x')
+    const cleared = clearErrors()
+    expect(cleared).toHaveLength(2)
+    expect(cleared[0].path).toBe('fn.a')
+    expect(errors()).toHaveLength(0)
+    expect(getErrorCount()).toBe(0)
+  })
+
+  it('can be disabled with configure', () => {
+    configure({ trackErrors: false })
+    typeError('fn.x', 'string', 42)
+    expect(errors()).toHaveLength(0)
+    expect(getErrorCount()).toBe(0)
+  })
+
+  it('resetRuntime clears error history', () => {
+    typeError('fn.x', 'string', 42)
+    expect(errors()).toHaveLength(1)
+    resetRuntime()
+    expect(errors()).toHaveLength(0)
+    expect(getErrorCount()).toBe(0)
+  })
+
+  it('zero cost on happy path', () => {
+    // No errors created — errors() should return empty
+    expect(errors()).toHaveLength(0)
+    expect(getErrorCount()).toBe(0)
+  })
+
+  it('catches unhandled errors from transpiled functions', () => {
+    const { tjs } = require('./index')
+    const savedTjs = globalThis.__tjs
+
+    try {
+      // installRuntime sets up globalThis.__tjs with the global runtime
+      // Emitted code calls createRuntime() to get a child — we need to
+      // access the child's error buffer via the __tjs local in the emitted code
+      const runtime = require('./runtime').createRuntime()
+      globalThis.__tjs = runtime
+
+      const result = tjs(`
+function greet(name: 'World'): 'Hello, World' {
+  return 'Hello, ' + name
+}
+
+function process(x: 0): 0 {
+  return x * 2
+}
+`)
+      // The emitted code creates its own child runtime via createRuntime().
+      // We need to capture that child's __tjs to check its error buffer.
+      const mod = new Function(
+        result.code + '\nreturn { greet, process, __tjs }'
+      )()
+
+      // Clear any errors from transpilation
+      mod.__tjs.clearErrors()
+
+      // Call with correct types — no errors
+      mod.greet('Alice')
+      mod.process(5)
+      expect(mod.__tjs.errors()).toHaveLength(0)
+
+      // Call with wrong type — error returned but not checked
+      mod.greet(42) // returns MonadicError, caller ignores it
+      mod.process('not a number') // same
+
+      // The errors are captured in history even though nobody checked them
+      const recent = mod.__tjs.errors()
+      expect(recent).toHaveLength(2)
+      expect(recent[0].path).toContain('greet.name')
+      expect(recent[0].expected).toBe('string')
+      expect(recent[1].path).toContain('process.x')
+      expect(recent[1].expected).toBe('integer')
+    } finally {
+      globalThis.__tjs = savedTjs
+    }
+  })
+
+  it('supports the test workflow: clear, run, check', () => {
+    const { tjs } = require('./index')
+    const savedTjs = globalThis.__tjs
+
+    try {
+      const runtime = require('./runtime').createRuntime()
+      globalThis.__tjs = runtime
+
+      const result = tjs(`
+function add(a: 1, b: 2): 3 {
+  return a + b
+}
+`)
+      const mod = new Function(result.code + '\nreturn { add, __tjs }')()
+
+      // Test workflow: clear → run → check for unexpected errors
+      mod.__tjs.clearErrors()
+
+      mod.add(10, 20) // correct types
+      mod.add(1, 2) // correct types
+
+      expect(mod.__tjs.errors()).toHaveLength(0)
+      expect(mod.__tjs.getErrorCount()).toBe(0)
+
+      // Now introduce a bad call
+      mod.add('x', 'y') // wrong types
+
+      expect(mod.__tjs.errors()).toHaveLength(1)
+      expect(mod.__tjs.getErrorCount()).toBe(1)
+    } finally {
+      globalThis.__tjs = savedTjs
+    }
+  })
+})

package/src/lang/runtime.ts

@@ -11,6 +11,7 @@
  */
 
 import { validate, s } from 'tosijs-schema'
+import { functionMetaToJSONSchema } from './json-schema'
 import {
   Type,
   isRuntimeType,
@@ -180,7 +181,7 @@ export function typeError(
 ): MonadicError {
   const actual = value === null ? 'null' : typeof value
   // Capture call stack in debug mode (getStack returns [] if not in debug mode)
-  const stack = config.debug ? getStack() : undefined
+  const stack = config.callStacks || config.debug ? getStack() : undefined
   const err = new MonadicError(
     `Expected ${expected} for '${path}', got ${actual}`,
     path,
@@ -189,6 +190,15 @@ export function typeError(
     stack
   )
 
+  // Track in error history ring buffer (zero cost on happy path)
+  if (config.trackErrors !== false) {
+    const size = config.maxErrors ?? ERROR_BUF_SIZE
+    errorBuffer[errorHead] = err
+    errorHead = (errorHead + 1) % size
+    if (errorBufCount < size) errorBufCount++
+    errorTotal++
+  }
+
   // Log to console if configured (includes source location from path)
   if (config.logTypeErrors) {
     console.error(`[TJS TypeError] ${err.message}`)
@@ -253,8 +263,18 @@ export interface TJSConfig {
   safety?: SafetyLevel
   /** Require explicit return types (error if -> not specified) */
   requireReturnTypes?: boolean
-  /** Maximum call stack size to prevent memory issues (default: 100) */
+  /** Track call stacks for error diagnostics (default: false).
+   *  Useful for server-side logging and agent debugging without devtools.
+   *  Uses a fixed ring buffer — no allocation pressure. */
+  callStacks?: boolean
+  /** Ring buffer size for call stack tracking (default: 64) */
   maxStackSize?: number
+  /** Track recent type errors in a ring buffer (default: true).
+   *  Zero cost on happy path — only writes when an error occurs.
+   *  Lets you catch monadic errors that were silently ignored. */
+  trackErrors?: boolean
+  /** Ring buffer size for error tracking (default: 64) */
+  maxErrors?: number
   /** Log type errors to console.error when they occur (default: false) */
   logTypeErrors?: boolean
   /** Throw type errors instead of returning them (default: false).
@@ -267,14 +287,27 @@ const DEFAULT_CONFIG: TJSConfig = {
   debug: false,
   safety: 'inputs',
   requireReturnTypes: false,
-  maxStackSize: 100,
+  callStacks: false,
+  maxStackSize: 64,
+  trackErrors: true,
+  maxErrors: 64,
 }
 
 /** Current runtime configuration */
 let config: TJSConfig = { ...DEFAULT_CONFIG }
 
-/** Current call stack (only tracked in debug mode) */
-const callStack: string[] = []
+/** Ring buffer for call stack tracking — fixed size, zero allocation */
+const STACK_SIZE = 64
+const callStackBuffer: string[] = new Array(STACK_SIZE).fill('')
+let callStackHead = 0
+let callStackCount = 0
+
+/** Ring buffer for error history — zero cost on happy path */
+const ERROR_BUF_SIZE = 64
+const errorBuffer: any[] = new Array(ERROR_BUF_SIZE).fill(null)
+let errorHead = 0
+let errorBufCount = 0
+let errorTotal = 0
 
 /** Unsafe mode depth - when > 0, skip validation in wrap() */
 let unsafeDepth = 0
@@ -316,45 +349,91 @@ export function getConfig(): TJSConfig {
 }
 
 /**
- * Push a function onto the call stack (debug mode only)
- * Respects maxStackSize to prevent unbounded memory growth
+ * Push a function onto the call stack ring buffer.
+ * Only tracks when callStacks or debug is enabled.
+ * O(1), no allocation.
  */
 export function pushStack(name: string): void {
-  if (config.debug && name) {
-    callStack.push(name)
-    // Enforce max stack size by removing oldest entries
-    const maxSize = config.maxStackSize ?? 100
-    while (callStack.length > maxSize) {
-      callStack.shift()
-    }
+  if ((config.callStacks || config.debug) && name) {
+    const size = config.maxStackSize ?? STACK_SIZE
+    callStackBuffer[callStackHead] = name
+    callStackHead = (callStackHead + 1) % size
+    if (callStackCount < size) callStackCount++
   }
 }
 
 /**
- * Pop a function from the call stack (debug mode only)
+ * Pop a function from the call stack ring buffer.
+ * O(1), no allocation.
  */
 export function popStack(): void {
-  if (config.debug) {
-    callStack.pop()
+  if ((config.callStacks || config.debug) && callStackCount > 0) {
+    const size = config.maxStackSize ?? STACK_SIZE
+    callStackHead = (callStackHead - 1 + size) % size
+    callStackCount--
   }
 }
 
 /**
- * Get current call stack snapshot
+ * Get current call stack snapshot (most recent entries, newest last)
  */
 export function getStack(): string[] {
-  return [...callStack]
+  if (callStackCount === 0) return []
+  const size = config.maxStackSize ?? STACK_SIZE
+  const result: string[] = []
+  const start = (callStackHead - callStackCount + size) % size
+  for (let i = 0; i < callStackCount; i++) {
+    result.push(callStackBuffer[(start + i) % size])
+  }
+  return result
+}
+
+/**
+ * Get recent type errors (newest last).
+ * Only tracks when trackErrors is enabled (default: true).
+ */
+export function errors(): MonadicError[] {
+  if (config.trackErrors === false || errorBufCount === 0) return []
+  const size = config.maxErrors ?? ERROR_BUF_SIZE
+  const result: MonadicError[] = []
+  const start = (errorHead - errorBufCount + size) % size
+  for (let i = 0; i < errorBufCount; i++) {
+    result.push(errorBuffer[(start + i) % size])
+  }
+  return result
+}
+
+/**
+ * Clear error history. Returns the cleared errors.
+ */
+export function clearErrors(): MonadicError[] {
+  const cleared = errors()
+  errorHead = 0
+  errorBufCount = 0
+  errorTotal = 0
+  return cleared
+}
+
+/**
+ * Total error count since last clear (may exceed buffer size).
+ */
+export function getErrorCount(): number {
+  return errorTotal
 }
 
 /**
  * Reset runtime state to defaults
  *
- * Resets: config, callStack, unsafeDepth
+ * Resets: config, callStack, errors, unsafeDepth
  * Use this in test teardown to prevent state leaking between tests.
  */
 export function resetRuntime(): void {
   config = { ...DEFAULT_CONFIG }
-  callStack.length = 0
+  callStackHead = 0
+  callStackCount = 0
+  errorHead = 0
+  errorBufCount = 0
+  errorTotal = 0
   unsafeDepth = 0
 }
 
@@ -522,20 +601,6 @@ export function TypeOf(value: unknown): string {
   return typeof value
 }
 
-/**
- * Check if a number is bounded (finite and not NaN).
- * The question you're actually asking when you reach for isNaN or isFinite.
- *
- * IsBounded(42)        → true
- * IsBounded(3.14)      → true
- * IsBounded(NaN)       → false
- * IsBounded(Infinity)  → false
- * IsBounded(-Infinity) → false
- * IsBounded('hello')   → false
- */
-export function IsBounded(value: unknown): boolean {
-  return typeof value === 'number' && isFinite(value) && !isNaN(value)
-}
 export function Eq(a: unknown, b: unknown): boolean {
   // Unwrap boxed primitives
   if (a instanceof String || a instanceof Number || a instanceof Boolean) {
@@ -600,12 +665,12 @@ export function error(
     ...details,
   }
 
-  // In debug mode, capture the call stack
-  if (config.debug && callStack.length > 0) {
-    // Add the path to the stack if it exists
+  // Capture call stack when tracking is enabled
+  if ((config.callStacks || config.debug) && callStackCount > 0) {
+    const currentStack = getStack()
     const fullStack = details?.path
-      ? [...callStack, details.path]
-      : [...callStack]
+      ? [...currentStack, details.path]
+      : currentStack
     err.stack = fullStack
   }
 
@@ -891,6 +956,8 @@ export function wrap<T extends (...args: any[]) => any>(
 ): T {
   // Always attach metadata for introspection/autocomplete
   ;(fn as any).__tjs = meta
+  // Lazy JSON Schema generation — only computed when called
+  ;(fn as any).__tjs.schema = () => functionMetaToJSONSchema(meta)
 
   // Determine if we need a wrapper at all
   // Polymorphic dispatchers handle their own routing — no wrapping needed
@@ -1035,8 +1102,9 @@ export function wrap<T extends (...args: any[]) => any>(
       }
     }
 
-    // Push onto call stack in debug mode
-    pushStack(funcName)
+    // Track call stack only when enabled (ring buffer, no allocation)
+    const trackStack = config.callStacks || config.debug
+    if (trackStack) pushStack(funcName)
 
     try {
       // Execute function
@@ -1055,15 +1123,15 @@ export function wrap<T extends (...args: any[]) => any>(
           `${funcName}()`
         )
         if (returnError) {
-          popStack()
+          if (trackStack) popStack()
           return returnError as ReturnType<T>
         }
       }
 
-      popStack()
+      if (trackStack) popStack()
       return result
     } catch (e) {
-      popStack()
+      if (trackStack) popStack()
       // Convert thrown errors to TJS errors
       return error((e as Error).message || String(e), {
         path: funcName,
@@ -1075,6 +1143,7 @@ export function wrap<T extends (...args: any[]) => any>(
   // Preserve function name and metadata
   Object.defineProperty(wrapped, 'name', { value: fn.name })
   ;(wrapped as any).__tjs = meta
+  ;(wrapped as any).__tjs.schema = () => functionMetaToJSONSchema(meta)
 
   return wrapped as T
 }
@@ -1147,7 +1216,15 @@ export function wrapClass<T extends new (...args: any[]) => any>(
 export function createRuntime() {
   // Per-instance state - inherit current global config
   let instanceConfig: TJSConfig = { ...config }
-  const instanceCallStack: string[] = []
+  const instStackSize = instanceConfig.maxStackSize ?? STACK_SIZE
+  const instanceStackBuffer: string[] = new Array(instStackSize).fill('')
+  let instanceStackHead = 0
+  let instanceStackCount = 0
+  const instErrorSize = instanceConfig.maxErrors ?? ERROR_BUF_SIZE
+  const instanceErrorBuffer: any[] = new Array(instErrorSize).fill(null)
+  let instanceErrorHead = 0
+  let instanceErrorBufCount = 0
+  let instanceErrorTotal = 0
   let instanceUnsafeDepth = 0
 
   // Per-instance stateful functions
@@ -1160,28 +1237,42 @@ export function createRuntime() {
   }
 
   function instancePushStack(name: string): void {
-    if (instanceConfig.debug && name) {
-      instanceCallStack.push(name)
-      const maxSize = instanceConfig.maxStackSize ?? 100
-      while (instanceCallStack.length > maxSize) {
-        instanceCallStack.shift()
-      }
+    if ((instanceConfig.callStacks || instanceConfig.debug) && name) {
+      instanceStackBuffer[instanceStackHead] = name
+      instanceStackHead = (instanceStackHead + 1) % instStackSize
+      if (instanceStackCount < instStackSize) instanceStackCount++
     }
   }
 
   function instancePopStack(): void {
-    if (instanceConfig.debug) {
-      instanceCallStack.pop()
+    if (
+      (instanceConfig.callStacks || instanceConfig.debug) &&
+      instanceStackCount > 0
+    ) {
+      instanceStackHead =
+        (instanceStackHead - 1 + instStackSize) % instStackSize
+      instanceStackCount--
     }
   }
 
   function instanceGetStack(): string[] {
-    return [...instanceCallStack]
+    if (instanceStackCount === 0) return []
+    const result: string[] = []
+    const start =
+      (instanceStackHead - instanceStackCount + instStackSize) % instStackSize
+    for (let i = 0; i < instanceStackCount; i++) {
+      result.push(instanceStackBuffer[(start + i) % instStackSize])
+    }
+    return result
   }
 
   function instanceResetRuntime(): void {
     instanceConfig = { ...DEFAULT_CONFIG }
-    instanceCallStack.length = 0
+    instanceStackHead = 0
+    instanceStackCount = 0
+    instanceErrorHead = 0
+    instanceErrorBufCount = 0
+    instanceErrorTotal = 0
     instanceUnsafeDepth = 0
   }
 
@@ -1267,7 +1358,10 @@ export function createRuntime() {
     value: unknown
   ): MonadicError {
     const actual = value === null ? 'null' : typeof value
-    const stack = instanceConfig.debug ? instanceGetStack() : undefined
+    const stack =
+      instanceConfig.callStacks || instanceConfig.debug
+        ? instanceGetStack()
+        : undefined
     const err = new MonadicError(
       `Expected ${expected} for '${path}', got ${actual}`,
       path,
@@ -1276,6 +1370,14 @@ export function createRuntime() {
       stack
     )
 
+    // Track in error history
+    if (instanceConfig.trackErrors !== false) {
+      instanceErrorBuffer[instanceErrorHead] = err
+      instanceErrorHead = (instanceErrorHead + 1) % instErrorSize
+      if (instanceErrorBufCount < instErrorSize) instanceErrorBufCount++
+      instanceErrorTotal++
+    }
+
     if (instanceConfig.logTypeErrors) {
       console.error(`[TJS TypeError] ${err.message}`)
     }
@@ -1286,6 +1388,31 @@ export function createRuntime() {
     return err
   }
 
+  function instanceErrors(): MonadicError[] {
+    if (instanceConfig.trackErrors === false || instanceErrorBufCount === 0)
+      return []
+    const result: MonadicError[] = []
+    const start =
+      (instanceErrorHead - instanceErrorBufCount + instErrorSize) %
+      instErrorSize
+    for (let i = 0; i < instanceErrorBufCount; i++) {
+      result.push(instanceErrorBuffer[(start + i) % instErrorSize])
+    }
+    return result
+  }
+
+  function instanceClearErrors(): MonadicError[] {
+    const cleared = instanceErrors()
+    instanceErrorHead = 0
+    instanceErrorBufCount = 0
+    instanceErrorTotal = 0
+    return cleared
+  }
+
+  function instanceGetErrorCount(): number {
+    return instanceErrorTotal
+  }
+
   function instanceError(
     message: string,
     details?: Partial<Omit<TJSError, '$error' | 'message'>>
@@ -1295,21 +1422,39 @@ export function createRuntime() {
       message,
       ...details,
     }
-    if (instanceConfig.debug && instanceCallStack.length > 0) {
+    if (
+      (instanceConfig.callStacks || instanceConfig.debug) &&
+      instanceStackCount > 0
+    ) {
       const fullStack = details?.path
-        ? [...instanceCallStack, details.path]
-        : [...instanceCallStack]
+        ? [...instanceGetStack(), details.path]
+        : instanceGetStack()
       err.stack = fullStack
     }
     return err
   }
 
+  /**
+   * Bang access (!.) — asserted non-null member access.
+   * Returns MonadicError if obj is null, undefined, or already a MonadicError.
+   * Otherwise returns obj[prop] (bare access — throws as usual on other errors).
+   */
+  function instanceBang(obj: unknown, prop: string): unknown {
+    if (obj === null || obj === undefined) {
+      return instanceTypeError(`bang.${prop}`, 'non-null', obj)
+    }
+    if (isMonadicError(obj)) return obj
+    return (obj as any)[prop]
+  }
+
   return {
     version: TJS_VERSION,
     // Monadic error handling
     MonadicError,
     typeError: instanceTypeError,
     isMonadicError,
+    // Bang access (!.)
+    bang: instanceBang,
     // Legacy error handling
     isError,
     error: instanceError,
@@ -1322,12 +1467,17 @@ export function createRuntime() {
     wrapClass,
     compareVersions,
     versionsCompatible,
+    // Create child runtime instances
+    createRuntime,
     // Debug mode (instance-specific)
     configure: instanceConfigure,
     getConfig: instanceGetConfig,
     pushStack: instancePushStack,
     popStack: instancePopStack,
     getStack: instanceGetStack,
+    errors: instanceErrors,
+    clearErrors: instanceClearErrors,
+    getErrorCount: instanceGetErrorCount,
     resetRuntime: instanceResetRuntime,
     // Unsafe mode (instance-specific)
     enterUnsafe: instanceEnterUnsafe,
@@ -1364,8 +1514,6 @@ export function createRuntime() {
     NotEq,
     // Honest typeof (typeof with TjsEquals)
     TypeOf,
-    // Number utilities
-    IsBounded,
     tjsEquals,
     // Extensions
     registerExtension: instanceRegisterExtension,
@@ -1406,6 +1554,9 @@ export const runtime = {
   pushStack,
   popStack,
   getStack,
+  errors,
+  clearErrors,
+  getErrorCount,
   resetRuntime,
   // Unsafe mode
   enterUnsafe,
@@ -1447,8 +1598,6 @@ export const runtime = {
   NotEq,
   // Honest typeof (used by typeof with TjsEquals)
   TypeOf,
-  // Number utilities
-  IsBounded,
 }
 
 /**