tjs-lang 0.6.13 → 0.6.15

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.15",
   "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.15'
 
 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

@@ -124,6 +124,158 @@ interface TypeResolutionContext {
   typeParams?: Map<string, { constraint?: ts.TypeNode; default?: ts.TypeNode }>
 }
 
+/**
+ * DOM interface types — not constructible but common in TS signatures.
+ * Map to {} (opaque object) so params stay annotated and required
+ * rather than degrading to bare names.
+ */
+const domInterfaceTypes = new Set([
+  // Events
+  'Event',
+  'CustomEvent',
+  'MouseEvent',
+  'KeyboardEvent',
+  'PointerEvent',
+  'TouchEvent',
+  'FocusEvent',
+  'InputEvent',
+  'CompositionEvent',
+  'WheelEvent',
+  'DragEvent',
+  'AnimationEvent',
+  'TransitionEvent',
+  'ClipboardEvent',
+  'UIEvent',
+  'ProgressEvent',
+  'ErrorEvent',
+  'MessageEvent',
+  'PopStateEvent',
+  'HashChangeEvent',
+  'PageTransitionEvent',
+  'StorageEvent',
+  'BeforeUnloadEvent',
+  'SubmitEvent',
+  // Event targets / misc
+  'EventTarget',
+  'EventListener',
+  // Nodes
+  'Node',
+  'Element',
+  'HTMLElement',
+  'SVGElement',
+  'Document',
+  'DocumentFragment',
+  'ShadowRoot',
+  'Text',
+  'Comment',
+  'Attr',
+  // Specific HTML elements
+  'HTMLInputElement',
+  'HTMLTextAreaElement',
+  'HTMLSelectElement',
+  'HTMLButtonElement',
+  'HTMLFormElement',
+  'HTMLAnchorElement',
+  'HTMLImageElement',
+  'HTMLVideoElement',
+  'HTMLAudioElement',
+  'HTMLCanvasElement',
+  'HTMLDivElement',
+  'HTMLSpanElement',
+  'HTMLParagraphElement',
+  'HTMLTableElement',
+  'HTMLTemplateElement',
+  'HTMLSlotElement',
+  'HTMLDialogElement',
+  'HTMLDetailsElement',
+  'HTMLLabelElement',
+  'HTMLOptionElement',
+  'HTMLIFrameElement',
+  'HTMLScriptElement',
+  'HTMLStyleElement',
+  'HTMLLinkElement',
+  'HTMLMetaElement',
+  'HTMLHeadElement',
+  'HTMLBodyElement',
+  'HTMLMediaElement',
+  // SVG elements
+  'SVGSVGElement',
+  'SVGPathElement',
+  'SVGGElement',
+  'SVGCircleElement',
+  'SVGRectElement',
+  'SVGTextElement',
+  'SVGLineElement',
+  'SVGPolygonElement',
+  // Collections / lists
+  'NodeList',
+  'HTMLCollection',
+  'NamedNodeMap',
+  'DOMTokenList',
+  'DOMStringMap',
+  'CSSStyleDeclaration',
+  'DOMRect',
+  'DOMRectReadOnly',
+  'DOMPoint',
+  'DOMMatrix',
+  // Ranges / selection
+  'Range',
+  'Selection',
+  'StaticRange',
+  // Observers
+  'MutationObserver',
+  'MutationRecord',
+  'IntersectionObserver',
+  'IntersectionObserverEntry',
+  'ResizeObserver',
+  'ResizeObserverEntry',
+  'PerformanceObserver',
+  'PerformanceEntry',
+  // Window / global
+  'Window',
+  'Location',
+  'History',
+  'Navigator',
+  'Screen',
+  'Storage',
+  // Canvas / media
+  'CanvasRenderingContext2D',
+  'WebGLRenderingContext',
+  'WebGL2RenderingContext',
+  'OffscreenCanvas',
+  'ImageData',
+  'ImageBitmap',
+  'MediaStream',
+  'MediaRecorder',
+  'AudioContext',
+  'AudioNode',
+  'AudioBuffer',
+  // Workers / messaging
+  'Worker',
+  'SharedWorker',
+  'ServiceWorker',
+  'ServiceWorkerRegistration',
+  'BroadcastChannel',
+  'MessageChannel',
+  'MessagePort',
+  // Other Web APIs
+  'WebSocket',
+  'XMLHttpRequest',
+  'FileReader',
+  'FileList',
+  'DataTransfer',
+  'Crypto',
+  'SubtleCrypto',
+  'CryptoKey',
+  'Geolocation',
+  'Notification',
+  'PermissionStatus',
+  'MediaQueryList',
+  'TreeWalker',
+  'NodeIterator',
+  'ClipboardItem',
+])
+
 /**
  * Convert a TypeScript type node to a TJS example value string
  *
@@ -221,6 +373,10 @@ function typeToExample(
         Error: "new Error('example')",
         TypeError: "new TypeError('example')",
         RangeError: "new RangeError('example')",
+        SyntaxError: "new SyntaxError('example')",
+        ReferenceError: "new ReferenceError('example')",
+        URIError: "new URIError('example')",
+        EvalError: "new EvalError('example')",
         // Date/Regex
         Date: 'new Date()',
         RegExp: '/example/',
@@ -239,7 +395,7 @@ function typeToExample(
         Uint8ClampedArray: 'new Uint8ClampedArray(0)',
         BigInt64Array: 'new BigInt64Array(0)',
         BigUint64Array: 'new BigUint64Array(0)',
-        // Web/DOM
+        // Web APIs (constructible)
         URL: "new URL('https://example.com')",
         URLSearchParams: 'new URLSearchParams()',
         Headers: 'new Headers()',
@@ -249,6 +405,7 @@ function typeToExample(
         Response: 'new Response()',
         Request: "new Request('https://example.com')",
         AbortController: 'new AbortController()',
+        AbortSignal: 'AbortSignal.abort()',
         // Streams
         ReadableStream: 'new ReadableStream()',
         WritableStream: 'new WritableStream()',
@@ -256,6 +413,8 @@ function typeToExample(
         // Structured data
         TextEncoder: 'new TextEncoder()',
         TextDecoder: 'new TextDecoder()',
+        // Promises
+        Promise: 'Promise.resolve(null)',
       }
 
       if (typeName in builtinExamples) {
@@ -318,6 +477,11 @@ function typeToExample(
         // No constraint or default — fall through to 'any'
       }
 
+      // DOM interface types — opaque objects, keep params annotated
+      if (domInterfaceTypes.has(typeName)) {
+        return '{}'
+      }
+
       // Single uppercase letter or common generic names — treat as any
       if (
         /^[A-Z]$/.test(typeName) ||
@@ -420,9 +584,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
@@ -669,6 +848,11 @@ function typeToInfo(
         }
       }
 
+      // DOM interface types — opaque objects
+      if (domInterfaceTypes.has(typeName)) {
+        return { kind: 'object' }
+      }
+
       // Generics and unknown types become 'any'
       return { kind: 'any' }
     }
@@ -978,6 +1162,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 +2257,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 +2283,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
+            )
           }
         }
       }