@pwfabric/runtime 0.0.0-stage → 1.0.0-rc.0

package/dist/binding/engine.js

@@ -0,0 +1,268 @@
+/**
+ * Binding Engine
+ *
+ * Resolves and manages capability bindings for surfaces
+ *
+ * @module @pwfabric/runtime/binding/engine
+ */
+import { executionErr } from '@pwfabric/contracts';
+// ============================================================
+// RUNTIME BINDING ENGINE
+// ============================================================
+/**
+ * Runtime binding engine implementation
+ */
+export class RuntimeBindingEngine {
+    fabric;
+    cache;
+    contexts = new Map();
+    constructor(fabric, cache) {
+        this.fabric = fabric;
+        this.cache = cache;
+    }
+    bind(surfaceId, config) {
+        // Resolve capability from fabric
+        const resolution = this.fabric.resolve(config.capabilityId);
+        if (!resolution.found) {
+            return {
+                success: false,
+                error: {
+                    type: 'resolution_failed',
+                    message: `Capability ${config.capabilityId} not found`,
+                },
+            };
+        }
+        const alias = config.alias ?? config.capabilityId;
+        // Create bound capability
+        const boundCapability = this.createBoundCapability(surfaceId, alias, resolution.capability, config);
+        // Get or create context
+        let context = this.contexts.get(surfaceId);
+        if (!context) {
+            context = {
+                surfaceId,
+                data: {},
+                bindings: new Map(),
+            };
+            this.contexts.set(surfaceId, context);
+        }
+        // Add to bindings
+        context.bindings.set(alias, boundCapability);
+        return { success: true, binding: boundCapability };
+    }
+    bindAll(surfaceId, configs) {
+        const errors = [];
+        for (const config of configs) {
+            const result = this.bind(surfaceId, config);
+            if (!result.success) {
+                errors.push(result.error);
+            }
+        }
+        if (errors.length > 0) {
+            return { success: false, errors };
+        }
+        const context = this.contexts.get(surfaceId);
+        if (!context) {
+            return {
+                success: false,
+                errors: [{ type: 'resolution_failed', message: 'Context not created' }],
+            };
+        }
+        return { success: true, context };
+    }
+    get(surfaceId, alias) {
+        return this.contexts.get(surfaceId)?.bindings.get(alias);
+    }
+    unbind(surfaceId, alias) {
+        const context = this.contexts.get(surfaceId);
+        if (!context)
+            return false;
+        return context.bindings.delete(alias);
+    }
+    unbindAll(surfaceId) {
+        this.contexts.delete(surfaceId);
+    }
+    getContext(surfaceId) {
+        return this.contexts.get(surfaceId);
+    }
+    setAuthContext(surfaceId, auth) {
+        const existing = this.contexts.get(surfaceId);
+        if (existing) {
+            const updated = {
+                ...existing,
+                auth,
+            };
+            this.contexts.set(surfaceId, updated);
+        }
+        else {
+            this.contexts.set(surfaceId, {
+                surfaceId,
+                auth,
+                data: {},
+                bindings: new Map(),
+            });
+        }
+    }
+    createBoundCapability(surfaceId, alias, _capability, config) {
+        let state = 'bound';
+        let lastExecuted;
+        let lastResult;
+        let lastInput;
+        let error;
+        const execute = async (input) => {
+            state = 'binding';
+            lastInput = input;
+            try {
+                // Apply input transform if configured
+                let transformedInput = input;
+                if (config.transform?.input) {
+                    try {
+                        transformedInput = config.transform.input(input);
+                    }
+                    catch (e) {
+                        state = 'error';
+                        error = {
+                            type: 'transform_failed',
+                            message: `Input transform failed: ${e}`,
+                            cause: e,
+                        };
+                        const execError = {
+                            type: 'execution_error',
+                            message: error.message,
+                            capabilityId: config.capabilityId,
+                        };
+                        return executionErr(execError);
+                    }
+                }
+                // Check cache if enabled
+                if (config.cache?.enabled && this.cache) {
+                    const cacheKey = config.cache.key ?? `${surfaceId}:${alias}:${JSON.stringify(input)}`;
+                    const cached = await this.cache.get(cacheKey);
+                    if (cached !== undefined) {
+                        state = 'bound';
+                        lastExecuted = Date.now();
+                        lastResult = { success: true, data: cached };
+                        return lastResult;
+                    }
+                }
+                // Execute capability
+                const result = await this.fabric.execute(config.capabilityId, transformedInput);
+                if (result.success) {
+                    // Apply output transform if configured
+                    let output = result.data;
+                    if (config.transform?.output) {
+                        try {
+                            output = config.transform.output(output);
+                        }
+                        catch (e) {
+                            state = 'error';
+                            error = {
+                                type: 'transform_failed',
+                                message: `Output transform failed: ${e}`,
+                                cause: e,
+                            };
+                            const execError = {
+                                type: 'execution_error',
+                                message: error.message,
+                                capabilityId: config.capabilityId,
+                            };
+                            return executionErr(execError);
+                        }
+                    }
+                    // Store in cache if enabled
+                    if (config.cache?.enabled && this.cache) {
+                        const cacheKey = config.cache.key ?? `${surfaceId}:${alias}:${JSON.stringify(input)}`;
+                        await this.cache.set(cacheKey, output, config.cache.ttl);
+                    }
+                    state = 'bound';
+                    lastExecuted = Date.now();
+                    lastResult = { success: true, data: output };
+                    return lastResult;
+                }
+                else {
+                    state = 'error';
+                    error = {
+                        type: 'execution_failed',
+                        message: result.error.message,
+                        cause: result.error,
+                    };
+                    lastResult = result;
+                    return result;
+                }
+            }
+            catch (e) {
+                state = 'error';
+                error = {
+                    type: 'execution_failed',
+                    message: `Execution failed: ${e}`,
+                    cause: e,
+                };
+                const execError = {
+                    type: 'execution_error',
+                    message: error.message,
+                    capabilityId: config.capabilityId,
+                };
+                return executionErr(execError);
+            }
+        };
+        const refresh = async () => {
+            if (lastInput === undefined) {
+                const execError = {
+                    type: 'execution_error',
+                    message: 'No previous input to refresh',
+                    capabilityId: config.capabilityId,
+                };
+                return executionErr(execError);
+            }
+            return execute(lastInput);
+        };
+        const invalidate = () => {
+            state = 'stale';
+            if (config.cache?.enabled && this.cache) {
+                const cacheKey = config.cache.key ?? `${surfaceId}:${alias}:${JSON.stringify(lastInput)}`;
+                this.cache.delete(cacheKey);
+            }
+        };
+        const boundCapability = {
+            get id() {
+                return `${surfaceId}:${alias}`;
+            },
+            capabilityId: config.capabilityId,
+            get state() {
+                return state;
+            },
+            config,
+            execute,
+            refresh,
+            invalidate,
+        };
+        // Use Object.defineProperties for optional getters to satisfy exactOptionalPropertyTypes
+        Object.defineProperties(boundCapability, {
+            lastExecuted: {
+                get() {
+                    return lastExecuted;
+                },
+                enumerable: true,
+            },
+            lastResult: {
+                get() {
+                    return lastResult;
+                },
+                enumerable: true,
+            },
+            error: {
+                get() {
+                    return error;
+                },
+                enumerable: true,
+            },
+        });
+        return boundCapability;
+    }
+}
+/**
+ * Create a binding engine
+ */
+export function createBindingEngine(fabric, cache) {
+    return new RuntimeBindingEngine(fabric, cache);
+}
+//# sourceMappingURL=engine.js.map

package/dist/binding/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/binding/engine.ts"],"names":[],"mappings":"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"}

package/dist/binding/expression.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Expression Evaluator for Data Binding
+ *
+ * Enhanced expression evaluation for data binding in surfaces
+ *
+ * This module extends the base expression evaluator with:
+ * - Arithmetic operations (+, -, *, /, %)
+ * - Data/state/params context separation
+ * - Dependency extraction for reactive updates
+ * - Safe null-coalescing operators
+ *
+ * @module @pwfabric/runtime/binding/expression
+ */
+/**
+ * Context for expression evaluation in data binding
+ */
+export interface BindingExpressionContext {
+    /** Data from data sources */
+    readonly data: Record<string, unknown>;
+    /** State from state stores */
+    readonly state: Record<string, unknown>;
+    /** URL/route parameters */
+    readonly params: Record<string, unknown>;
+    /** Custom helper functions */
+    readonly helpers?: Record<string, (...args: unknown[]) => unknown>;
+}
+/**
+ * Result of expression evaluation
+ */
+export type ExpressionEvalResult<T = unknown> = {
+    readonly success: true;
+    readonly value: T;
+} | {
+    readonly success: false;
+    readonly error: string;
+};
+/**
+ * Expression evaluator interface for data binding
+ */
+export interface ExpressionEvaluator {
+    /**
+     * Evaluate an expression in the given context
+     */
+    evaluate(expression: string, context: BindingExpressionContext): unknown;
+    /**
+     * Check if a value is an expression (contains {{...}})
+     */
+    isExpression(value: unknown): boolean;
+    /**
+     * Extract dependencies from an expression for reactive updates
+     */
+    extractDependencies(expression: string): ExpressionDependency[];
+    /**
+     * Interpolate expressions in a template string
+     */
+    interpolate(template: string, context: BindingExpressionContext): string;
+}
+/**
+ * Dependency extracted from an expression
+ */
+export interface ExpressionDependency {
+    /** The source of the dependency */
+    readonly source: 'data' | 'state' | 'params';
+    /** The path within the source */
+    readonly path: string;
+}
+/**
+ * Read one named property off a value, stepping into a list of one record.
+ *
+ * A LIST SOURCE ALWAYS BINDS AS A LIST (DataBoundSurfaceRenderer): a `rest`,
+ * `entity` or `graphql` source answering with ONE object is bound as `[obj]`,
+ * so `{{src[0].field}}` and `{{src.length}}` behave the same whatever the
+ * endpoint returned. But a detail page is authored as `{{product.title}}`, and
+ * a property read on an array finds nothing — such a page would render blank
+ * (`{{rows.name}}` → empty while `{{rows[0].name}}` → "banana").
+ *
+ * So: when the value is an array of EXACTLY ONE element and the array itself
+ * does not carry the key (not `length`, not an index, not an array method),
+ * the read continues into that one element. A list of two or more is a list —
+ * its `.title` stays undefined, as it always was. Both evaluators (this one
+ * and surface/expression) read properties through here, so a path means the
+ * same thing in a binding and in a block prop.
+ */
+export declare function readProperty(target: unknown, key: string): unknown;
+/**
+ * Resolve a dotted path in an object, handling nested properties and array indices
+ *
+ * @example
+ * resolvePath({ user: { name: 'John' } }, 'user.name') // 'John'
+ * resolvePath({ items: ['a', 'b'] }, 'items[0]') // 'a'
+ * resolvePath({ users: [{ name: 'John' }] }, 'users[0].name') // 'John'
+ */
+export declare function resolvePath(obj: unknown, path: string): unknown;
+/** Lexical options — the only grammar differences between the two callers. */
+export interface ExpressionSyntaxOptions {
+    /**
+     * `hero-stats-data.0.text` is ONE name. Surface data-source ids are
+     * hyphenated, and the surface evaluator always read them as paths, so in
+     * that mode a `-` between two name characters with no space around it is
+     * part of the name. Subtraction needs spaces there: `a - b`.
+     */
+    readonly hyphenNames?: boolean;
+    /** The binding evaluator has always read the literal `undefined` as `null`. */
+    readonly undefinedAsNull?: boolean;
+}
+/**
+ * How a bare name and a call resolve. The grammar is shared; the scope is the
+ * caller's: bindings see `data` / `state` / `params`, block props see the
+ * surface's expression data (`state`, source ids, `item`, `__errors`, …).
+ */
+export interface NameResolver {
+    /** The value of a bare name. */
+    lookup(name: string): unknown;
+    /** The helper a call names, or undefined when there is none. */
+    helper(name: string): ((...args: unknown[]) => unknown) | undefined;
+}
+/**
+ * Evaluate one expression (the text between `{{` and `}}`) against a scope.
+ * Throws on a syntax error, an unknown helper or an unsupported method — the
+ * two public evaluators turn that into `{ success: false }`.
+ */
+export declare function evaluateWithScope(expression: string, scope: NameResolver, opts?: ExpressionSyntaxOptions): unknown;
+/**
+ * Evaluate an expression with full context support
+ */
+export declare function evaluateExpression(expression: string, context: BindingExpressionContext): ExpressionEvalResult;
+/**
+ * Extract dependencies from an expression for reactive updates
+ */
+export declare function extractDependencies(expression: string): ExpressionDependency[];
+/**
+ * Check if a value contains expression syntax
+ */
+export declare function isExpression(value: unknown): boolean;
+/**
+ * Interpolate expressions within a template string
+ *
+ * @example
+ * interpolate('Hello, {{user.name}}!', context) // 'Hello, John!'
+ * interpolate('Total: {{price * quantity}}', context) // 'Total: 100'
+ */
+export declare function interpolate(template: string, context: BindingExpressionContext): string;
+/**
+ * Default helper functions for expressions
+ */
+export declare const DEFAULT_BINDING_HELPERS: Record<string, (...args: unknown[]) => unknown>;
+/**
+ * Create an expression evaluator with context and helpers
+ */
+export declare function createExpressionEvaluator(additionalHelpers?: Record<string, (...args: unknown[]) => unknown>): ExpressionEvaluator;
+//# sourceMappingURL=expression.d.ts.map

package/dist/binding/expression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression.d.ts","sourceRoot":"","sources":["../../src/binding/expression.ts"],"names":[],"mappings":"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"}