tjs-lang 0.6.26 → 0.6.27

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

@@ -0,0 +1,147 @@
+/**
+ * Type definitions for the Agent99 JavaScript transpiler
+ */
+import type { Node } from 'acorn';
+import type { SeqNode } from '../builder';
+/** Represents a type extracted from value patterns */
+export interface TypeDescriptor {
+    kind: 'string' | 'number' | 'integer' | 'non-negative-integer' | 'boolean' | 'null' | 'undefined' | 'array' | 'object' | 'union' | 'any';
+    nullable?: boolean;
+    /** For arrays: the element type */
+    items?: TypeDescriptor;
+    /** For objects: the shape */
+    shape?: Record<string, TypeDescriptor>;
+    /** For unions: the member types */
+    members?: TypeDescriptor[];
+    /** For destructured parameters: full parameter descriptors */
+    destructuredParams?: Record<string, ParameterDescriptor>;
+}
+/** Describes a function parameter */
+export interface ParameterDescriptor {
+    name: string;
+    type: TypeDescriptor;
+    required: boolean;
+    default?: any;
+    /** The example value used to infer the type (for autocomplete) */
+    example?: any;
+    description?: string;
+    /** Source location for error reporting */
+    loc?: {
+        start: number;
+        end: number;
+    };
+}
+/** Describes a function's complete signature */
+export interface FunctionSignature {
+    name: string;
+    description?: string;
+    parameters: Record<string, ParameterDescriptor>;
+    returns?: TypeDescriptor;
+}
+/** Options for the transpile function */
+export interface TranspileOptions {
+    /** Include source locations in output AST */
+    sourceMaps?: boolean;
+    /** Atom registry for validation (optional) */
+    atoms?: Record<string, {
+        op: string;
+    }>;
+    /** Filename for error messages */
+    filename?: string;
+    /** Whether to use strict type checking */
+    strict?: boolean;
+}
+/** Result of transpilation */
+export interface TranspileResult {
+    /** The Agent99 AST */
+    ast: SeqNode;
+    /** The function signature with types */
+    signature: FunctionSignature;
+    /** Source map (if enabled) */
+    sourceMap?: SourceMap;
+    /** Warnings (non-fatal issues) */
+    warnings: TranspileWarning[];
+}
+/** A non-fatal warning during transpilation */
+export interface TranspileWarning {
+    message: string;
+    line: number;
+    column: number;
+    source?: string;
+}
+/** Source map for debugging */
+export interface SourceMap {
+    version: 3;
+    file: string;
+    sources: string[];
+    mappings: string;
+}
+/** Base class for transpiler errors with source location */
+export declare class TranspileError extends Error {
+    line: number;
+    column: number;
+    source?: string;
+    filename?: string;
+    constructor(message: string, location: {
+        line: number;
+        column: number;
+    }, source?: string, filename?: string);
+}
+/** Syntax error during parsing */
+export declare class SyntaxError extends TranspileError {
+    constructor(message: string, location: {
+        line: number;
+        column: number;
+    }, source?: string, filename?: string);
+    /**
+     * Format the error with source context for better debugging
+     * Shows the problematic line with a caret pointing to the error location
+     */
+    formatWithContext(contextLines?: number): string;
+}
+/** Type error during transpilation or runtime */
+export declare class TypeError extends TranspileError {
+    expected?: string;
+    received?: string;
+    suggestion?: string;
+    constructor(message: string, location: {
+        line: number;
+        column: number;
+    }, options?: {
+        expected?: string;
+        received?: string;
+        suggestion?: string;
+        source?: string;
+        filename?: string;
+    });
+}
+/** Context passed through the transformer */
+export interface TransformContext {
+    /** Current scope depth */
+    depth: number;
+    /** Variables declared in current scope with their types */
+    locals: Map<string, TypeDescriptor>;
+    /** Parent scope's context (for scope chain) */
+    parent?: TransformContext;
+    /** Function parameters */
+    parameters: Map<string, ParameterDescriptor>;
+    /** Registered atom names */
+    atoms: Set<string>;
+    /** Accumulated warnings */
+    warnings: TranspileWarning[];
+    /** Source code for error messages */
+    source: string;
+    /** Filename */
+    filename: string;
+    /** Options */
+    options: TranspileOptions;
+}
+/** Create a child context for nested scopes */
+export declare function createChildContext(parent: TransformContext): TransformContext;
+/** Look up a variable in the scope chain */
+export declare function lookupVariable(name: string, ctx: TransformContext): TypeDescriptor | undefined;
+/** Extract location from an Acorn node */
+export declare function getLocation(node: Node): {
+    line: number;
+    column: number;
+};

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

@@ -0,0 +1,83 @@
+/**
+ * TJS to WebAssembly Compiler
+ *
+ * Compiles a subset of TJS to WebAssembly for performance-critical code.
+ *
+ * Supported features:
+ * - Numeric operations (+, -, *, /, %)
+ * - Typed arrays (Float32Array, Float64Array, Int32Array, Uint8Array)
+ * - For loops with numeric bounds
+ * - Math functions (sin, cos, sqrt, abs, floor, ceil, min, max)
+ * - Basic conditionals (if/else)
+ * - Variable declarations (let)
+ *
+ * The goal is to enable real-world WASM acceleration for hot paths like
+ * audio processing, image manipulation, and physics simulations.
+ */
+import type { WasmBlock } from './parser';
+/** Compile result */
+export interface WasmCompileResult {
+    /** The compiled WebAssembly module bytes */
+    bytes: Uint8Array;
+    /** Any warnings during compilation */
+    warnings: string[];
+    /** Whether compilation succeeded */
+    success: boolean;
+    /** Error message if compilation failed */
+    error?: string;
+    /** Whether the module needs imported memory */
+    needsMemory?: boolean;
+    /** WAT text representation (for debugging) */
+    wat?: string;
+}
+/**
+ * Compile a WASM block to WebAssembly
+ */
+export declare function compileToWasm(block: WasmBlock): WasmCompileResult;
+/**
+ * Instantiate a compiled WASM module
+ */
+export declare function instantiateWasm(bytes: Uint8Array, memory?: WebAssembly.Memory): Promise<WebAssembly.Instance>;
+/**
+ * Create a callable function from a WASM block with typed array support
+ */
+export declare function createWasmFunction(block: WasmBlock): Promise<{
+    fn: (...args: any[]) => any;
+    memory?: WebAssembly.Memory;
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Compile and register a WASM block globally
+ */
+export declare function registerWasmBlock(block: WasmBlock): Promise<boolean>;
+/**
+ * Compile all WASM blocks from a preprocessed source
+ */
+export declare function compileWasmBlocks(blocks: WasmBlock[]): Promise<{
+    compiled: number;
+    failed: number;
+    errors: string[];
+}>;
+/**
+ * Compiled WASM data that can be serialized and passed to an iframe
+ */
+export interface CompiledWasmData {
+    id: string;
+    bytes: number[];
+    captures: string[];
+    needsMemory: boolean;
+}
+/**
+ * Compile WASM blocks and return serializable data for iframe instantiation
+ */
+export declare function compileWasmBlocksForIframe(blocks: WasmBlock[]): Promise<{
+    compiled: CompiledWasmData[];
+    failed: number;
+    errors: string[];
+}>;
+/**
+ * Generate JavaScript code that instantiates compiled WASM in an iframe
+ * This code should be injected into the iframe's script
+ */
+export declare function generateWasmInstantiationCode(compiledBlocks: CompiledWasmData[]): string;

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

@@ -0,0 +1,85 @@
+import type { Store } from '../store/interface';
+export { evaluateAccessShortcut, selectAccessRule, validateSchema, interpretRuleResult, hasRoleLevel, buildRuleContext, } from './rules.js';
+/**
+ * Security rule definition
+ */
+export interface SecurityRule {
+    /** Rule for read operations */
+    read?: string | {
+        code: string;
+        fuel?: number;
+    };
+    /** Rule for write operations (fallback for create/update) */
+    write?: string | {
+        code: string;
+        fuel?: number;
+    };
+    /** Rule for create operations */
+    create?: string | {
+        code: string;
+        fuel?: number;
+    };
+    /** Rule for update operations */
+    update?: string | {
+        code: string;
+        fuel?: number;
+    };
+    /** Rule for delete operations */
+    delete?: string | {
+        code: string;
+        fuel?: number;
+    };
+    /** Legacy: single code rule for all operations */
+    code?: string;
+    /** Schema validation for writes */
+    schema?: {
+        required?: string[];
+        properties?: Record<string, {
+            type: string;
+        }>;
+    };
+    /** Max fuel for AJS evaluation */
+    fuel?: number;
+    /** Timeout for AJS evaluation */
+    timeoutMs?: number;
+}
+/**
+ * Access check options
+ */
+export interface CheckOptions {
+    uid?: string | null;
+    roles?: string[];
+    method: 'read' | 'write' | 'delete';
+    collection: string;
+    docId?: string | null;
+    doc?: Record<string, any> | null;
+    newData?: Record<string, any> | null;
+}
+/**
+ * Access check result
+ */
+export interface CheckResult {
+    allowed: boolean;
+    reason?: string;
+    ruleType: 'shortcut' | 'schema' | 'code' | 'default' | 'error';
+    evalTimeMs: number;
+}
+/**
+ * RBAC instance with store backend
+ */
+export interface RBAC {
+    /** Check if an operation is allowed */
+    check(options: CheckOptions): Promise<CheckResult>;
+    /** Set a security rule for a collection */
+    setRule(collection: string, rule: SecurityRule): Promise<void>;
+    /** Get the security rule for a collection */
+    getRule(collection: string): Promise<SecurityRule | null>;
+    /** Delete a security rule */
+    deleteRule(collection: string): Promise<void>;
+    /** Load user roles from store */
+    loadUserRoles(uid: string): Promise<string[]>;
+}
+/**
+ * Create an RBAC instance with a store backend
+ */
+export declare function createRBAC(store: Store): RBAC;

package/dist/src/rbac/rules.d.ts

@@ -0,0 +1,184 @@
+export function evaluateAccessShortcut(accessRule: any, context: any): {
+    allowed: boolean;
+    reason: string;
+} | {
+    allowed: boolean;
+    reason?: undefined;
+} | null;
+export namespace evaluateAccessShortcut {
+    namespace __tjs {
+        namespace params {
+            namespace accessRule {
+                namespace type {
+                    let kind: string;
+                }
+                let required: boolean;
+            }
+            namespace context {
+                export namespace type_1 {
+                    let kind_1: string;
+                    export { kind_1 as kind };
+                }
+                export { type_1 as type };
+                let required_1: boolean;
+                export { required_1 as required };
+            }
+        }
+        let unsafe: boolean;
+        let source: string;
+    }
+}
+export function selectAccessRule(rule: any, context: any): any;
+export namespace selectAccessRule {
+    export namespace __tjs_1 {
+        export namespace params_1 {
+            export namespace rule {
+                export namespace type_2 {
+                    let kind_2: string;
+                    export { kind_2 as kind };
+                }
+                export { type_2 as type };
+                let required_2: boolean;
+                export { required_2 as required };
+            }
+            export namespace context_1 {
+                export namespace type_3 {
+                    let kind_3: string;
+                    export { kind_3 as kind };
+                }
+                export { type_3 as type };
+                let required_3: boolean;
+                export { required_3 as required };
+            }
+            export { context_1 as context };
+        }
+        export { params_1 as params };
+        let unsafe_1: boolean;
+        export { unsafe_1 as unsafe };
+        let source_1: string;
+        export { source_1 as source };
+    }
+    export { __tjs_1 as __tjs };
+}
+export function validateSchema(schema: any, data: any): {
+    valid: boolean;
+    errors: string[];
+};
+export namespace validateSchema {
+    export namespace __tjs_2 {
+        export namespace params_2 {
+            namespace schema {
+                export namespace type_4 {
+                    let kind_4: string;
+                    export { kind_4 as kind };
+                }
+                export { type_4 as type };
+                let required_4: boolean;
+                export { required_4 as required };
+            }
+            namespace data {
+                export namespace type_5 {
+                    let kind_5: string;
+                    export { kind_5 as kind };
+                }
+                export { type_5 as type };
+                let required_5: boolean;
+                export { required_5 as required };
+            }
+        }
+        export { params_2 as params };
+        let unsafe_2: boolean;
+        export { unsafe_2 as unsafe };
+        let source_2: string;
+        export { source_2 as source };
+    }
+    export { __tjs_2 as __tjs };
+}
+export function interpretRuleResult(result: any): {
+    allowed: boolean;
+    reason: any;
+};
+export namespace interpretRuleResult {
+    export namespace __tjs_3 {
+        export namespace params_3 {
+            namespace result {
+                export namespace type_6 {
+                    let kind_6: string;
+                    export { kind_6 as kind };
+                }
+                export { type_6 as type };
+                let required_6: boolean;
+                export { required_6 as required };
+            }
+        }
+        export { params_3 as params };
+        let unsafe_3: boolean;
+        export { unsafe_3 as unsafe };
+        let source_3: string;
+        export { source_3 as source };
+    }
+    export { __tjs_3 as __tjs };
+}
+export function hasRoleLevel(userRoles: any, requiredRole: any): boolean;
+export namespace hasRoleLevel {
+    export namespace __tjs_4 {
+        export namespace params_4 {
+            namespace userRoles {
+                export namespace type_7 {
+                    let kind_7: string;
+                    export { kind_7 as kind };
+                }
+                export { type_7 as type };
+                let required_7: boolean;
+                export { required_7 as required };
+            }
+            namespace requiredRole {
+                export namespace type_8 {
+                    let kind_8: string;
+                    export { kind_8 as kind };
+                }
+                export { type_8 as type };
+                let required_8: boolean;
+                export { required_8 as required };
+            }
+        }
+        export { params_4 as params };
+        let unsafe_4: boolean;
+        export { unsafe_4 as unsafe };
+        let source_4: string;
+        export { source_4 as source };
+    }
+    export { __tjs_4 as __tjs };
+}
+export function buildRuleContext(options: any): {
+    _uid: any;
+    _roles: any;
+    _isAdmin: any;
+    _isAuthor: any;
+    _method: any;
+    _collection: any;
+    _docId: any;
+    doc: any;
+    newData: any;
+};
+export namespace buildRuleContext {
+    export namespace __tjs_5 {
+        export namespace params_5 {
+            namespace options {
+                export namespace type_9 {
+                    let kind_9: string;
+                    export { kind_9 as kind };
+                }
+                export { type_9 as type };
+                let required_9: boolean;
+                export { required_9 as required };
+            }
+        }
+        export { params_5 as params };
+        let unsafe_5: boolean;
+        export { unsafe_5 as unsafe };
+        let source_5: string;
+        export { source_5 as source };
+    }
+    export { __tjs_5 as __tjs };
+}

package/dist/src/runtime.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @deprecated Import from './vm/runtime' instead
+ */
+export * from './vm/runtime';

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

@@ -0,0 +1,3 @@
+export type { Store, Doc, QueryConstraints, WhereClause, WriteResult, StoreFactory, } from './interface';
+export { createMemoryStore, getMemoryStore, resetMemoryStore } from './memory';
+export { createIndexedDBStore, getIndexedDBStore } from './indexeddb';

package/dist/src/store/indexeddb.d.ts

@@ -0,0 +1,6 @@
+import type { Store } from './interface';
+/**
+ * Create an IndexedDB-backed store
+ */
+export declare function createIndexedDBStore(): Store;
+export declare function getIndexedDBStore(): Store;

package/dist/src/store/interface.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Where clause for queries
+ */
+export interface WhereClause {
+    field: string;
+    op: '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'not-in' | 'array-contains';
+    value: any;
+}
+/**
+ * Query constraints
+ */
+export interface QueryConstraints {
+    where?: WhereClause[];
+    orderBy?: string;
+    orderDirection?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Document with ID
+ */
+export interface Doc<T = Record<string, any>> {
+    id: string;
+    data: T;
+}
+/**
+ * Result of a write operation
+ */
+export interface WriteResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Abstract store interface
+ *
+ * All methods are async to support both sync (IndexedDB) and
+ * async (Firestore, Postgres) backends.
+ */
+export interface Store {
+    /**
+     * Get a document by ID
+     * Returns null if not found
+     */
+    get(collection: string, id: string): Promise<Record<string, any> | null>;
+    /**
+     * Set a document (create or update)
+     * If merge is true, only updates provided fields
+     */
+    set(collection: string, id: string, data: Record<string, any>, options?: {
+        merge?: boolean;
+    }): Promise<WriteResult>;
+    /**
+     * Delete a document
+     */
+    delete(collection: string, id: string): Promise<WriteResult>;
+    /**
+     * Query documents in a collection
+     */
+    query(collection: string, constraints?: QueryConstraints): Promise<Doc[]>;
+    /**
+     * Check if a document exists
+     */
+    exists(collection: string, id: string): Promise<boolean>;
+    /**
+     * Generate a unique ID for a new document
+     */
+    generateId(collection: string): string;
+    /**
+     * Batch write operations (atomic)
+     * Optional - not all backends support transactions
+     */
+    batch?(operations: Array<{
+        type: 'set';
+        collection: string;
+        id: string;
+        data: Record<string, any>;
+    } | {
+        type: 'delete';
+        collection: string;
+        id: string;
+    }>): Promise<WriteResult>;
+    /**
+     * Clear all data (for testing)
+     */
+    clear?(): Promise<void>;
+}
+/**
+ * Factory function type for creating stores
+ */
+export type StoreFactory = () => Store | Promise<Store>;

package/dist/src/store/memory.d.ts

@@ -0,0 +1,10 @@
+import type { Store } from './interface';
+/**
+ * Create an in-memory store
+ */
+export declare function createMemoryStore(): Store;
+export declare function getMemoryStore(): Store;
+/**
+ * Reset the default store (for tests)
+ */
+export declare function resetMemoryStore(): void;

package/dist/src/test-examples.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Helpers for loading and testing playground example markdown files.
+ *
+ * Usage:
+ *   import { loadExample, loadExamples } from './test-examples'
+ *
+ *   const ex = loadExample('guides/examples/tjs/wasm-starfield.md')
+ *   // ex.code     — the source code from the first code block
+ *   // ex.language — 'tjs', 'ajs', 'javascript', etc.
+ *   // ex.title    — from the markdown # heading
+ *   // ex.metadata — parsed JSON from <!--{...}--> comment
+ *
+ *   const all = loadExamples('guides/examples/tjs')
+ *   // array of all examples in that directory
+ */
+export interface ExampleFile {
+    /** Absolute or relative path to the source .md file */
+    path: string;
+    /** Title from the first # heading */
+    title: string;
+    /** Description — first paragraph between title and code block */
+    description: string;
+    /** Source code from the first fenced code block */
+    code: string;
+    /** Language tag from the code fence (e.g. 'tjs', 'ajs', 'javascript') */
+    language: string;
+    /** Parsed metadata from the <!--{...}--> comment, if present */
+    metadata: Record<string, any>;
+}
+/**
+ * Load a single example from a markdown file.
+ */
+export declare function loadExample(filePath: string): ExampleFile;
+/**
+ * Load all .md examples from a directory.
+ */
+export declare function loadExamples(dirPath: string): ExampleFile[];
+/**
+ * Parse example content from markdown source.
+ */
+export declare function parseExample(content: string, filePath?: string): ExampleFile;