tjs-lang 0.6.13 → 0.6.14

package/docs/function-predicate-design.md

@@ -0,0 +1,180 @@
+# FunctionPredicate: Design Notes
+
+_First-class function types in TJS, using the same pattern as Type/Generic._
+
+---
+
+## The Problem
+
+TJS has no way to express "this parameter must be a function with this
+signature." Currently:
+
+- `() => void` in TypeScript becomes `undefined` in fromTS output
+- There's no TJS syntax for function-typed parameters
+- Callbacks, event handlers, and higher-order functions lose their
+  type information at the boundary
+
+## Design Principles
+
+1. **Functions are values** — a function should be usable as a type example,
+   just like `0` means "integer" and `''` means "string"
+2. **FunctionPredicate should work like Type/Generic** — same pattern of
+   predicate-based checking, introspection via metadata
+3. **The return contract is part of the type** — `->`, `-?`, and `-!` are
+   meaningful distinctions in the function's contract
+
+## The Three Return Contracts
+
+| Marker | Name | Meaning |
+|--------|------|---------|
+| `->` | `returns` | Verified at transpile time (signature test) |
+| `-?` | `checkedReturns` | Verified at transpile time AND runtime |
+| `-!` | `assertReturns` | Declared but not verified (metadata only) |
+
+These are not just build options — they describe the **trust level** of
+the function's return type. A function with `-?` makes a stronger promise
+than one with `-!`.
+
+## Syntax: Function as Type Example
+
+The most TJS-idiomatic approach — a function IS its own type:
+
+```tjs
+// This function's signature IS a type
+function formatter(input: '', options: { locale: 'en' }) -? '' {
+  return input
+}
+
+// fn must match formatter's contract
+function process(fn: formatter) {
+  const result = fn('hello', { locale: 'fr' })
+}
+```
+
+The runtime check for `fn: formatter`:
+1. `typeof fn === 'function'`
+2. `fn.__tjs` exists (it's a TJS-typed function)
+3. `fn.__tjs.params` shape-matches `formatter.__tjs.params`
+4. `fn.__tjs.returns` matches `formatter.__tjs.returns`
+
+Untyped functions (no `__tjs`) would fail the check — they don't have
+the metadata to verify against. Use `!` (unsafe) to skip the check for
+interop with plain JS callbacks.
+
+## Syntax: Explicit FunctionPredicate
+
+For cases where you want to declare a function type without writing an
+example function:
+
+```tjs
+FunctionPredicate Formatter {
+  description: 'formats a string with locale options'
+  params: { input: '', options: { locale: 'en' } }
+  returns: ''
+}
+
+// Or with checked returns:
+FunctionPredicate Validator {
+  params: { value: null }
+  checkedReturns: false
+}
+
+// Or declared-only returns:
+FunctionPredicate Callback {
+  params: { event: { type: '', target: null } }
+  assertReturns: undefined
+}
+```
+
+## Syntax: FunctionPredicate from Function
+
+Create a type from an existing function's metadata:
+
+```tjs
+function myFormatter(input: '', options: { locale: 'en' }) -? '' {
+  return input
+}
+
+// Extract the type from the function
+FunctionPredicate Formatter(myFormatter, 'string formatter with locale')
+```
+
+This is analogous to `Type Name 'example'` — the function itself is the
+example value, and its `__tjs` metadata defines the type.
+
+## Runtime Representation
+
+A FunctionPredicate at runtime would be an object with:
+
+```javascript
+{
+  check(fn) { ... },      // returns boolean
+  params: { ... },         // param descriptors
+  returns: { ... },        // return type descriptor
+  returnContract: 'checked' | 'returns' | 'assert',
+  description: '...',
+  default: exampleFn,      // the example function, if provided
+}
+```
+
+This matches the shape of `Type()` — `check`, `default`, `description`.
+
+## Validation Levels
+
+When checking `fn: SomeType` where SomeType is a FunctionPredicate:
+
+| Check | What it verifies |
+|-------|------------------|
+| `typeof fn === 'function'` | It's callable |
+| `fn.__tjs` exists | It's a TJS-typed function |
+| Param count matches | Same arity (or compatible) |
+| Param types match | Each param's type descriptor matches |
+| Return type matches | Return type descriptor matches |
+| Return contract | At least as strict as required |
+
+Return contract strictness: `checkedReturns` (-?) > `returns` (->) > `assertReturns` (-!).
+A `checkedReturns` function satisfies any requirement.
+A `returns` function satisfies `returns` or `assertReturns`.
+An `assertReturns` function only satisfies `assertReturns`.
+
+## Compatibility with Untyped Functions
+
+Plain JS functions have no `__tjs` metadata. Options:
+
+1. **Strict**: Reject untyped functions (safe but hostile to JS interop)
+2. **Lenient**: Accept any function, only validate if `__tjs` exists
+3. **Unsafe marker**: Use `!` to skip the check for known-untyped callbacks
+
+Option 3 is most consistent with TJS's existing patterns:
+
+```tjs
+// Strict — fn must have matching __tjs metadata
+function process(fn: formatter) { ... }
+
+// Lenient — fn just needs to be callable
+function process(! fn: formatter) { ... }
+```
+
+## Relationship to Existing Features
+
+- **Type**: FunctionPredicate IS a Type — just one that checks function
+  signatures specifically. Could be implemented as a special case of Type
+  with a built-in predicate that introspects `__tjs`.
+- **Generic**: FunctionPredicate could be generic too —
+  `FunctionPredicate Mapper<T, U> { params: { value: T }, returns: U }`
+- **declaration block**: FunctionPredicates would benefit from declaration
+  blocks for `.d.ts` emission, same as Generic.
+
+## Implementation Path
+
+1. **Runtime**: Add `FunctionPredicate()` to the TJS runtime alongside
+   `Type()` and `Generic()`. Returns a type guard that checks `__tjs`
+   metadata on functions.
+2. **Parser**: Recognize `FunctionPredicate` as a declaration keyword
+   (same as `Type`, `Generic`). Parse the block or function-argument form.
+3. **Metadata**: The `__tjs` metadata for the return type already includes
+   `type` — add a `contract` field for the marker.
+4. **fromTS**: When converting `(x: number) => string` types, emit a
+   FunctionPredicate instead of `undefined`.
+5. **Inference**: When a function is used as a `:` param type, check if
+   it has `__tjs` metadata and validate the caller's function against it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tjs-lang",
-  "version": "0.6.13",
+  "version": "0.6.14",
   "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/cli/tjs.ts

@@ -20,7 +20,7 @@ import { emit } from './commands/emit'
 import { convert } from './commands/convert'
 import { test } from './commands/test'
 
-const VERSION = '0.6.13'
+const VERSION = '0.6.14'
 
 const HELP = `
 tjs - Typed JavaScript CLI

package/src/lang/emitters/dts.test.ts

@@ -437,6 +437,64 @@ export Generic Box<T> {
   })
 })
 
+describe('generateDTS — FunctionPredicate declarations', () => {
+  it('should emit FunctionPredicate as TS function type', () => {
+    const source = `
+export FunctionPredicate Callback {
+  params: { x: 0, y: '' }
+  returns: false
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain(
+      'export type Callback = (x: number, y: string) => boolean;'
+    )
+  })
+
+  it('should emit FunctionPredicate with no params as zero-arg function', () => {
+    const source = `
+export FunctionPredicate Thunk {
+  returns: 0
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('export type Thunk = () => number;')
+  })
+
+  it('should emit FunctionPredicate with no return as void', () => {
+    const source = `
+export FunctionPredicate SideEffect {
+  params: { msg: '' }
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).toContain('export type SideEffect = (msg: string) => void;')
+  })
+
+  it('should not emit non-exported FunctionPredicate when exports exist', () => {
+    const source = `
+FunctionPredicate Internal {
+  params: { x: 0 }
+}
+
+export function use(fn: Internal) {
+  return fn(1)
+}
+`
+    const result = transpileToJS(source, { runTests: false })
+    const dts = generateDTS(result, source)
+
+    expect(dts).not.toContain('type Internal')
+    expect(dts).toContain('export declare function use(')
+  })
+})
+
 describe('generateDTS — mixed declarations', () => {
   it('should handle file with functions, classes, types, and generics', () => {
     const source = `

package/src/lang/emitters/dts.ts

@@ -169,6 +169,12 @@ function detectExports(source: string): Map<string, ExportInfo> {
     result.set(m[1], { exported: true, isDefault: false })
   }
 
+  // export FunctionPredicate Name
+  const fpRe = /^[ \t]*export\s+FunctionPredicate\s+(\w+)/gm
+  while ((m = fpRe.exec(source)) !== null) {
+    result.set(m[1], { exported: true, isDefault: false })
+  }
+
   // export { Name, Name2, ... } — re-export form
   const reExportRe = /^[ \t]*export\s*\{([^}]+)\}/gm
   while ((m = reExportRe.exec(source)) !== null) {
@@ -184,6 +190,62 @@ function detectExports(source: string): Map<string, ExportInfo> {
   return result
 }
 
+/** Info about a FunctionPredicate declaration */
+interface FunctionPredicateInfo {
+  params: { name: string; example: string }[]
+  returns?: string
+}
+
+/** Detect FunctionPredicate declarations and extract their param/return specs */
+function detectFunctionPredicates(
+  source: string
+): Map<string, FunctionPredicateInfo> {
+  const result = new Map<string, FunctionPredicateInfo>()
+
+  // Block form: FunctionPredicate Name { params: { ... } returns: ... }
+  const blockRe = /^[ \t]*(?:export\s+)?FunctionPredicate\s+(\w+)\s*\{/gm
+  let m
+  while ((m = blockRe.exec(source)) !== null) {
+    const name = m[1]
+    const blockStart = m.index + m[0].length - 1
+
+    // Find matching closing brace
+    let depth = 1
+    let i = blockStart + 1
+    while (i < source.length && depth > 0) {
+      if (source[i] === '{') depth++
+      else if (source[i] === '}') depth--
+      i++
+    }
+    const body = source.slice(blockStart + 1, i - 1)
+
+    // Extract params object: params: { key: value, ... }
+    const params: FunctionPredicateInfo['params'] = []
+    const paramsMatch = body.match(/params\s*:\s*\{([^}]*)\}/)
+    if (paramsMatch) {
+      const paramsStr = paramsMatch[1]
+      const paramEntries = splitParams(paramsStr)
+      for (const entry of paramEntries) {
+        const kv = entry.match(/^(\w+)\s*:\s*(.+)$/)
+        if (kv) {
+          params.push({ name: kv[1], example: kv[2].trim() })
+        }
+      }
+    }
+
+    // Extract returns value
+    let returns: string | undefined
+    const returnsMatch = body.match(/returns\s*:\s*(.+?)(?:\n|$)/)
+    if (returnsMatch) {
+      returns = returnsMatch[1].trim()
+    }
+
+    result.set(name, { params, returns })
+  }
+
+  return result
+}
+
 /** Info about a class extracted from source */
 interface ClassInfo {
   name: string
@@ -535,6 +597,28 @@ export function generateDTS(
     emitted.add(name)
   }
 
+  // Emit FunctionPredicate declarations as TS function types.
+  // FunctionPredicate Callback { params: { x: 0 } returns: '' }
+  // → export type Callback = (x: number) => string;
+  const funcPreds = detectFunctionPredicates(source)
+  for (const [name, fpInfo] of funcPreds) {
+    if (emitted.has(name)) continue
+
+    const exportInfo = exports.get(name)
+    const isExported = hasAnyExport ? !!exportInfo?.exported : true
+    if (!isExported) continue
+
+    const tsParams = fpInfo.params
+      .map((p) => `${p.name}: ${inferTSTypeFromExample(p.example)}`)
+      .join(', ')
+    const tsReturn =
+      fpInfo.returns !== undefined
+        ? inferTSTypeFromExample(fpInfo.returns)
+        : 'void'
+    lines.push(`export type ${name} = (${tsParams}) => ${tsReturn};`)
+    emitted.add(name)
+  }
+
   if (options.moduleName) {
     const indented = lines.map((l) => `  ${l}`).join('\n')
     return `declare module '${options.moduleName}' {\n${indented}\n}\n`

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

@@ -420,9 +420,24 @@ function typeToExample(
       return typeToExample(parenType.type, checker)
     }
 
-    case ts.SyntaxKind.FunctionType:
-      // Functions become undefined (can't really express as example)
-      return 'undefined'
+    case ts.SyntaxKind.FunctionType: {
+      // Convert to inline FunctionPredicate expression
+      const funcType = type as ts.FunctionTypeNode
+      const fpParams: string[] = []
+      for (const param of funcType.parameters) {
+        const name = param.name?.getText() || '_'
+        if (name === 'this') continue
+        let paramExample = typeToExample(param.type, checker, warnings, ctx)
+        if (paramExample === 'any') paramExample = 'null'
+        fpParams.push(`${name}: ${paramExample}`)
+      }
+      let fpReturn = typeToExample(funcType.type, checker, warnings, ctx)
+      if (fpReturn === 'any') fpReturn = 'null'
+      const spec: string[] = []
+      if (fpParams.length > 0) spec.push(`params: { ${fpParams.join(', ')} }`)
+      if (fpReturn !== 'undefined') spec.push(`returns: ${fpReturn}`)
+      return `FunctionPredicate('function', { ${spec.join(', ')} })`
+    }
 
     case ts.SyntaxKind.TupleType: {
       const tupleType = type as ts.TupleTypeNode
@@ -978,6 +993,25 @@ function transformTypeAliasToType(
     return `Union ${typeName} '${typeName}' ${literalValues.join(' | ')}`
   }
 
+  // Function types → FunctionPredicate declaration
+  if (node.type.kind === ts.SyntaxKind.FunctionType) {
+    const funcType = node.type as ts.FunctionTypeNode
+    const fpParams: string[] = []
+    for (const param of funcType.parameters) {
+      const name = param.name?.getText(sourceFile) || '_'
+      if (name === 'this') continue
+      let paramExample = typeToExample(param.type, undefined, warnings)
+      if (paramExample === 'any') paramExample = 'null'
+      fpParams.push(`${name}: ${paramExample}`)
+    }
+    let fpReturn = typeToExample(funcType.type, undefined, warnings)
+    if (fpReturn === 'any') fpReturn = 'null'
+    const spec: string[] = []
+    if (fpParams.length > 0) spec.push(`params: { ${fpParams.join(', ')} }`)
+    if (fpReturn !== 'undefined') spec.push(`returns: ${fpReturn}`)
+    return `FunctionPredicate ${typeName} {\n  ${spec.join('\n  ')}\n}`
+  }
+
   const example = typeToExample(node.type, undefined, warnings)
 
   // 'any' and 'undefined' — skip declaration (undeclared = any in TJS)
@@ -2054,7 +2088,11 @@ export function fromTS(
             const isExported = statement.modifiers?.some(
               (m) => m.kind === ts.SyntaxKind.ExportKeyword
             )
-            tjsFunctions.push(isExported ? `export ${typeDecl}` : typeDecl)
+            tjsFunctions.push(
+              isExported
+                ? typeDecl.replace(/^(\/\*[\s\S]*?\*\/\s*)?/, '$1export ')
+                : typeDecl
+            )
           }
         }
       }
@@ -2076,7 +2114,11 @@ export function fromTS(
             const isExported = statement.modifiers?.some(
               (m) => m.kind === ts.SyntaxKind.ExportKeyword
             )
-            tjsFunctions.push(isExported ? `export ${typeDecl}` : typeDecl)
+            tjsFunctions.push(
+              isExported
+                ? typeDecl.replace(/^(\/\*[\s\S]*?\*\/\s*)?/, '$1export ')
+                : typeDecl
+            )
           }
         }
       }

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

@@ -0,0 +1,188 @@
+import { describe, it, expect } from 'bun:test'
+import { FunctionPredicate } from '../types/Type'
+import { preprocess } from './parser'
+import { tjs } from './index'
+import { fromTS } from './emitters/from-ts'
+
+describe('FunctionPredicate runtime', () => {
+  it('should create a type that accepts functions', () => {
+    const Callback = FunctionPredicate('Callback', {
+      params: { x: 0 },
+      returns: '',
+    })
+    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)
+  })
+
+  it('should create from existing typed function', () => {
+    const fn = (a: number, b: number) => a + b
+    ;(fn as any).__tjs = {
+      params: {
+        a: { type: { kind: 'integer' }, example: 0 },
+        b: { type: { kind: 'integer' }, example: 0 },
+      },
+      returns: { type: { kind: 'integer' }, example: 0 },
+    }
+    const Adder = FunctionPredicate('Adder', fn)
+    expect(Adder.params).toHaveProperty('a')
+    expect(Adder.params).toHaveProperty('b')
+    expect(Adder.description).toBe('Adder')
+    expect(Adder.__runtimeType).toBe(true)
+  })
+
+  it('should have correct return contract', () => {
+    const assert = FunctionPredicate('f', {
+      returnContract: 'assertReturns',
+    })
+    const returns = FunctionPredicate('f', { returnContract: 'returns' })
+    const checked = FunctionPredicate('f', {
+      returnContract: 'checkedReturns',
+    })
+    expect(assert.returnContract).toBe('assertReturns')
+    expect(returns.returnContract).toBe('returns')
+    expect(checked.returnContract).toBe('checkedReturns')
+  })
+
+  it('should default to assertReturns contract', () => {
+    const fp = FunctionPredicate('f', {})
+    expect(fp.returnContract).toBe('assertReturns')
+  })
+
+  it('should reject function with wrong arity via __tjs metadata', () => {
+    const Binop = FunctionPredicate('Binop', {
+      params: { a: 0, b: 0 },
+      returns: 0,
+    })
+    // Function with matching arity + types → pass
+    const goodFn = (a: number, b: number) => a + b
+    ;(goodFn as any).__tjs = {
+      params: {
+        a: { type: { kind: 'integer' }, example: 0 },
+        b: { type: { kind: 'integer' }, example: 0 },
+      },
+    }
+    expect(Binop.check(goodFn)).toBe(true)
+
+    // Function with wrong arity → fail
+    const wrongArity = (x: number) => x
+    ;(wrongArity as any).__tjs = {
+      params: {
+        x: { type: { kind: 'integer' }, example: 0 },
+      },
+    }
+    expect(Binop.check(wrongArity)).toBe(false)
+  })
+
+  it('should reject function with wrong param types via __tjs metadata', () => {
+    const StrFn = FunctionPredicate('StrFn', {
+      params: { name: '' },
+      returns: '',
+    })
+    // Function with string param → pass
+    const goodFn = (s: string) => s
+    ;(goodFn as any).__tjs = {
+      params: { s: { type: { kind: 'string' }, example: '' } },
+    }
+    expect(StrFn.check(goodFn)).toBe(true)
+
+    // Function with number param → fail
+    const badFn = (n: number) => String(n)
+    ;(badFn as any).__tjs = {
+      params: { n: { type: { kind: 'integer' }, example: 0 } },
+    }
+    expect(StrFn.check(badFn)).toBe(false)
+  })
+
+  it('should accept function with any-typed params', () => {
+    const Binop = FunctionPredicate('Binop', {
+      params: { a: 0, b: 0 },
+    })
+    const fn = (a: any, b: any) => a + b
+    ;(fn as any).__tjs = {
+      params: {
+        a: { type: { kind: 'any' }, example: null },
+        b: { type: { kind: 'any' }, example: null },
+      },
+    }
+    expect(Binop.check(fn)).toBe(true)
+  })
+
+  it('should accept plain functions without __tjs metadata', () => {
+    const Callback = FunctionPredicate('Callback', {
+      params: { x: 0 },
+    })
+    // Plain function with no metadata — should still pass (can't validate)
+    expect(Callback.check(() => {})).toBe(true)
+    expect(Callback.check(Math.abs)).toBe(true)
+  })
+})
+
+describe('FunctionPredicate parser transform', () => {
+  it('should transform block form', () => {
+    const result = preprocess(
+      "FunctionPredicate Callback {\n  params: { x: 0 }\n  returns: ''\n}"
+    )
+    expect(result.source).toContain("FunctionPredicate('Callback'")
+    expect(result.source).toContain('params: { x: 0 }')
+    expect(result.source).toContain("returns: ''")
+  })
+
+  it('should transform function form', () => {
+    const result = preprocess(
+      "FunctionPredicate Handler(myFn, 'event handler')"
+    )
+    expect(result.source).toContain("FunctionPredicate('event handler'")
+    expect(result.source).toContain('myFn')
+  })
+
+  it('should transpile block form through full pipeline', () => {
+    const result = tjs(
+      'FunctionPredicate Callback {\n  params: { x: 0 }\n  returns: false\n}',
+      { runTests: false }
+    )
+    expect(result.code).toContain('FunctionPredicate')
+    expect(result.code).toContain('Callback')
+  })
+})
+
+describe('FunctionPredicate in fromTS', () => {
+  it('should convert function type alias to FunctionPredicate', () => {
+    const result = fromTS('type Callback = (x: number) => void', {
+      emitTJS: true,
+    })
+    expect(result.code).toContain('FunctionPredicate Callback')
+    expect(result.code).toContain('params: { x: 0.0 }')
+  })
+
+  it('should convert function type with return to FunctionPredicate', () => {
+    const result = fromTS('type Mapper = (value: string) => number', {
+      emitTJS: true,
+    })
+    expect(result.code).toContain('FunctionPredicate Mapper')
+    expect(result.code).toContain("params: { value: '' }")
+    expect(result.code).toContain('returns: 0.0')
+  })
+
+  it('should handle inline function params', () => {
+    const result = fromTS(
+      'function process(cb: (x: number) => string): void {}',
+      { emitTJS: true }
+    )
+    expect(result.code).toContain("FunctionPredicate('function'")
+  })
+
+  it('should handle void function type', () => {
+    const result = fromTS('type VoidFn = () => void', { emitTJS: true })
+    expect(result.code).toContain('FunctionPredicate VoidFn')
+  })
+
+  it('should preserve export on function type alias', () => {
+    const result = fromTS('export type Handler = (event: Event) => boolean', {
+      emitTJS: true,
+    })
+    expect(result.code).toContain('export FunctionPredicate Handler')
+  })
+})