tjs-lang 0.5.2 → 0.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tjs-lang",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "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",

package/src/lang/codegen.test.ts

@@ -28,11 +28,11 @@ describe('TS → TJS conversion quality', () => {
       expect(code).not.toContain('x: number')
     })
 
-    it('converts optional param to equals syntax', () => {
+    it('converts optional param to union with undefined', () => {
       const ts = `function greet(name?: string): string { return name || 'World' }`
       const { code } = fromTS(ts, { emitTJS: true })
 
-      expect(code).toContain("name = ''")
+      expect(code).toContain("name: '' | undefined")
       expect(code).not.toContain('name?')
     })
 
@@ -47,7 +47,14 @@ describe('TS → TJS conversion quality', () => {
       const ts = `function toggle(flag: boolean): boolean { return !flag }`
       const { code } = fromTS(ts, { emitTJS: true })
 
-      expect(code).toContain('flag: true')
+      expect(code).toContain('flag: false')
+    })
+
+    it('converts optional boolean param to union with undefined', () => {
+      const ts = `function greet(name: string, excited?: boolean): string { return excited ? name + '!' : name }`
+      const { code } = fromTS(ts, { emitTJS: true })
+
+      expect(code).toContain('excited: false | undefined')
     })
 
     it('converts array param correctly', () => {
@@ -78,7 +85,7 @@ describe('TS → TJS conversion quality', () => {
       const { code } = fromTS(ts, { emitTJS: true })
 
       expect(code).toContain("url: ''")
-      expect(code).toContain('timeout = 0')
+      expect(code).toContain('timeout: 0.0 | undefined')
     })
   })
 
@@ -101,7 +108,7 @@ describe('TS → TJS conversion quality', () => {
       const ts = `function isValid(): boolean { return true }`
       const { code } = fromTS(ts, { emitTJS: true })
 
-      expect(code).toContain('-! true')
+      expect(code).toContain('-! false')
     })
 
     it('converts object return type to -! syntax', () => {
@@ -288,18 +295,18 @@ class Api {
   })
 
   describe('nullable types', () => {
-    it('converts T | null to T || null', () => {
+    it('converts T | null to T | null', () => {
       const ts = `function maybe(x: string | null): string | null { return x }`
       const { code } = fromTS(ts, { emitTJS: true })
 
-      expect(code).toContain("'' || null")
+      expect(code).toContain("'' | null")
     })
 
-    it('converts T | undefined to T || undefined', () => {
+    it('converts T | undefined to T | undefined', () => {
       const ts = `function maybe(x: number | undefined): number | undefined { return x }`
       const { code } = fromTS(ts, { emitTJS: true })
 
-      expect(code).toContain('0 || undefined')
+      expect(code).toContain('0 | undefined')
     })
   })
 
@@ -371,12 +378,21 @@ class Api {
 
 describe('TJS → JS transpilation quality', () => {
   describe('colon syntax transformation', () => {
-    it('transforms colon params to defaults in output', () => {
+    it('strips colon type annotations from output (required params get no default)', () => {
       const source = `function greet(name: 'World') { return name }`
       const { code } = tjs(source)
 
-      expect(code).toContain('name = ')
+      // Required params (`:` syntax) should have no default in JS
+      expect(code).toContain('function greet(name)')
       expect(code).not.toContain("name: 'World'")
+      expect(code).not.toContain('name = ')
+    })
+
+    it('preserves defaults for optional params (= syntax)', () => {
+      const source = `function greet(name = 'World') { return name }`
+      const { code } = tjs(source)
+
+      expect(code).toContain("name = 'World'")
     })
   })
 
@@ -624,12 +640,12 @@ console.log(second())
       expect(code).not.toContain('y: string')
     })
 
-    it('uses equals syntax for optional params', () => {
+    it('uses union with undefined for optional params', () => {
       const ts = `function test(x?: number, y?: string): void { }`
       const { code } = fromTS(ts, { emitTJS: true })
 
-      expect(code).toContain('x = 0')
-      expect(code).toContain("y = ''")
+      expect(code).toContain('x: 0.0 | undefined')
+      expect(code).toContain("y: '' | undefined")
     })
 
     it('uses -! syntax for return types (skip signature test)', () => {
@@ -1247,7 +1263,9 @@ function test(required: string, optional?: number): void { }
       const { types } = tjs(tjsCode)
 
       expect(types?.test?.params?.required?.required).toBe(true)
-      expect(types?.test?.params?.optional?.required).toBe(false)
+      // TS optional becomes TJS union with undefined (required param that accepts undefined)
+      expect(types?.test?.params?.optional?.required).toBe(true)
+      expect(types?.test?.params?.optional?.type?.kind).toBe('union')
     })
   })
 })
@@ -1780,7 +1798,7 @@ function format(x: '') -! '' { return x + '!' }
     })
 
     it('error short-circuits function body', () => {
-      let bodyExecuted = false
+      const bodyExecuted = false
 
       const { code } = tjs(`
 function process(x: '') -! '' {
@@ -1927,4 +1945,46 @@ function divide(a: 10, b: 2) -? { value: 0, error = '' } {
       expect(result.code).toContain('"error"')
     })
   })
+
+  describe('union param JS output', () => {
+    it('required union param has no default in JS', () => {
+      const result = tjs('function f(x: false | undefined) { return x }')
+      expect(result.code).toContain('function f(x)')
+      expect(result.code).not.toMatch(/x = false/)
+      expect(result.code).not.toMatch(/x = false \| undefined/)
+    })
+
+    it('optional union param keeps first value as default', () => {
+      const result = tjs('function f(x = false | undefined) { return x }')
+      expect(result.code).toContain('x = false')
+      expect(result.code).not.toMatch(/x = false \| undefined/)
+    })
+
+    it('generates union type check for required union param', () => {
+      const result = tjs('function f(x: false | undefined) { return x }')
+      expect(result.code).toContain("typeof x !== 'boolean'")
+      expect(result.code).toContain('x !== undefined')
+    })
+
+    it('generates nullable integer check for int|null', () => {
+      const result = tjs('function f(x: 0 | null) { return x }')
+      expect(result.code).toContain('function f(x)')
+      // 0 | null is parsed as { kind: 'integer', nullable: true }, not a union
+      expect(result.code).toContain("'integer'")
+      // Nullable types skip the check when value is null
+      expect(result.metadata?.f?.params?.x?.type?.nullable).toBe(true)
+    })
+
+    it('preserves | in function body (bitwise OR)', () => {
+      const result = tjs('function f(x: 0) { return x | 0xFF }')
+      expect(result.code).toContain('x | 0xFF')
+    })
+
+    it('preserves union metadata despite stripping from JS', () => {
+      const result = tjs('function f(x: false | undefined) { return x }')
+      const meta = result.metadata?.f
+      expect(meta).toBeDefined()
+      expect(meta.params.x.type.kind).toBe('union')
+    })
+  })
 })

package/src/lang/emitters/from-ts.ts

@@ -139,7 +139,7 @@ function typeToExample(
     case ts.SyntaxKind.NumberKeyword:
       return '0.0'
     case ts.SyntaxKind.BooleanKeyword:
-      return 'true'
+      return 'false'
     case ts.SyntaxKind.NullKeyword:
       return 'null'
     case ts.SyntaxKind.UndefinedKeyword:
@@ -296,10 +296,10 @@ function typeToExample(
       const hasUndefined = unionType.types.some(isUndefinedType)
 
       if (nonNullTypes.length === 1 && (hasNull || hasUndefined)) {
-        // Nullable type: T | null -> T || null
+        // Nullable type: T | null -> T | null
         const baseExample = typeToExample(nonNullTypes[0], checker)
-        if (hasNull) return `${baseExample} || null`
-        if (hasUndefined) return `${baseExample} || undefined`
+        if (hasNull) return `${baseExample} | null`
+        if (hasUndefined) return `${baseExample} | undefined`
       }
 
       // General union: use first type as example
@@ -916,7 +916,7 @@ function transformFunctionToTJS(
   warnings?: string[],
   includeLineNumber?: boolean
 ): string {
-  const params: string[] = []
+  const params = transformParams(node.parameters, sourceFile, warnings)
 
   // Get line number (1-indexed) for source mapping
   const { line } = sourceFile.getLineAndCharacterOfPosition(
@@ -924,27 +924,6 @@ function transformFunctionToTJS(
   )
   const lineComment = includeLineNumber ? `/* line ${line + 1} */\n` : ''
 
-  for (const param of node.parameters) {
-    const name = param.name.getText(sourceFile)
-    const isOptional = !!param.questionToken || !!param.initializer
-    const typeExample = typeToExample(param.type, undefined, warnings)
-
-    if (param.initializer) {
-      // Has default value - use it directly
-      const defaultText = param.initializer.getText(sourceFile)
-      params.push(`${name} = ${defaultText}`)
-    } else if (typeExample === 'any' || typeExample === 'undefined') {
-      // any/undefined type - no annotation in TJS (bare name means any)
-      params.push(name)
-    } else if (isOptional) {
-      // Optional without default - use = for optional
-      params.push(`${name} = ${typeExample}`)
-    } else {
-      // Required - use : for required
-      params.push(`${name}: ${typeExample}`)
-    }
-  }
-
   const funcName =
     explicitName ||
     (ts.isFunctionDeclaration(node) && node.name
@@ -1203,8 +1182,9 @@ function transformParams(
       // any/undefined type - no annotation in TJS (bare name means any)
       params.push(name)
     } else if (isOptional) {
-      // Optional without default - use = for optional
-      params.push(`${name} = ${typeExample}`)
+      // Optional without default - use union with undefined to preserve
+      // three-state semantics (e.g. TS `flag?: boolean` can be true/false/undefined)
+      params.push(`${name}: ${typeExample} | undefined`)
     } else {
       // Required - use : for required
       params.push(`${name}: ${typeExample}`)

package/src/lang/emitters/js.ts

@@ -139,6 +139,26 @@ export interface TJSTypeInfo {
   destructuredRequired?: Set<string>
 }
 
+/**
+ * Check if a param used `:` (required) or `=` (optional) in the raw source.
+ * Finds the function's param list by name, then looks for `paramName:` vs `paramName =`.
+ */
+function isParamRequiredInSource(
+  source: string,
+  funcName: string,
+  paramName: string
+): boolean {
+  if (!source || !funcName) return false
+  // Find the function declaration and its param list
+  const funcPattern = new RegExp(
+    `function\\s+${funcName}\\s*\\([^)]*?\\b${paramName}\\s*([=:])`,
+    's'
+  )
+  const match = source.match(funcPattern)
+  if (!match) return false
+  return match[1] === ':'
+}
+
 /**
  * Extract type info for a single function declaration
  */
@@ -146,7 +166,8 @@ function extractFunctionTypeInfo(
   func: FunctionDeclaration,
   originalSource: string,
   requiredParams: Set<string>,
-  returnTypeStr: string | null
+  returnTypeStr: string | null,
+  inputSource?: string
 ): { types: TJSTypeInfo; warnings: string[] } {
   const warnings: string[] = []
 
@@ -205,9 +226,19 @@ function extractFunctionTypeInfo(
         param.left.type === 'Identifier'
       ) {
         const paramInfo = parseParameter(param, requiredParams)
+        // Determine if this param used `:` (required) or `=` (optional).
+        // The global requiredParams set is name-based, which fails when
+        // two functions share a param name with different syntax.
+        // Use the raw input source to check the actual syntax.
+        const isRequired = isParamRequiredInSource(
+          inputSource || '',
+          func.id?.name || '',
+          param.left.name
+        )
         params[param.left.name] = {
           ...paramInfo,
-          required: requiredParams.has(param.left.name),
+          required: isRequired,
+          default: isRequired ? null : paramInfo.example ?? paramInfo.default,
           description: tdoc.params[param.left.name],
         }
       } else if (param.type === 'ObjectPattern') {
@@ -346,7 +377,10 @@ function generateInlineValidationCode(
     const typeCheck = generateTypeCheckExpr(paramName, param.type)
 
     if (typeCheck) {
-      const expectedType = param.type.kind
+      const expectedType =
+        param.type.kind === 'union'
+          ? (param.type as any).members.map((m: any) => m.kind).join(' | ')
+          : param.type.kind
       if (param.required) {
         lines.push(
           `if (${typeCheck}) return __tjs.typeError('${path}', '${expectedType}', ${paramName});`
@@ -533,6 +567,9 @@ export function transpileToJS(
 
   // Collect insertions: { position, text } to be applied in reverse order
   const insertions: { position: number; text: string }[] = []
+  // Collect deletions for | union suffixes in param defaults
+  // e.g. `x = false | undefined` -> `x = false` (the `| undefined` is type-only)
+  const deletions: { start: number; end: number }[] = []
 
   // Process each function
   for (const func of functions) {
@@ -564,11 +601,40 @@ export function transpileToJS(
       func,
       originalSource,
       requiredParams,
-      returnTypeStr
+      returnTypeStr,
+      cleanSource
     )
     warnings.push(...funcWarnings)
     allTypes[funcName] = types
 
+    // Clean up param defaults in the emitted JS.
+    // After colon→equals transform, `x: false | undefined` becomes
+    // `x = false | undefined` in the parsed source.
+    // - For required params (`:` syntax), strip the entire `= value` — there's
+    //   no JS default for required params, the value is a type annotation only.
+    // - For union defaults, strip just the `| suffix` to avoid bitwise OR.
+    for (const param of func.params) {
+      if (param.type === 'AssignmentPattern') {
+        const paramName =
+          (param as any).left?.name || (param as any).left?.value
+        const paramInfo = paramName ? types.params[paramName] : null
+
+        if (paramInfo?.required && paramInfo.default === null) {
+          // Required param — strip entire `= value` from JS output
+          deletions.push({
+            start: (param as any).left.end,
+            end: (param as any).right.end,
+          })
+        } else {
+          // Optional param with union — strip just the `| suffix`
+          const right = (param as any).right
+          if (right.type === 'BinaryExpression' && right.operator === '|') {
+            deletions.push({ start: right.left.end, end: right.end })
+          }
+        }
+      }
+    }
+
     // Determine safety options
     // Module-level "safety none" makes ALL functions unsafe (no validation)
     const isUnsafe =
@@ -649,10 +715,27 @@ export function transpileToJS(
     }
   }
 
-  // Apply insertions in reverse position order (to maintain correct offsets)
-  insertions.sort((a, b) => b.position - a.position)
-
+  // Apply deletions first (reverse order to maintain offsets), then insertions.
+  // Deletions strip | union suffixes from param defaults in the output JS.
+  deletions.sort((a, b) => b.start - a.start)
   let code = preprocessed.source
+  for (const { start, end } of deletions) {
+    code = code.slice(0, start) + code.slice(end)
+  }
+
+  // Adjust insertion positions for any deletions that shifted offsets
+  for (const ins of insertions) {
+    let shift = 0
+    for (const del of deletions) {
+      if (del.start < ins.position) {
+        shift += del.end - del.start
+      }
+    }
+    ins.position -= shift
+  }
+
+  // Apply insertions in reverse position order
+  insertions.sort((a, b) => b.position - a.position)
   for (const { position, text } of insertions) {
     code = code.slice(0, position) + text + code.slice(position)
   }
@@ -1002,6 +1085,13 @@ function generateTypeCheckExpr(
     case 'object':
       // For nested objects, just check it's an object (deep validation is separate)
       return `(typeof ${fieldPath} !== 'object' || ${fieldPath} === null || Array.isArray(${fieldPath}))`
+    case 'union': {
+      const checks = (type as any).members
+        .map((m: TypeDescriptor) => generateTypeCheckExpr(fieldPath, m))
+        .filter((c: string | null) => c !== null)
+      if (checks.length === 0) return null
+      return `(${checks.join(' && ')})`
+    }
     case 'any':
       return null // No check needed
     default:

package/src/lang/eval.ts

@@ -14,6 +14,27 @@ import { transpile } from './core'
 let _vm: AgentVM<Record<string, never>> | null = null
 const getVM = () => (_vm ??= new AgentVM())
 
+/**
+ * Walk an AST and wrap return values in { __result: value } objects.
+ * This lets Eval/SafeFunction return arbitrary values through the VM,
+ * which enforces strict object returns for agent composability.
+ */
+function wrapReturnValues(node: any): void {
+  if (!node || typeof node !== 'object') return
+  if (Array.isArray(node)) {
+    for (const child of node) wrapReturnValues(child)
+    return
+  }
+  if (node.op === 'return' && 'value' in node) {
+    node.value = { __result: node.value }
+  }
+  // Recurse into steps (seq), branches (if/else), etc.
+  if (node.steps) wrapReturnValues(node.steps)
+  if (node.then) wrapReturnValues(node.then)
+  if (node.else) wrapReturnValues(node.else)
+  if (node.body) wrapReturnValues(node.body)
+}
+
 /** Capabilities that can be injected into SafeFunction/Eval */
 export interface SafeCapabilities {
   /** Fetch function for HTTP requests */
@@ -65,14 +86,24 @@ export async function Eval(options: EvalOptions): Promise<{
   try {
     const { ast } = transpile(wrappedCode)
 
+    // Box return values in objects for VM strict-return compliance.
+    // Walk AST and wrap each { op: 'return', value } into
+    // { op: 'return', value: { __result: originalValue } }
+    wrapReturnValues(ast)
+
     const vmResult = await vm.run(ast, context, {
       fuel,
       timeoutMs,
       capabilities,
     })
 
+    // Unwrap the boxed result
+    const raw = vmResult.result
+    const result =
+      raw && typeof raw === 'object' && '__result' in raw ? raw.__result : raw
+
     return {
-      result: vmResult.result,
+      result,
       fuelUsed: vmResult.fuelUsed,
       error: vmResult.error
         ? { message: vmResult.error.message || String(vmResult.error) }
@@ -128,6 +159,9 @@ export async function SafeFunction(options: SafeFunctionOptions): Promise<
   // Pre-compile the AST (done once at creation time)
   const { ast } = transpile(source)
 
+  // Box return values for VM strict-return compliance
+  wrapReturnValues(ast)
+
   // Return a function that runs the pre-compiled AST
   return async (...args: unknown[]) => {
     const context: Record<string, unknown> = {}
@@ -142,8 +176,13 @@ export async function SafeFunction(options: SafeFunctionOptions): Promise<
         capabilities,
       })
 
+      // Unwrap the boxed result
+      const raw = vmResult.result
+      const result =
+        raw && typeof raw === 'object' && '__result' in raw ? raw.__result : raw
+
       return {
-        result: vmResult.result,
+        result,
         fuelUsed: vmResult.fuelUsed,
         error: vmResult.error
           ? { message: vmResult.error.message || String(vmResult.error) }

package/src/lang/from-ts.test.ts

@@ -19,13 +19,13 @@ describe('TypeScript to TJS Transpiler', () => {
       expect(result.code).toContain('b: 0')
     })
 
-    it('should convert optional params to = syntax', () => {
+    it('should convert optional params to union with undefined', () => {
       const result = fromTS(
         `function greet(name: string, title?: string) { return name }`,
         { emitTJS: true }
       )
       expect(result.code).toContain("name: ''")
-      expect(result.code).toContain("title = ''")
+      expect(result.code).toContain("title: '' | undefined")
     })
 
     it('should convert return type to -! annotation (skip signature test)', () => {
@@ -57,7 +57,7 @@ describe('TypeScript to TJS Transpiler', () => {
         `function find(id: string): string | null { return null }`,
         { emitTJS: true }
       )
-      expect(result.code).toContain("-! '' || null") // -! for TS-transpiled
+      expect(result.code).toContain("-! '' | null") // -! for TS-transpiled
     })
 
     it('should preserve default values', () => {

package/src/lang/inference.ts

@@ -6,8 +6,8 @@
  *   10 -> { kind: 'number' }
  *   ['string'] -> { kind: 'array', items: { kind: 'string' } }
  *   { name: 'string' } -> { kind: 'object', shape: { name: { kind: 'string' } } }
- *   'string' || null -> { kind: 'string', nullable: true }
- *   'string' || 0 -> { kind: 'union', members: [{ kind: 'string' }, { kind: 'number' }] }
+ *   'string' | null -> { kind: 'string', nullable: true }
+ *   'string' | 0 -> { kind: 'union', members: [{ kind: 'string' }, { kind: 'number' }] }
  */
 
 import { parseExpressionAt } from 'acorn'
@@ -71,24 +71,8 @@ export function inferTypeFromValue(node: Expression): TypeDescriptor {
       const { operator, left, right } = node as any
 
       if (operator === '||') {
-        const leftType = inferTypeFromValue(left)
-        const rightType = inferTypeFromValue(right)
-
-        // type || null means nullable type
-        if (rightType.kind === 'null') {
-          return { ...leftType, nullable: true }
-        }
-
-        // null || type means nullable type (reverse)
-        if (leftType.kind === 'null') {
-          return { ...rightType, nullable: true }
-        }
-
-        // type1 || type2 means union
-        return {
-          kind: 'union',
-          members: [leftType, rightType],
-        }
+        // || is JavaScript logical OR — infer type from left operand
+        return inferTypeFromValue(left)
       }
 
       if (operator === '&&') {
@@ -106,6 +90,27 @@ export function inferTypeFromValue(node: Expression): TypeDescriptor {
       return { kind: 'any' }
     }
 
+    case 'BinaryExpression': {
+      const { operator, left, right } = node as any
+      // | means union type (e.g., 0 | null, '' | undefined)
+      if (operator === '|') {
+        const leftType = inferTypeFromValue(left)
+        const rightType = inferTypeFromValue(right)
+
+        if (rightType.kind === 'null') {
+          return { ...leftType, nullable: true }
+        }
+        if (leftType.kind === 'null') {
+          return { ...rightType, nullable: true }
+        }
+        return {
+          kind: 'union',
+          members: [leftType, rightType],
+        }
+      }
+      return { kind: 'any' }
+    }
+
     case 'Identifier': {
       // Handle undefined as a type
       if ((node as any).name === 'undefined') {
@@ -282,6 +287,15 @@ export function extractLiteralValue(node: Expression): any {
       }
       return undefined
 
+    case 'BinaryExpression': {
+      const { operator, left } = node as any
+      // | is union type — extract the left (primary) example value
+      if (operator === '|') {
+        return extractLiteralValue(left)
+      }
+      return undefined
+    }
+
     case 'LogicalExpression': {
       const { operator, left, right } = node as any
       if (operator === '&&') {

package/src/lang/parser.test.ts

@@ -294,9 +294,9 @@ test 'always fails' { throw new Error('intentional') }
       expect(signature.parameters.limit.default).toBe(10)
     })
 
-    it('should handle nullable types with colon syntax', () => {
+    it('should handle nullable types with | syntax', () => {
       const { signature } = transpile(`
-        function test(filter: 'default' || null) {
+        function test(filter: 'default' | null) {
           return { filter }
         }
       `)
@@ -304,9 +304,9 @@ test 'always fails' { throw new Error('intentional') }
       expect(signature.parameters.filter.type.nullable).toBe(true)
     })
 
-    it('should handle union types with colon syntax', () => {
+    it('should handle union types with | syntax', () => {
       const { signature } = transpile(`
-        function test(id: 'abc123' || 42) {
+        function test(id: 'abc123' | 42) {
           return { id }
         }
       `)

package/src/lang/transpiler.test.ts

@@ -37,14 +37,16 @@ describe('TJS Emitter', () => {
       expect(result.types.test.params.optional.required).toBe(false)
     })
 
-    it('should convert colon syntax to default values in output', () => {
+    it('should strip colon type annotations from output (no default for required params)', () => {
       const result = transpileToJS(`
         function greet(name: 'world') {
           return name
         }
       `)
-      expect(result.code).toContain("name = 'world'")
+      // Required `:` params have no default in JS output
+      expect(result.code).toContain('function greet(name)')
       expect(result.code).not.toContain("name: 'world'")
+      expect(result.code).not.toContain("name = 'world'")
     })
 
     it('should handle object type annotations', () => {
@@ -225,7 +227,7 @@ function greet(name: 'world') {
           return x
         }
       `)
-      expect(result.code).toContain('function test(x = 0)')
+      expect(result.code).toContain('function test(x)')
       expect(result.code).not.toContain('!')
     })