tjs-lang 0.6.13 → 0.6.14

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

@@ -1594,6 +1594,75 @@ describe('fromTS — tosijs conversion edge cases', () => {
   })
 })
 
+// =============================================================================
+// 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)