tjs-lang 0.6.13 → 0.6.15

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')
+  })
+})

package/src/lang/parser-transforms.ts

@@ -1188,6 +1188,109 @@ export function transformTypeDeclarations(source: string): string {
   return result
 }
 
+/**
+ * Transform FunctionPredicate declarations
+ *
+ * Block form:
+ *   FunctionPredicate Callback {
+ *     params: { x: 0, y: '' }
+ *     returns: false
+ *   }
+ *   → const Callback = FunctionPredicate('Callback', { params: { x: 0, y: '' }, returns: false })
+ *
+ * Function form:
+ *   FunctionPredicate Handler(existingFn, 'description')
+ *   → const Handler = FunctionPredicate('description', existingFn)
+ */
+export function transformFunctionPredicateDeclarations(source: string): string {
+  let result = ''
+  let i = 0
+
+  while (i < source.length) {
+    const fpMatch = source
+      .slice(i)
+      .match(/^\bFunctionPredicate\s+([A-Z_][a-zA-Z0-9_]*)\s*/)
+    if (fpMatch) {
+      const fpName = fpMatch[1]
+      const j = i + fpMatch[0].length
+
+      // Check for block form: FunctionPredicate Name { ... }
+      if (source[j] === '{') {
+        // Find matching closing brace
+        let depth = 1
+        let k = j + 1
+        while (k < source.length && depth > 0) {
+          if (source[k] === '{') depth++
+          else if (source[k] === '}') depth--
+          k++
+        }
+
+        if (depth === 0) {
+          const blockBody = source.slice(j + 1, k - 1).trim()
+
+          // Extract params: { ... }
+          const paramsMatch = blockBody.match(/params\s*:\s*(\{[^}]*\})/)
+          // Extract returns value
+          const returnsMatch = blockBody.match(/returns\s*:\s*(.+?)(?:\n|$)/)
+          // Extract returnContract
+          const contractMatch = blockBody.match(
+            /returnContract\s*:\s*['"](\w+)['"]/
+          )
+          // Extract description
+          const descMatch = blockBody.match(/description\s*:\s*(['"])([^]*?)\1/)
+
+          const spec: string[] = []
+          if (paramsMatch) spec.push(`params: ${paramsMatch[1]}`)
+          if (returnsMatch) spec.push(`returns: ${returnsMatch[1].trim()}`)
+          if (contractMatch) {
+            spec.push(`returnContract: '${contractMatch[1]}'`)
+          }
+
+          const desc = descMatch ? descMatch[2] : fpName
+          result += `const ${fpName} = FunctionPredicate('${desc}', { ${spec.join(
+            ', '
+          )} })`
+          i = k
+          continue
+        }
+      }
+
+      // Check for function form: FunctionPredicate Name(fn, 'desc')
+      if (source[j] === '(') {
+        // Find matching closing paren
+        let depth = 1
+        let k = j + 1
+        while (k < source.length && depth > 0) {
+          if (source[k] === '(') depth++
+          else if (source[k] === ')') depth--
+          k++
+        }
+
+        if (depth === 0) {
+          const args = source.slice(j + 1, k - 1).trim()
+          // Split on comma: fn, 'description'
+          const commaIdx = args.indexOf(',')
+          if (commaIdx !== -1) {
+            const fnRef = args.slice(0, commaIdx).trim()
+            const desc = args.slice(commaIdx + 1).trim()
+            result += `const ${fpName} = FunctionPredicate(${desc}, ${fnRef})`
+          } else {
+            // Just a function reference, name as description
+            result += `const ${fpName} = FunctionPredicate('${fpName}', ${args})`
+          }
+          i = k
+          continue
+        }
+      }
+    }
+
+    result += source[i]
+    i++
+  }
+
+  return result
+}
+
 /**
  * Transform Generic block declarations
  *

package/src/lang/parser.ts

@@ -36,6 +36,7 @@ import {
   transformEqualityToStructural,
   transformTypeDeclarations,
   transformGenericDeclarations,
+  transformFunctionPredicateDeclarations,
   transformUnionDeclarations,
   transformEnumDeclarations,
   transformExtendDeclarations,
@@ -167,6 +168,7 @@ export function preprocess(
   // Enum Status { Pending, Active, Done } -> const Status = Enum(...)
   source = transformTypeDeclarations(source)
   source = transformGenericDeclarations(source)
+  source = transformFunctionPredicateDeclarations(source)
   source = transformUnionDeclarations(source)
   source = transformEnumDeclarations(source)
 

package/src/lang/runtime.ts

@@ -17,6 +17,7 @@ import {
   Union,
   Generic,
   Enum,
+  FunctionPredicate,
   Nullable,
   Optional,
   TArray,
@@ -48,6 +49,7 @@ export {
   Union,
   Generic,
   Enum,
+  FunctionPredicate,
   Nullable,
   Optional,
   TArray,
@@ -1179,6 +1181,7 @@ export function createRuntime() {
     Union,
     Generic,
     Enum,
+    FunctionPredicate,
     Nullable,
     Optional,
     TArray,
@@ -1251,6 +1254,7 @@ export const runtime = {
   Union,
   Generic,
   Enum,
+  FunctionPredicate,
   Nullable,
   Optional,
   TArray,

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

@@ -1312,10 +1312,9 @@ describe('Constrained generics use constraint as example', () => {
 // =============================================================================
 
 describe('fromTS — tosijs conversion edge cases', () => {
-  test('unknown type param before known type param does not error', () => {
-    // When a param type is unknown (e.g. Element), it degrades to bare name
-    // (looks optional). A subsequent typed param should not cause
-    // "required param after optional" error.
+  test('DOM type params stay annotated (not degraded to bare name)', () => {
+    // Element is a DOM interface type — should map to {} (opaque object)
+    // so the param stays annotated and required, not degraded to bare name
     const result = fromTS(
       `export function touchElement(element: Element, changedPath?: string): void {
         console.log(element, changedPath)
@@ -1323,7 +1322,8 @@ describe('fromTS — tosijs conversion edge cases', () => {
       { emitTJS: true }
     )
     expect(result.code).toContain('function touchElement(')
-    // Should succeed without error
+    // Element should be annotated with {} (opaque object), not bare name
+    expect(result.code).toContain('element: {}')
     expect(result.code).toBeDefined()
   })
 
@@ -1594,6 +1594,155 @@ describe('fromTS — tosijs conversion edge cases', () => {
   })
 })
 
+// =============================================================================
+// DOM TYPES
+// =============================================================================
+
+describe('DOM Types', () => {
+  test('Event param maps to opaque object', () => {
+    const result = fromTS(`function handle(e: Event): void {}`, {
+      emitTJS: true,
+    })
+    expect(result.code).toContain('e: {}')
+    // Should NOT have degraded comment
+    expect(result.code).not.toContain('TODO: TS types degraded')
+  })
+
+  test('HTMLElement param maps to opaque object', () => {
+    const result = fromTS(`function render(el: HTMLElement): void {}`, {
+      emitTJS: true,
+    })
+    expect(result.code).toContain('el: {}')
+  })
+
+  test('specific HTML element types map to opaque object', () => {
+    const result = fromTS(
+      `function setup(input: HTMLInputElement, form: HTMLFormElement): void {}`,
+      { emitTJS: true }
+    )
+    expect(result.code).toContain('input: {}')
+    expect(result.code).toContain('form: {}')
+  })
+
+  test('MouseEvent param maps to opaque object', () => {
+    const result = fromTS(
+      `function onClick(ev: MouseEvent): boolean { return true }`,
+      { emitTJS: true }
+    )
+    expect(result.code).toContain('ev: {}')
+  })
+
+  test('Document and Node params map to opaque object', () => {
+    const result = fromTS(
+      `function traverse(doc: Document, node: Node): void {}`,
+      { emitTJS: true }
+    )
+    expect(result.code).toContain('doc: {}')
+    expect(result.code).toContain('node: {}')
+  })
+
+  test('DOM types as return types', () => {
+    const result = fromTS(
+      `function getRoot(): HTMLElement { return document.body }`,
+      { emitTJS: true }
+    )
+    // Return type should be {} not degraded
+    expect(result.code).toContain('-! {}')
+  })
+
+  test('DOM callback type preserves annotation', () => {
+    const result = fromTS(`type ClickHandler = (ev: MouseEvent) => void`, {
+      emitTJS: true,
+    })
+    expect(result.code).toContain('FunctionPredicate ClickHandler')
+  })
+
+  test('mixed DOM and primitive params', () => {
+    const result = fromTS(
+      `function bind(el: Element, attr: string, value: number): void {}`,
+      { emitTJS: true }
+    )
+    expect(result.code).toContain('el: {}')
+    expect(result.code).toContain("attr: ''")
+    expect(result.code).toContain('value: 0.0')
+  })
+
+  test('DOM types in metadata mode', () => {
+    const { types } = fromTS(`function handle(e: Event): void {}`)
+    // Should be 'object' not 'any'
+    expect(types?.handle.params.e.type.kind).toBe('object')
+  })
+})
+
+// =============================================================================
+// FUNCTION TYPES → FunctionPredicate
+// =============================================================================
+
+describe('Function Types (FunctionPredicate)', () => {
+  test('function type alias emits FunctionPredicate', () => {
+    const result = fromTS(`type Callback = (x: number, y: string) => boolean`, {
+      emitTJS: true,
+    })
+    expect(result.code).toContain('FunctionPredicate Callback')
+    expect(result.code).toContain('params: { x: 0.0')
+    expect(result.code).toContain("y: ''")
+    expect(result.code).toContain('returns: false')
+  })
+
+  test('void function type alias', () => {
+    const result = fromTS(`type Logger = (msg: string) => void`, {
+      emitTJS: true,
+    })
+    expect(result.code).toContain('FunctionPredicate Logger')
+    expect(result.code).toContain("params: { msg: '' }")
+    // void return should not emit a returns line
+    expect(result.code).not.toMatch(/returns:/)
+  })
+
+  test('exported function type alias preserves export', () => {
+    const result = fromTS(`export type Handler = (event: Event) => boolean`, {
+      emitTJS: true,
+    })
+    expect(result.code).toContain('export FunctionPredicate Handler')
+  })
+
+  test('inline function param emits FunctionPredicate', () => {
+    const result = fromTS(
+      `function process(cb: (item: string) => number): void {}`,
+      { emitTJS: true }
+    )
+    expect(result.code).toContain("FunctionPredicate('function'")
+  })
+
+  test('no-arg function type', () => {
+    const result = fromTS(`type Thunk = () => number`, { emitTJS: true })
+    expect(result.code).toContain('FunctionPredicate Thunk')
+    expect(result.code).toContain('returns: 0.0')
+  })
+
+  test('function type with multiple params', () => {
+    const result = fromTS(
+      `type Reducer = (acc: number, item: string, index: number) => number`,
+      { emitTJS: true }
+    )
+    expect(result.code).toContain('FunctionPredicate Reducer')
+    expect(result.code).toContain('acc: 0.0')
+    expect(result.code).toContain("item: ''")
+    expect(result.code).toContain('index: 0.0')
+    expect(result.code).toContain('returns: 0.0')
+  })
+
+  test('function type transpiles through full TJS pipeline', () => {
+    const tsResult = fromTS(
+      `type Compare = (a: number, b: number) => boolean`,
+      { emitTJS: true }
+    )
+    const jsResult = tjs(tsResult.code, { runTests: false })
+    expect(jsResult.code).toContain('FunctionPredicate')
+    expect(jsResult.code).toContain('Compare')
+  })
+})
+
 // =============================================================================
 // SUMMARY: Features to implement (in priority order)
 // =============================================================================

package/src/types/Type.ts

@@ -608,3 +608,151 @@ export function Enum<T extends Record<string, string | number>>(
 
   return enumType
 }
+
+// =============================================================================
+// FunctionPredicate - Runtime type for function signatures
+// =============================================================================
+
+/** Return contract levels in order of strictness */
+export type ReturnContract = 'assertReturns' | 'returns' | 'checkedReturns'
+
+/** Specification for a FunctionPredicate */
+export interface FunctionPredicateSpec {
+  /** Parameter types as example values */
+  params?: Record<string, any>
+  /** Return type as example value */
+  returns?: any
+  /** Return contract level */
+  returnContract?: ReturnContract
+}
+
+/** A runtime type that validates function signatures */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export interface FunctionPredicateType extends RuntimeType<Function> {
+  /** Parameter specification */
+  readonly params: Record<string, any>
+  /** Return type specification */
+  readonly returns?: any
+  /** Return contract level */
+  readonly returnContract: ReturnContract
+}
+
+/** Infer a TypeDescriptor kind from an example value */
+function kindOfExample(example: unknown): string | null {
+  if (example === null) return 'null'
+  if (example === undefined) return 'undefined'
+  switch (typeof example) {
+    case 'string':
+      return 'string'
+    case 'boolean':
+      return 'boolean'
+    case 'number':
+      return Number.isInteger(example) ? 'integer' : 'number'
+    case 'object':
+      return Array.isArray(example) ? 'array' : 'object'
+    default:
+      return null
+  }
+}
+
+/**
+ * Create a runtime type for function signatures.
+ *
+ * Forms:
+ *   FunctionPredicate(name, spec) - from a specification object
+ *   FunctionPredicate(name, fn)   - from an existing typed function
+ *
+ * @example
+ * const Callback = FunctionPredicate('Callback', {
+ *   params: { x: 0, y: 0 },
+ *   returns: 0,
+ * })
+ * Callback.check((a, b) => a + b) // true (typeof === 'function')
+ * Callback.check(42)              // false
+ *
+ * @example
+ * function add(a: 0, b: 0) -> 0 { return a + b }
+ * const Adder = FunctionPredicate('Adder', add)
+ * // Extracts params/returns from add.__tjs
+ */
+export function FunctionPredicate(
+  name: string,
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  specOrFn: FunctionPredicateSpec | Function
+): FunctionPredicateType {
+  let params: Record<string, any> = {}
+  let returns: any = undefined
+  let returnContract: ReturnContract = 'assertReturns'
+
+  if (typeof specOrFn === 'function') {
+    // Extract from function's __tjs metadata
+    const meta = (specOrFn as any).__tjs
+    if (meta) {
+      // Build params from __tjs.params
+      if (meta.params) {
+        for (const [key, info] of Object.entries(meta.params)) {
+          params[key] = (info as any)?.example ?? null
+        }
+      }
+      // Extract return type
+      if (meta.returns) {
+        returns = (meta.returns as any)?.example ?? null
+      }
+      // Extract return contract from safety markers
+      if (meta.safeReturn) returnContract = 'checkedReturns'
+      else if (meta.unsafe) returnContract = 'assertReturns'
+      else returnContract = 'returns'
+    }
+  } else {
+    params = specOrFn.params ?? {}
+    returns = specOrFn.returns
+    returnContract = specOrFn.returnContract ?? 'assertReturns'
+  }
+
+  const fpType: FunctionPredicateType = {
+    description: name,
+    params,
+    returns,
+    returnContract,
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    check: (value: unknown): value is Function => {
+      if (typeof value !== 'function') return false
+
+      // Structural validation: check arity and __tjs metadata
+      const expectedArity = Object.keys(params).length
+      if (expectedArity > 0) {
+        // Check function.length (number of params before first default)
+        // eslint-disable-next-line @typescript-eslint/ban-types
+        const fn = value as Function
+        const meta = (fn as any).__tjs
+        if (meta?.params) {
+          // Has TJS metadata — check param count matches
+          const metaParamCount = Object.keys(meta.params).length
+          if (metaParamCount !== expectedArity) return false
+
+          // Check param type kinds match where both sides have type info
+          const expectedKeys = Object.keys(params)
+          const metaKeys = Object.keys(meta.params)
+          for (let i = 0; i < expectedKeys.length; i++) {
+            const metaInfo = meta.params[metaKeys[i]]
+            const expectedExample = params[expectedKeys[i]]
+            if (metaInfo?.type?.kind && expectedExample !== undefined) {
+              const expectedKind = kindOfExample(expectedExample)
+              if (
+                expectedKind &&
+                metaInfo.type.kind !== expectedKind &&
+                metaInfo.type.kind !== 'any'
+              )
+                return false
+            }
+          }
+        }
+      }
+
+      return true
+    },
+    __runtimeType: true as const,
+  }
+
+  return fpType
+}

package/src/types/index.ts

@@ -38,6 +38,11 @@ export {
   TRecord,
   type GenericType,
   type TypeParam,
+  // Function predicates
+  FunctionPredicate,
+  type FunctionPredicateType,
+  type FunctionPredicateSpec,
+  type ReturnContract,
 } from './Type'
 
 // Timestamp and LegalDate utilities (pure functions)