tjs-lang 0.5.3 → 0.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tjs-lang",
-  "version": "0.5.3",
+  "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?')
     })
 
@@ -50,12 +50,11 @@ describe('TS → TJS conversion quality', () => {
       expect(code).toContain('flag: false')
     })
 
-    it('converts optional boolean param to = 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')
-      expect(code).not.toContain('excited = true')
+      expect(code).toContain('excited: false | undefined')
     })
 
     it('converts array param correctly', () => {
@@ -86,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')
     })
   })
 
@@ -296,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')
     })
   })
 
@@ -379,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'")
     })
   })
 
@@ -632,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)', () => {
@@ -1255,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')
     })
   })
 })
@@ -1788,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: '') -! '' {
@@ -1935,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,11 +139,6 @@ function typeToExample(
     case ts.SyntaxKind.NumberKeyword:
       return '0.0'
     case ts.SyntaxKind.BooleanKeyword:
-      // REVISIT: TS `x?: boolean` becomes TJS `x = false`, which collapses
-      // "not passed" (undefined) and "passed as false" into the same value.
-      // Code that distinguishes the three states (true/false/undefined) will
-      // break. Consider emitting `x: false || null` for optional booleans
-      // to preserve the undefined state.
       return 'false'
     case ts.SyntaxKind.NullKeyword:
       return 'null'
@@ -301,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
@@ -921,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(
@@ -929,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
@@ -1208,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/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('!')
     })
 

package/src/lang/typescript-syntax.test.ts

@@ -13,7 +13,7 @@
  */
 
 import { describe, test, expect } from 'bun:test'
-import { transpileToJS, fromTS } from './index'
+import { transpileToJS, fromTS, tjs } from './index'
 
 // Helper to get the first function's metadata from the Record
 function getFirstFunc(metadata: Record<string, any>) {
@@ -125,9 +125,9 @@ describe('Basic Types', () => {
 // =============================================================================
 
 describe('Union Types', () => {
-  test('union with || (TJS style)', () => {
+  test('union with | (string or integer)', () => {
     const { metadata } = transpileToJS(`
-      function flexible(id: '' || 0) {
+      function flexible(id: '' | 0) {
         return String(id)
       }
     `)
@@ -135,9 +135,9 @@ describe('Union Types', () => {
     expect(getFirstFunc(metadata).params.id.type.members?.length).toBe(2)
   })
 
-  test('nullable with || null', () => {
+  test('nullable with | null', () => {
     const { metadata } = transpileToJS(`
-      function maybeString(s: '' || null) {
+      function maybeString(s: '' | null) {
         return s ?? 'default'
       }
     `)
@@ -153,18 +153,7 @@ describe('Union Types', () => {
     expect(types?.flexible.params.id.type.kind).toBe('union')
   })
 
-  test('union return type with || (TJS style)', () => {
-    const { metadata } = transpileToJS(`
-      function find(id: 0) -! { name: '' } || null {
-        return null
-      }
-    `)
-    expect(getFirstFunc(metadata).returns?.kind).toBe('object')
-    expect(getFirstFunc(metadata).returns?.nullable).toBe(true)
-  })
-
-  // TODO: Union return types like `{ obj } | null` not yet supported in parser
-  test.skip('union return type with | (TS style)', () => {
+  test('union return type with | (nullable object)', () => {
     const { metadata } = transpileToJS(`
       function find(id: 0) -! { name: '' } | null {
         return null
@@ -858,6 +847,20 @@ describe('Real-World Patterns', () => {
     // Generic T becomes any, but structure is preserved
     expect(types?.chunk.params.array.type.kind).toBe('array')
   })
+
+  test('?: boolean transpiles to required union param with no JS default', () => {
+    const tjsCode = fromTS('function f(excited?: boolean) { return excited }', {
+      emitTJS: true,
+    }).code
+    // TJS should have union annotation
+    expect(tjsCode).toContain('excited: false | undefined')
+    const jsResult = tjs(tjsCode)
+    // JS should not have default or bitwise OR — `:` means required
+    expect(jsResult.code).not.toMatch(/excited = false/)
+    expect(jsResult.code).not.toMatch(/excited = false \| undefined/)
+    // Should have union type check
+    expect(jsResult.code).toContain("typeof excited !== 'boolean'")
+  })
 })
 
 // =============================================================================