tjs-lang 0.7.3 → 0.7.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tjs-lang",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "Type-safe JavaScript dialect with runtime validation, sandboxed VM execution, and AI agent orchestration. Transpiles TypeScript to validated JS with fuel-metered execution for untrusted code.",
   "keywords": [
     "typescript",
@@ -31,22 +31,27 @@
     "./eval": {
       "bun": "./src/lang/eval.ts",
       "types": "./dist/src/lang/eval.d.ts",
-      "default": "./dist/lang/eval.js"
+      "default": "./dist/tjs-eval.js"
     },
     "./lang": {
-      "bun": "./src/lang/index.ts",
-      "types": "./dist/src/lang/index.d.ts",
-      "default": "./dist/lang/index.js"
-    },
-    "./lang/eval": {
-      "bun": "./src/lang/eval.ts",
-      "types": "./dist/src/lang/eval.d.ts",
-      "default": "./dist/lang/eval.js"
+      "bun": "./src/lang/transpiler.ts",
+      "types": "./dist/src/lang/transpiler.d.ts",
+      "default": "./dist/tjs-lang.js"
     },
     "./lang/from-ts": {
       "bun": "./src/lang/emitters/from-ts.ts",
       "types": "./dist/src/lang/emitters/from-ts.d.ts",
-      "default": "./dist/lang/emitters/from-ts.js"
+      "default": "./dist/tjs-from-ts.js"
+    },
+    "./vm": {
+      "bun": "./src/vm/index.ts",
+      "types": "./dist/src/vm/index.d.ts",
+      "default": "./dist/tjs-vm.js"
+    },
+    "./batteries": {
+      "bun": "./src/batteries/index.ts",
+      "types": "./dist/src/batteries/index.d.ts",
+      "default": "./dist/tjs-batteries.js"
     },
     "./src": "./src/index.ts",
     "./editors/monaco": "./editors/monaco/ajs-monarch.js",
@@ -94,6 +99,7 @@
     "acorn-walk": "^8.3.4",
     "chokidar": "^4.0.3",
     "codemirror": "^6.0.2",
+    "esbuild": "^0.28.0",
     "eslint": "^8.57.1",
     "firebase": "^10.12.0",
     "firebase-admin": "^13.6.0",

package/src/lang/emitters/js.ts

@@ -822,8 +822,8 @@ export function transpileToJS(
     // Core: MonadicError + typeError (needed by almost all validated functions)
     if (needsTypeError) {
       inlineParts.push(
-        `class MonadicError extends Error{constructor(m,p,e,a,c){super(m);this.name='MonadicError';this.path=p;this.expected=e;this.actual=a;this.callStack=c}}`,
-        `function typeError(p,e,v){const a=v===null?'null':typeof v;const err=new MonadicError('Expected '+e+" for '"+p+"', got "+a,p,e,a);const c=globalThis.__tjs?.getConfig?.();if(c?.logTypeErrors)console.error('[TJS TypeError] '+err.message);if(c?.throwTypeErrors)throw err;return err}`,
+        `class MonadicError extends Error{constructor(m,p,e,a,c,r){super(m);this.name='MonadicError';this.path=p;this.expected=e;this.actual=a;this.callStack=c;this.reason=r}}`,
+        `function typeError(p,e,v,r){const a=v===null?'null':typeof v;const m=r?'Expected '+e+" for '"+p+"': "+r:'Expected '+e+" for '"+p+"', got "+a;const err=new MonadicError(m,p,e,a,undefined,r);const c=globalThis.__tjs?.getConfig?.();if(c?.logTypeErrors)console.error('[TJS TypeError] '+err.message);if(c?.throwTypeErrors)throw err;return err}`,
         `function isMonadicError(v){return v instanceof Error&&v.name==='MonadicError'&&'path' in v}`
       )
     }
@@ -892,8 +892,8 @@ export function transpileToJS(
       // bang depends on typeError and isMonadicError — ensure they're inlined
       if (!needsTypeError) {
         inlineParts.push(
-          `class MonadicError extends Error{constructor(m,p,e,a,c){super(m);this.name='MonadicError';this.path=p;this.expected=e;this.actual=a;this.callStack=c}}`,
-          `function typeError(p,e,v){const a=v===null?'null':typeof v;const err=new MonadicError('Expected '+e+" for '"+p+"', got "+a,p,e,a);const c=globalThis.__tjs?.getConfig?.();if(c?.logTypeErrors)console.error('[TJS TypeError] '+err.message);if(c?.throwTypeErrors)throw err;return err}`,
+          `class MonadicError extends Error{constructor(m,p,e,a,c,r){super(m);this.name='MonadicError';this.path=p;this.expected=e;this.actual=a;this.callStack=c;this.reason=r}}`,
+          `function typeError(p,e,v,r){const a=v===null?'null':typeof v;const m=r?'Expected '+e+" for '"+p+"': "+r:'Expected '+e+" for '"+p+"', got "+a;const err=new MonadicError(m,p,e,a,undefined,r);const c=globalThis.__tjs?.getConfig?.();if(c?.logTypeErrors)console.error('[TJS TypeError] '+err.message);if(c?.throwTypeErrors)throw err;return err}`,
           `function isMonadicError(v){return v instanceof Error&&v.name==='MonadicError'&&'path' in v}`
         )
       }

package/src/lang/function-predicate.test.ts

@@ -12,9 +12,11 @@ describe('FunctionPredicate runtime', () => {
     })
     expect(Callback.check(() => {})).toBe(true)
     expect(Callback.check((x: number) => String(x))).toBe(true)
-    expect(Callback.check(42)).toBe(false)
-    expect(Callback.check('not a function')).toBe(false)
-    expect(Callback.check(null)).toBe(false)
+    expect(Callback.check(42)).toBe('expected function, got number')
+    expect(Callback.check('not a function')).toBe(
+      'expected function, got string'
+    )
+    expect(Callback.check(null)).toBe('expected function, got null')
   })
 
   it('should create from existing typed function', () => {
@@ -73,7 +75,7 @@ describe('FunctionPredicate runtime', () => {
         x: { type: { kind: 'integer' }, example: 0 },
       },
     }
-    expect(Binop.check(wrongArity)).toBe(false)
+    expect(Binop.check(wrongArity)).toBe('expected 2 params, got 1')
   })
 
   it('should reject function with wrong param types via __tjs metadata', () => {
@@ -93,7 +95,7 @@ describe('FunctionPredicate runtime', () => {
     ;(badFn as any).__tjs = {
       params: { n: { type: { kind: 'integer' }, example: 0 } },
     }
-    expect(StrFn.check(badFn)).toBe(false)
+    expect(StrFn.check(badFn)).toBe("param 'name' expected string, got integer")
   })
 
   it('should accept function with any-typed params', () => {
@@ -230,7 +232,7 @@ describe('Generic FunctionPredicate runtime', () => {
     expect(StringCreator.returns).toBe('')
     expect(StringCreator.params.x).toBe('')
     expect(StringCreator.check(() => {})).toBe(true)
-    expect(StringCreator.check(42)).toBe(false)
+    expect(StringCreator.check(42)).toBe('expected function, got number')
   })
 
   it('should use default type arg when none provided', () => {

package/src/lang/runtime.test.ts

@@ -28,6 +28,9 @@ import {
   Is,
   IsNot,
   tjsEquals,
+  checkType,
+  MonadicError,
+  isMonadicError,
 } from './runtime'
 import { Eval, SafeFunction } from './eval'
 
@@ -1120,3 +1123,58 @@ function add(a: 1, b: 2): 3 {
     }
   })
 })
+
+describe('predicate reason strings', () => {
+  it('typeError includes reason in message and field', () => {
+    const err = typeError('foo.bar', 'even number', 3, 'value is odd')
+    expect(err.message).toContain('value is odd')
+    expect(err.message).toContain('foo.bar')
+    expect(err.reason).toBe('value is odd')
+    expect(isMonadicError(err)).toBe(true)
+  })
+
+  it('typeError without reason works as before', () => {
+    const err = typeError('foo.bar', 'string', 42)
+    expect(err.message).toContain('got number')
+    expect(err.reason).toBeUndefined()
+  })
+
+  it('checkType captures reason from predicate', () => {
+    const EvenType = {
+      check: (v: unknown): boolean | string => {
+        if (typeof v !== 'number') return `expected number, got ${typeof v}`
+        if (v % 2 !== 0) return `${v} is odd`
+        return true
+      },
+      description: 'even number',
+    }
+
+    // Pass
+    expect(checkType(4, EvenType, 'test.val')).toBeNull()
+
+    // Fail with reason
+    const err = checkType(3, EvenType, 'test.val')
+    expect(err).not.toBeNull()
+    expect(err!.message).toContain('3 is odd')
+    expect(err!.reason).toBe('3 is odd')
+
+    // Fail with different reason
+    const err2 = checkType('x', EvenType, 'test.val')
+    expect(err2).not.toBeNull()
+    expect(err2!.message).toContain('expected number, got string')
+  })
+
+  it('checkType works with boolean-only predicates', () => {
+    const PositiveType = {
+      check: (v: unknown) => typeof v === 'number' && v > 0,
+      description: 'positive number',
+    }
+
+    expect(checkType(5, PositiveType, 'x')).toBeNull()
+
+    const err = checkType(-1, PositiveType, 'x')
+    expect(err).not.toBeNull()
+    expect(err!.message).toContain('positive number')
+    expect(err!.reason).toBeUndefined()
+  })
+})

package/src/lang/runtime.ts

@@ -142,13 +142,16 @@ export class MonadicError extends Error {
   readonly actual?: string
   /** TJS call stack (only in debug mode) - shows source locations */
   readonly callStack?: string[]
+  /** Why the check failed (from predicate reason strings) */
+  readonly reason?: string
 
   constructor(
     message: string,
     path: string,
     expected?: string,
     actual?: string,
-    callStack?: string[]
+    callStack?: string[],
+    reason?: string
   ) {
     super(message)
     this.name = 'MonadicError'
@@ -156,6 +159,7 @@ export class MonadicError extends Error {
     this.expected = expected
     this.actual = actual
     this.callStack = callStack
+    this.reason = reason
     // Maintains proper stack trace in V8 environments
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, MonadicError)
@@ -177,18 +181,16 @@ export class MonadicError extends Error {
 export function typeError(
   path: string,
   expected: string,
-  value: unknown
+  value: unknown,
+  reason?: string
 ): MonadicError {
   const actual = value === null ? 'null' : typeof value
   // Capture call stack in debug mode (getStack returns [] if not in debug mode)
   const stack = config.callStacks || config.debug ? getStack() : undefined
-  const err = new MonadicError(
-    `Expected ${expected} for '${path}', got ${actual}`,
-    path,
-    expected,
-    actual,
-    stack
-  )
+  const msg = reason
+    ? `Expected ${expected} for '${path}': ${reason}`
+    : `Expected ${expected} for '${path}', got ${actual}`
+  const err = new MonadicError(msg, path, expected, actual, stack, reason)
 
   // Track in error history ring buffer (zero cost on happy path)
   if (config.trackErrors !== false) {
@@ -238,6 +240,8 @@ export interface TJSError {
   stack?: string[]
   expected?: string
   actual?: string
+  /** Why the check failed (from predicate reason strings) */
+  reason?: string
   cause?: Error | TJSError
   /** Source location for error reporting */
   loc?: { start: number; end: number }
@@ -779,7 +783,9 @@ export function isNativeType(value: unknown, typeName: string): boolean {
  */
 export function checkType(
   value: unknown,
-  expected: string | { check: (v: unknown) => boolean; description: string },
+  expected:
+    | string
+    | { check: (v: unknown) => boolean | string; description: string },
   path?: string
 ): TJSError | null {
   // If value is already an error, propagate it
@@ -791,11 +797,17 @@ export function checkType(
     expected !== null &&
     'check' in expected
   ) {
-    if (expected.check(value)) return null
-    return error(`Expected ${expected.description} but got ${typeOf(value)}`, {
+    const result = expected.check(value)
+    if (result === true) return null
+    const reason = typeof result === 'string' ? result : undefined
+    const msg = reason
+      ? `Expected ${expected.description} for '${path}': ${reason}`
+      : `Expected ${expected.description} but got ${typeOf(value)}`
+    return error(msg, {
       path,
       expected: expected.description,
       actual: typeOf(value),
+      reason,
     })
   }
 
@@ -828,7 +840,9 @@ export function checkType(
 }
 
 /** Type specifier - either a string name or a RuntimeType */
-type TypeSpec = string | { check: (v: unknown) => boolean; description: string }
+type TypeSpec =
+  | string
+  | { check: (v: unknown) => boolean | string; description: string }
 
 /** Parameter metadata with optional location */
 interface ParamMeta {

package/src/types/Type.test.ts

@@ -207,8 +207,8 @@ describe('Built-in Types', () => {
   it('TString validates strings', () => {
     expect(TString.check('hello')).toBe(true)
     expect(TString.check('')).toBe(true)
-    expect(TString.check(123)).toBe(false)
-    expect(TString.check(null)).toBe(false)
+    expect(TString.check(123)).toBe('expected string, got number')
+    expect(TString.check(null)).toBe('expected string, got null')
   })
 
   it('TNumber validates numbers', () => {
@@ -216,60 +216,64 @@ describe('Built-in Types', () => {
     expect(TNumber.check(0)).toBe(true)
     expect(TNumber.check(-1.5)).toBe(true)
     expect(TNumber.check(NaN)).toBe(true) // NaN is typeof number
-    expect(TNumber.check('123')).toBe(false)
+    expect(TNumber.check('123')).toBe('expected number, got string')
   })
 
   it('TBoolean validates booleans', () => {
     expect(TBoolean.check(true)).toBe(true)
     expect(TBoolean.check(false)).toBe(true)
-    expect(TBoolean.check(1)).toBe(false)
-    expect(TBoolean.check('true')).toBe(false)
+    expect(TBoolean.check(1)).toBe('expected boolean, got number')
+    expect(TBoolean.check('true')).toBe('expected boolean, got string')
   })
 
   it('TInteger validates integers', () => {
     expect(TInteger.check(1)).toBe(true)
     expect(TInteger.check(0)).toBe(true)
     expect(TInteger.check(-5)).toBe(true)
-    expect(TInteger.check(1.5)).toBe(false)
-    expect(TInteger.check('1')).toBe(false)
+    expect(TInteger.check(1.5)).toBe('1.5 is not an integer')
+    expect(TInteger.check('1')).toBe('expected integer, got string')
   })
 
   it('TPositiveInt validates positive integers', () => {
     expect(TPositiveInt.check(1)).toBe(true)
     expect(TPositiveInt.check(100)).toBe(true)
-    expect(TPositiveInt.check(0)).toBe(false)
-    expect(TPositiveInt.check(-1)).toBe(false)
-    expect(TPositiveInt.check(1.5)).toBe(false)
+    expect(TPositiveInt.check(0)).toBe('0 is not positive')
+    expect(TPositiveInt.check(-1)).toBe('-1 is not positive')
+    expect(TPositiveInt.check(1.5)).toBe('1.5 is not an integer')
   })
 
   it('TNonEmptyString validates non-empty strings', () => {
     expect(TNonEmptyString.check('hello')).toBe(true)
     expect(TNonEmptyString.check('a')).toBe(true)
-    expect(TNonEmptyString.check('')).toBe(false)
-    expect(TNonEmptyString.check(123)).toBe(false)
+    expect(TNonEmptyString.check('')).toBe('string is empty')
+    expect(TNonEmptyString.check(123)).toBe('expected string, got number')
   })
 
   it('TEmail validates email addresses', () => {
     expect(TEmail.check('user@example.com')).toBe(true)
     expect(TEmail.check('a@b.c')).toBe(true)
-    expect(TEmail.check('invalid')).toBe(false)
-    expect(TEmail.check('no@domain')).toBe(false)
-    expect(TEmail.check('@example.com')).toBe(false)
+    expect(TEmail.check('invalid')).toBe('"invalid" is not a valid email')
+    expect(TEmail.check('no@domain')).toBe('"no@domain" is not a valid email')
+    expect(TEmail.check('@example.com')).toBe(
+      '"@example.com" is not a valid email'
+    )
   })
 
   it('TUrl validates URLs', () => {
     expect(TUrl.check('https://example.com')).toBe(true)
     expect(TUrl.check('http://localhost:3000')).toBe(true)
     expect(TUrl.check('ftp://files.example.com')).toBe(true)
-    expect(TUrl.check('not-a-url')).toBe(false)
-    expect(TUrl.check('example.com')).toBe(false)
+    expect(TUrl.check('not-a-url')).toBe('"not-a-url" is not a valid URL')
+    expect(TUrl.check('example.com')).toBe('"example.com" is not a valid URL')
   })
 
   it('TUuid validates UUIDs', () => {
     expect(TUuid.check('550e8400-e29b-41d4-a716-446655440000')).toBe(true)
     expect(TUuid.check('550E8400-E29B-41D4-A716-446655440000')).toBe(true)
-    expect(TUuid.check('not-a-uuid')).toBe(false)
-    expect(TUuid.check('550e8400-e29b-41d4-a716')).toBe(false)
+    expect(TUuid.check('not-a-uuid')).toBe('"not-a-uuid" is not a valid UUID')
+    expect(TUuid.check('550e8400-e29b-41d4-a716')).toBe(
+      '"550e8400-e29b-41d4-a716" is not a valid UUID'
+    )
   })
 })
 
@@ -676,3 +680,48 @@ describe('Enum', () => {
     expect(HttpStatus.members.NotFound).toBe(404)
   })
 })
+
+describe('predicate reason strings', () => {
+  it('Type() passes through reason strings from predicates', () => {
+    const EvenNumber = Type<number>('even number', (v: unknown) => {
+      if (typeof v !== 'number') return 'not a number'
+      if (v % 2 !== 0) return `${v} is odd`
+      return true
+    })
+
+    expect(EvenNumber.check(4)).toBe(true)
+    expect(EvenNumber.check(3)).toBe('3 is odd')
+    expect(EvenNumber.check('x')).toBe('not a number')
+  })
+
+  it('schema-based types still return boolean', () => {
+    const StringType = Type('a string', s.string)
+    expect(StringType.check('hello')).toBe(true)
+    expect(StringType.check(42)).toBe(false)
+  })
+
+  it('Nullable correctly handles reason-returning predicates', () => {
+    const EvenNumber = Type<number>('even number', (v: unknown) => {
+      if (typeof v !== 'number') return 'not a number'
+      if (v % 2 !== 0) return `${v} is odd`
+      return true
+    })
+    const NullableEven = Nullable(EvenNumber)
+
+    expect(NullableEven.check(null)).toBe(true)
+    expect(NullableEven.check(4)).toBe(true)
+    expect(NullableEven.check(3)).toBe(false) // reason lost in combinator, but correctly fails
+  })
+
+  it('TArray correctly handles reason-returning predicates', () => {
+    const Positive = Type<number>('positive', (v: unknown) => {
+      if (typeof v !== 'number') return 'not a number'
+      if (v <= 0) return `${v} is not positive`
+      return true
+    })
+    const PositiveArray = TArray(Positive)
+
+    expect(PositiveArray.check([1, 2, 3])).toBe(true)
+    expect(PositiveArray.check([1, -1, 3])).toBe(false)
+  })
+})