tjs-lang 0.6.20 → 0.6.26

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

@@ -1,94 +0,0 @@
-/**
- * TypeScript to TJS Transpiler
- *
- * Converts TypeScript source to TJS (or directly to JS + metadata).
- *
- * Two modes:
- * 1. TS → TJS (for inspection/migration)
- * 2. TS → JS + __tjs metadata (for production)
- *
- * @example
- * ```typescript
- * // Input TypeScript:
- * function greet(name: string, age?: number): string {
- *   return `Hello, ${name}!`
- * }
- *
- * // Output TJS:
- * function greet(name: '', age = 0) -> '' {
- *   return `Hello, ${name}!`
- * }
- *
- * // Output JS + metadata:
- * function greet(name, age) {
- *   return `Hello, ${name}!`
- * }
- * greet.__tjs = {
- *   params: { name: { type: 'string', required: true }, age: { type: 'number', required: false } },
- *   returns: { type: 'string' }
- * }
- * ```
- */
-export interface FromTSOptions {
-    /** Emit TJS intermediate instead of JS + metadata */
-    emitTJS?: boolean;
-    /** Include sourcemap */
-    sourceMap?: boolean;
-    /** Filename for error messages */
-    filename?: string;
-}
-export interface FromTSResult {
-    /** The transpiled code (TJS or JS depending on options) */
-    code: string;
-    /** Function type metadata (only when emitting JS) */
-    types?: Record<string, FunctionTypeInfo>;
-    /** Class type metadata (only when emitting JS) */
-    classes?: Record<string, ClassTypeInfo>;
-    /** Any warnings during transpilation */
-    warnings?: string[];
-}
-export interface TypeParamInfo {
-    /** Constraint schema (from `extends`) - example-based */
-    constraint?: string | Record<string, any>;
-    /** Default schema (from `= Type`) - example-based */
-    default?: string | Record<string, any>;
-}
-export interface FunctionTypeInfo {
-    name: string;
-    params: Record<string, ParamTypeInfo>;
-    returns?: TypeInfo;
-    description?: string;
-    /** Generic type parameters with constraints/defaults */
-    typeParams?: Record<string, TypeParamInfo>;
-    /** Overload signatures (when function has TS overloads) */
-    overloads?: FunctionTypeInfo[];
-}
-export interface ClassTypeInfo {
-    name: string;
-    /** Constructor parameters - also serves as the type shape */
-    constructor?: {
-        params: Record<string, ParamTypeInfo>;
-    };
-    /** Instance methods */
-    methods: Record<string, FunctionTypeInfo>;
-    /** Static methods */
-    staticMethods: Record<string, FunctionTypeInfo>;
-    /** Generic type parameters */
-    typeParams?: Record<string, TypeParamInfo>;
-}
-export interface ParamTypeInfo {
-    type: TypeInfo;
-    required: boolean;
-    default?: any;
-    description?: string;
-}
-export interface TypeInfo {
-    kind: 'string' | 'number' | 'boolean' | 'null' | 'undefined' | 'array' | 'tuple' | 'object' | 'union' | 'any';
-    items?: TypeInfo;
-    /** For tuples: element types in order */
-    elements?: TypeInfo[];
-    shape?: Record<string, TypeInfo>;
-    members?: TypeInfo[];
-    nullable?: boolean;
-}
-export declare function fromTS(source: string, options?: FromTSOptions): FromTSResult;

package/dist/src/lang/emitters/js-tests.d.ts

@@ -1,70 +0,0 @@
-/**
- * TJS Test Execution
- *
- * Handles transpile-time test execution, signature validation, and test utilities.
- */
-import type { ExtractedTest, ExtractedMock } from '../tests';
-export interface TestResult {
-    /** Test description */
-    description: string;
-    /** Whether the test passed */
-    passed: boolean;
-    /** Error message if failed */
-    error?: string;
-    /** Whether this was an implicit signature test */
-    isSignatureTest?: boolean;
-    /** Source line number (1-indexed) where the test or error occurred */
-    line?: number;
-    /** Source column number (1-indexed) */
-    column?: number;
-}
-/**
- * Strip import/export syntax for test execution context
- * Tests run in new Function() which doesn't support ES modules
- *
- * Useful for:
- * - Running tests in new Function() context
- * - CLI test runners
- * - Bundler plugins that need to extract module code
- */
-export declare function stripModuleSyntax(code: string): string;
-/**
- * Strip the __tjs runtime preamble from transpiled code
- * This is needed when injecting resolved imports into a test context
- * that already has its own __tjs stub
- *
- * Useful for:
- * - Combining multiple TJS modules into a single execution context
- * - Test runners that provide their own __tjs runtime
- * - Bundlers that need to deduplicate runtime setup
- */
-export declare function stripTjsPreamble(code: string): string;
-/**
- * Info about a signature test (extracted but not yet executed)
- */
-interface SignatureTestInfo {
-    funcName: string;
-    args: unknown[];
-    expected: unknown;
-    defaults?: Record<string, unknown>;
-    line: number;
-    isAsync?: boolean;
-}
-/**
- * Extract signature test info from source without executing
- */
-export declare function extractSignatureTestInfos(originalSource: string): SignatureTestInfo[];
-/**
- * Run all tests (explicit blocks + signature tests) in a single execution context
- * This executes the module only once, then runs all tests against that context
- */
-export declare function runAllTests(tests: ExtractedTest[], mocks: ExtractedMock[], sigTestInfos: SignatureTestInfo[], transpiledCode: string, resolvedImports?: Record<string, string>, extensions?: Map<string, Set<string>>): TestResult[];
-/**
- * Extract return type example from source, handling nested braces
- */
-export declare function extractReturnExampleFromSource(source: string): string | null;
-export {};
-/**
- * Compile WASM blocks and generate bootstrap code that embeds the compiled bytes
- * and instantiates them on load.
- */

package/dist/src/lang/emitters/js-wasm.d.ts

@@ -1,15 +0,0 @@
-/**
- * TJS WASM Bootstrap Generation
- *
- * Compiles inline WASM blocks and generates JavaScript bootstrap code.
- */
-import type { WasmBlock } from '../parser';
-export declare function generateWasmBootstrap(blocks: WasmBlock[]): {
-    code: string;
-    results: {
-        id: string;
-        success: boolean;
-        error?: string;
-        byteLength?: number;
-    }[];
-};

package/dist/src/lang/emitters/js.d.ts

@@ -1,175 +0,0 @@
-/**
- * TJS to JavaScript Emitter
- *
- * Transforms TJS source into standard JavaScript with runtime type metadata.
- * Unlike the AST emitter (for AgentJS), this outputs executable JS code.
- *
- * Input:
- *   function greet(name: 'world') -> '' {
- *     return `Hello, ${name}!`
- *   }
- *
- * Output:
- *   function greet(name = 'world') {
- *     return `Hello, ${name}!`
- *   }
- *   greet.__tjs = {
- *     params: { name: { type: 'string', required: true, example: 'world' } },
- *     returns: { type: 'string' }
- *   }
- *
- * TODO: Self-contained output (no runtime dependency)
- * =====================================================
- * Currently, transpiled code references `globalThis.__tjs` for:
- *   - __tjs.pushStack() / popStack() - debug stack traces
- *   - __tjs.typeError() - monadic error creation
- *   - __tjs.Is() / IsNot() - structural equality (when == / != used)
- *
- * This requires either:
- *   1. The runtime to be installed via installRuntime()
- *   2. A stub to be provided (e.g., playground's inline stub)
- *
- * The ideal is that TJS produces completely independent code that only needs
- * things it semantically needs (like fetch for HTTP calls). The runtime
- * functions above are ~30 lines and could be inlined when used:
- *
- *   - typeError: Create a simple Error with extra properties
- *   - pushStack/popStack: Could be no-ops in production, or inline array ops
- *   - Is/IsNot: ~20 lines for deep structural equality
- *
- * Options to explore:
- *   1. Inline minimal runtime when needed (adds ~1KB unminified per output)
- *   2. Add transpile option: { standalone: true } to emit self-contained code
- *   3. Tree-shake: only inline the specific functions actually referenced
- *
- * See also: demo/src/tjs-playground.ts which has a manual __tjs stub that
- * must stay in sync with the runtime - a symptom of this leaky abstraction.
- */
-import type { TypeDescriptor, ParameterDescriptor } from '../types';
-export { stripModuleSyntax, stripTjsPreamble } from './js-tests';
-export interface TJSTranspileOptions {
-    /** Filename for error messages */
-    filename?: string;
-    /** Include source map comment */
-    sourceMap?: boolean;
-    /** Mode: 'dev' | 'strict' | 'production' */
-    mode?: 'dev' | 'strict' | 'production';
-    /**
-     * Test execution mode:
-     * - true (default): run tests at transpile time, throw on failure
-     * - false: skip tests entirely (production build)
-     * - 'only': only run tests, don't emit code (CI/test runner)
-     * - 'report': run tests, report results in testResults, don't throw
-     *             (caller decides whether to use the code based on results)
-     */
-    runTests?: boolean | 'only' | 'report';
-    /**
-     * Debug mode: include source locations in __tjs metadata
-     * Enables better error messages with file:line:column info
-     */
-    debug?: boolean;
-    /**
-     * Pre-resolved import code for test execution.
-     * Map of import specifier to compiled JavaScript code.
-     * Used when tests depend on imported modules.
-     */
-    resolvedImports?: Record<string, string>;
-}
-/** Result of running tests at transpile time */
-export type { TestResult } from './js-tests';
-import type { TestResult } from './js-tests';
-export interface TJSTranspileResult {
-    /** The transpiled JavaScript code */
-    code: string;
-    /** Type information for the function(s) - Record of function name to type info */
-    types: Record<string, TJSTypeInfo>;
-    /** Function metadata (alias for types, used by runtime) */
-    metadata: Record<string, TJSTypeInfo>;
-    /** Any warnings during transpilation */
-    warnings?: string[];
-    /** Generated test runner code (if tests were present) - DEPRECATED, tests now run at transpile time */
-    testRunner?: string;
-    /** Number of tests extracted */
-    testCount?: number;
-    /** Test results (when runTests is true or 'only') */
-    testResults?: TestResult[];
-    /** WASM compilation results (for debugging/inspection) */
-    wasmCompiled?: {
-        id: string;
-        success: boolean;
-        error?: string;
-        byteLength?: number;
-    }[];
-}
-export interface TJSTypeInfo {
-    /** Function name */
-    name: string;
-    /** Parameter types */
-    params: Record<string, ParameterDescriptor>;
-    /** Return type */
-    returns?: TypeDescriptor;
-    /** TDoc description */
-    description?: string;
-    /** True if function uses destructured object param (the fast path) */
-    isDestructuredParam?: boolean;
-    /** The shape of the destructured param (for inline validation) */
-    destructuredShape?: Record<string, TypeDescriptor>;
-    /** Which fields in destructuredShape are required */
-    destructuredRequired?: Set<string>;
-}
-/**
- * Transpile TJS source to JavaScript
- *
- * This function handles:
- * - Files with no functions (just statements/tests)
- * - Files with multiple functions
- * - Inline validation (no wrappers)
- * - __tjs metadata inserted immediately after each function
- */
-export declare function transpileToJS(source: string, options?: TJSTranspileOptions): TJSTranspileResult;
-/**
- * Safety options for metadata generation
- */
-interface SafetyOptions {
-    /** Function marked with (!) - never validate inputs */
-    unsafe?: boolean;
-    /** Function marked with (?) - always validate inputs */
-    safe?: boolean;
-    /** Return type safety: 'safe' (-?) or 'unsafe' (-!) */
-    returnSafety?: 'safe' | 'unsafe';
-}
-/**
- * Generate inline validation code for single-arg object types
- *
- * This is ~20x faster than schema-based validation because:
- * 1. No schema interpretation at runtime
- * 2. No object iteration
- * 3. JIT can inline the checks
- *
- * Generated code looks like:
- *   if (typeof input !== 'object' || input === null ||
- *       typeof input.x !== 'number' ||
- *       typeof input.y !== 'number') {
- *     return __tjs.typeError('funcName.input', 'object', input)
- *   }
- */
-export declare function generateInlineValidation(funcName: string, paramName: string, shape: Record<string, TypeDescriptor>, requiredFields: Set<string>): string;
-/**
- * Generate the complete function wrapper with inline validation
- *
- * For destructured object params, this generates:
- *
- *   const _original_funcName = funcName
- *   funcName = function(__input) {
- *     if (typeof __input !== 'object' || __input === null || ...) {
- *       return __tjs.typeError('funcName.input', 'object', __input)
- *     }
- *     return _original_funcName.call(this, __input)
- *   }
- *
- * For single named object params, same pattern with the actual param name.
- */
-export declare function generateInlineWrapper(funcName: string, types: TJSTypeInfo, safety?: SafetyOptions): string | null;
-/**
- * Fuzzy comparison for floating point numbers
- */

package/dist/src/lang/eval.d.ts

@@ -1,63 +0,0 @@
-/**
- * Safe Eval and SafeFunction - VM-backed dynamic code execution
- *
- * Import this module explicitly when you need to execute code dynamically.
- * This pulls in the AJS transpiler and VM (~50KB gzipped).
- *
- * For static code (pre-transpiled), use the lite runtime instead.
- */
-/** Capabilities that can be injected into SafeFunction/Eval */
-export interface SafeCapabilities {
-    /** Fetch function for HTTP requests */
-    fetch?: typeof globalThis.fetch;
-    /** Console for logging */
-    console?: Pick<typeof console, 'log' | 'warn' | 'error'>;
-    /** Additional capabilities to expose */
-    [key: string]: unknown;
-}
-/** Options for Eval */
-export interface EvalOptions {
-    /** Code to evaluate (expression or statements with return) */
-    code: string;
-    /** Context variables available to the code */
-    context?: Record<string, unknown>;
-    /** Fuel budget (default: 1000) */
-    fuel?: number;
-    /** Timeout in milliseconds (default: fuel * 10) */
-    timeoutMs?: number;
-    /** Capabilities to inject (fetch, console, etc.) */
-    capabilities?: SafeCapabilities;
-}
-/**
- * Safely evaluate code in a sandboxed VM with fuel metering
- */
-export declare function Eval(options: EvalOptions): Promise<{
-    result: unknown;
-    fuelUsed: number;
-    error?: {
-        message: string;
-    };
-}>;
-/** Options for SafeFunction */
-export interface SafeFunctionOptions {
-    /** Function body code */
-    body: string;
-    /** Parameter names (in order) */
-    params?: string[];
-    /** Fuel budget per invocation (default: 1000) */
-    fuel?: number;
-    /** Timeout in milliseconds (default: fuel * 10) */
-    timeoutMs?: number;
-    /** Capabilities to inject (fetch, console, etc.) */
-    capabilities?: SafeCapabilities;
-}
-/**
- * Create a reusable sandboxed function with fuel metering
- */
-export declare function SafeFunction(options: SafeFunctionOptions): Promise<(...args: unknown[]) => Promise<{
-    result: unknown;
-    fuelUsed: number;
-    error?: {
-        message: string;
-    };
-}>>;

package/dist/src/lang/index.d.ts

@@ -1,216 +0,0 @@
-/**
- * AsyncJS Transpiler
- *
- * Transforms AsyncJS ("Better JavaScript") into tjs-lang AST.
- *
- * @example
- * ```typescript
- * import { ajs, transpile } from 'tjs-lang'
- *
- * // Simple function
- * const ast = ajs(`
- *   function greet({ name }) {
- *     let msg = template({ tmpl: 'Hello {{name}}', vars: { name } })
- *     return { msg }
- *   }
- * `)
- *
- * // Execute
- * const vm = new AgentVM()
- * await vm.run(ast, { name: 'World' })
- * ```
- */
-import type { SeqNode } from '../builder';
-import type { TranspileOptions, TranspileResult, FunctionSignature } from './types';
-export * from './types';
-export { parse, preprocess, extractTDoc } from './parser';
-export { transformFunction } from './emitters/ast';
-export { transpileToJS, stripModuleSyntax, stripTjsPreamble, type TJSTranspileOptions, type TJSTranspileResult, type TJSTypeInfo, } from './emitters/js';
-export { generateDTS, typeDescriptorToTS, type GenerateDTSOptions, } from './emitters/dts';
-export { fromTS, type FromTSOptions, type FromTSResult, } from './emitters/from-ts';
-export * from './inference';
-export { Schema } from './schema';
-export { MetadataCache, getGlobalCache, setGlobalCache } from './metadata-cache';
-export { lint, type LintResult, type LintDiagnostic, type LintOptions, } from './linter';
-export { generateDocs, generateDocsMarkdown, type DocResult, type DocItem, type FunctionTypeInfo, type ParamTypeInfo, } from './docs';
-export { extractTests, assertFunction, expectFunction, testUtils, type ExtractedTest, type ExtractedMock, type TestExtractionResult, } from './tests';
-export { runtime, installRuntime, isError, error, typeOf, checkType, validateArgs, wrap, emitRuntimeWrapper, TJS_VERSION, type TJSError, } from './runtime';
-export { compileToWasm, instantiateWasm, registerWasmBlock, compileWasmBlocks, type WasmCompileResult, } from './wasm';
-export type { WasmBlock } from './parser';
-export { Eval, SafeFunction, type EvalOptions, type SafeFunctionOptions, } from './eval';
-export { hashSource, hashSourceSync, type CacheEntry, type CachedTranspileResult, type CachedTJSResult, type CacheStats, } from './metadata-cache';
-import { MetadataCache } from './metadata-cache';
-/**
- * Transpile JavaScript source code to Agent99 AST
- *
- * @param source - JavaScript source code containing a single function
- * @param options - Transpilation options
- * @returns The AST, signature, and any warnings
- *
- * @example
- * ```typescript
- * const result = transpile(`
- *   function search(query: 'string', limit = 10) {
- *     let results = storeSearch({ query, limit })
- *     return { results }
- *   }
- * `)
- *
- * console.log(result.signature)
- * // {
- * //   name: 'search',
- * //   parameters: {
- * //     query: { type: 'string', required: true },
- * //     limit: { type: 'number', required: false, default: 10 }
- * //   }
- * // }
- * ```
- */
-export declare function transpile(source: string, options?: TranspileOptions): TranspileResult;
-/**
- * Transpile AsyncJS source and return just the AST.
- * Works as both a function and a tagged template literal.
- *
- * @example
- * ```typescript
- * // As a function
- * const ast = ajs(`
- *   function agent({ topic }) {
- *     let results = search({ query: topic })
- *     return { results }
- *   }
- * `)
- *
- * // As a tagged template literal
- * const ast2 = ajs`
- *   function greet({ name }) {
- *     let msg = template({ tmpl: 'Hello {{name}}', vars: { name } })
- *     return { msg }
- *   }
- * `
- * ```
- */
-export declare function ajs(strings: TemplateStringsArray, ...values: any[]): SeqNode;
-export declare function ajs(source: string): SeqNode;
-/**
- * Transpile TJS source to JavaScript with type metadata.
- * Works as both a function and a tagged template literal.
- *
- * @example
- * ```typescript
- * // As a function
- * const result = tjs(`
- *   function greet(name: 'world') -> '' {
- *     return \`Hello, \${name}!\`
- *   }
- * `)
- * console.log(result.code)
- * // function greet(name = 'world') { return \`Hello, \${name}!\` }
- * // greet.__tjs = { params: { name: { type: 'string', required: true } }, returns: { type: 'string' } }
- *
- * // As a tagged template literal
- * const result2 = tjs`
- *   function add(a: 0, b: 0) -> 0 {
- *     return a + b
- *   }
- * `
- * ```
- */
-import { type TJSTranspileResult, type TJSTranspileOptions } from './emitters/js';
-export declare function tjs(strings: TemplateStringsArray, ...values: any[]): TJSTranspileResult;
-export declare function tjs(source: string, options?: TJSTranspileOptions): TJSTranspileResult;
-/**
- * Transpile with caching support
- *
- * Uses IndexedDB to cache transpilation results. On cache hit,
- * returns immediately without re-parsing. Particularly useful for
- * playground editors and development workflows.
- *
- * @example
- * ```typescript
- * const cache = new MetadataCache()
- * await cache.open()
- *
- * // First call: parses and caches
- * const result1 = await transpileWithCache(source, {}, cache)
- *
- * // Second call: returns from cache
- * const result2 = await transpileWithCache(source, {}, cache)
- * ```
- */
-export declare function transpileWithCache(source: string, options?: TranspileOptions, cache?: MetadataCache): Promise<TranspileResult>;
-/**
- * Transpile TJS to JavaScript with caching support
- *
- * @example
- * ```typescript
- * const cache = new MetadataCache()
- * await cache.open()
- *
- * // First call: transpiles and caches
- * const result1 = await tjsWithCache(source, {}, cache)
- *
- * // Second call: returns from cache
- * const result2 = await tjsWithCache(source, {}, cache)
- * ```
- */
-export declare function tjsWithCache(source: string, options?: import('./emitters/js').TJSTranspileOptions, cache?: MetadataCache): Promise<import('./emitters/js').TJSTranspileResult>;
-/**
- * Create a function with attached signature for introspection
- *
- * This wraps the transpiled AST in a callable that includes
- * the .signature property for self-documentation.
- *
- * @example
- * ```typescript
- * const search = createAgent(`
- *   function search(query: 'string', limit = 10) {
- *     let results = storeSearch({ query, limit })
- *     return { results }
- *   }
- * `, vm)
- *
- * // Introspect
- * console.log(search.signature.parameters)
- *
- * // Execute
- * const result = await search({ query: 'hello' })
- * ```
- */
-export declare function createAgent(source: string, vm: {
-    run: (ast: any, args: any, options?: any) => Promise<any>;
-}, runOptions?: {
-    fuel?: number;
-    capabilities?: any;
-}): ((args: Record<string, any>) => Promise<any>) & {
-    signature: FunctionSignature;
-    ast: SeqNode;
-};
-/**
- * Get tool definitions from a set of agent functions
- *
- * This converts function signatures to OpenAI-compatible tool definitions.
- *
- * @example
- * ```typescript
- * const search = createAgent(searchSource, vm)
- * const summarize = createAgent(summarizeSource, vm)
- *
- * const tools = getToolDefinitions({ search, summarize })
- * // Ready to pass to LLM API
- * ```
- */
-export declare function getToolDefinitions(agents: Record<string, {
-    signature: FunctionSignature;
-}>): Array<{
-    type: 'function';
-    function: {
-        name: string;
-        description?: string;
-        parameters: {
-            type: 'object';
-            properties: Record<string, any>;
-            required: string[];
-        };
-    };
-}>;

package/dist/src/lang/inference.d.ts

@@ -1,40 +0,0 @@
-/**
- * Type inference from value patterns
- *
- * Extracts types from example values:
- *   'string' -> { kind: 'string' }
- *   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' }] }
- */
-import type { Expression, Pattern } from 'acorn';
-import type { TypeDescriptor, ParameterDescriptor } from './types';
-/**
- * Infer type from a value expression (example value)
- */
-export declare function inferTypeFromValue(node: Expression): TypeDescriptor;
-/**
- * Parse a parameter and extract its type and default value
- *
- * @param param - The AST node for the parameter
- * @param requiredParams - Optional set of parameter names that are required (from colon syntax)
- */
-export declare function parseParameter(param: Pattern, requiredParams?: Set<string>): ParameterDescriptor;
-/**
- * Extract a literal value from an expression for default values
- */
-export declare function extractLiteralValue(node: Expression): any;
-/**
- * Parse return type from a type annotation expression
- */
-export declare function parseReturnType(typeExpr: string): TypeDescriptor;
-/**
- * Convert TypeDescriptor to a human-readable string
- */
-export declare function typeToString(type: TypeDescriptor): string;
-/**
- * Check if a value matches a type descriptor
- */
-export declare function checkType(value: any, type: TypeDescriptor): boolean;