@creact-labs/creact 0.1.7 → 0.2.0

package/dist/primitives/instance.js

@@ -0,0 +1,235 @@
+/**
+ * useInstance - bind to a provider and get reactive outputs
+ */
+import { createSignal } from '../reactive/signal';
+import { batch } from '../reactive/tracking';
+import { getCurrentFiber, getCurrentResourcePath, pushResourcePath } from '../runtime/render';
+// Registry of all instance nodes by ID
+const nodeRegistry = new Map();
+// Track which fiber owns each nodeId (to detect duplicate siblings)
+const nodeOwnership = new Map();
+// Output hydration map - populated before render to restore outputs from previous run
+const outputHydrationMap = new Map();
+/**
+ * Prepare output hydration from serialized nodes
+ * Called by runtime BEFORE rendering to restore outputs
+ */
+export function prepareOutputHydration(serializedNodes) {
+    outputHydrationMap.clear();
+    for (const node of serializedNodes) {
+        if (node.outputs && Object.keys(node.outputs).length > 0) {
+            outputHydrationMap.set(node.id, node.outputs);
+        }
+    }
+}
+/**
+ * Clear output hydration map
+ */
+export function clearOutputHydration() {
+    outputHydrationMap.clear();
+}
+/**
+ * Create a placeholder proxy that returns undefined for all outputs
+ * Used when props have undefined dependencies - node won't be created yet
+ */
+function createPlaceholderProxy() {
+    return new Proxy({}, {
+        get(_target, _key) {
+            return () => undefined; // All outputs return undefined
+        },
+    });
+}
+/**
+ * Create an instance bound to a provider
+ */
+export function useInstance(construct, props) {
+    const fiber = getCurrentFiber();
+    if (!fiber) {
+        throw new Error('useInstance must be called during render');
+    }
+    // Enforce one instance per component - forces proper JSX composition
+    // Each component = one resource, compose via children
+    if (fiber.instanceNodes.length > 0 || fiber.hasPlaceholderInstance) {
+        throw new Error('useInstance can only be called once per component. ' +
+            'Use child components for additional resources:\n\n' +
+            '  function MyStack() {\n' +
+            '    const db = useInstance(Database, { name: "main" });\n' +
+            '    return <Cache dbUrl={db.url()} />;\n' +
+            '  }\n\n' +
+            '  function Cache({ dbUrl }) {\n' +
+            '    useInstance(CacheService, { db: dbUrl });\n' +
+            '    return null;\n' +
+            '  }');
+    }
+    // Generate deterministic ID using resource path (not fiber path)
+    // This makes wrapper components transparent - they don't affect resource IDs
+    const currentResourcePath = getCurrentResourcePath();
+    const name = getNodeName(construct, fiber.key);
+    const fullPath = [...currentResourcePath, name];
+    const nodeId = fullPath.join('.');
+    // Check for undefined dependencies BEFORE creating/updating node
+    // If any prop is undefined, return placeholder - don't create node in registry
+    const hasUndefinedDeps = Object.values(props).some((v) => v === undefined);
+    if (hasUndefinedDeps) {
+        // STILL push to resource path so children have correct paths
+        pushResourcePath(name);
+        // Mark fiber as having a placeholder instance (for proper path pop in render.ts)
+        fiber.hasPlaceholderInstance = true;
+        return createPlaceholderProxy();
+    }
+    const constructType = construct.name || 'Unknown';
+    // Check for duplicate siblings (requires keys)
+    // Allow same fiber to re-register (reactive re-render), but not different fibers
+    const existingOwner = nodeOwnership.get(nodeId);
+    if (existingOwner && existingOwner !== fiber) {
+        throw new Error(`Multiple instances of ${constructType} at the same level require unique keys.\n` +
+            `Add a key prop to differentiate them:\n\n` +
+            `  {items.map((item) => (\n` +
+            `    <MyResource key={item.id} ... />\n` +
+            `  ))}`);
+    }
+    nodeOwnership.set(nodeId, fiber);
+    // Create or get existing node
+    let node = nodeRegistry.get(nodeId);
+    if (!node) {
+        node = {
+            id: nodeId,
+            path: fullPath,
+            construct,
+            constructType,
+            props,
+            outputSignals: new Map(),
+            children: [],
+            setOutputs(outputs) {
+                // Clear ownership before batch triggers re-renders
+                // When signals update, components re-execute and create new fibers
+                // that need to claim the same nodeIds
+                nodeOwnership.clear();
+                batch(() => {
+                    for (const [key, value] of Object.entries(outputs)) {
+                        if (!this.outputSignals.has(key)) {
+                            this.outputSignals.set(key, createSignal(value));
+                        }
+                        else {
+                            const [, write] = this.outputSignals.get(key);
+                            write(value);
+                        }
+                    }
+                });
+            },
+        };
+        nodeRegistry.set(nodeId, node);
+    }
+    else {
+        // Update props
+        node.props = props;
+    }
+    // Push to resource path so children see this component in their path
+    pushResourcePath(name);
+    // Hydrate outputs from previous run (if available)
+    const hydratedOutputs = outputHydrationMap.get(nodeId);
+    if (hydratedOutputs) {
+        for (const [key, value] of Object.entries(hydratedOutputs)) {
+            if (!node.outputSignals.has(key)) {
+                node.outputSignals.set(key, createSignal(value));
+            }
+            else {
+                const [, write] = node.outputSignals.get(key);
+                write(value);
+            }
+        }
+    }
+    // Attach to fiber
+    fiber.instanceNodes.push(node);
+    // Return proxy where each property access returns a wrapper function
+    // that auto-unwraps accessors (SolidJS-style)
+    return new Proxy({}, {
+        get(_, key) {
+            // Lazily create signal for this output
+            if (!node.outputSignals.has(key)) {
+                node.outputSignals.set(key, createSignal());
+            }
+            // biome-ignore lint/style/noNonNullAssertion: we just ensured the key exists above
+            const [read] = node.outputSignals.get(key);
+            // Return wrapper that auto-unwraps accessors
+            return () => {
+                const value = read(); // Read from signal (tracks it)
+                // If provider returned an accessor, call it (tracks provider's signal)
+                if (typeof value === 'function') {
+                    return value();
+                }
+                return value;
+            };
+        },
+    });
+}
+/**
+ * Generate a node name from construct and fiber key
+ */
+function getNodeName(construct, key) {
+    const baseName = construct.name || 'Instance';
+    const kebab = toKebabCase(baseName);
+    if (key !== undefined) {
+        return `${kebab}-${key}`;
+    }
+    return kebab;
+}
+/**
+ * Convert PascalCase to kebab-case
+ */
+function toKebabCase(str) {
+    return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+/**
+ * Fill instance outputs (called by runtime after provider returns)
+ * @internal
+ */
+export function fillInstanceOutputs(nodeId, outputs) {
+    const node = nodeRegistry.get(nodeId);
+    if (!node)
+        return;
+    // Clear ownership before batch triggers re-renders
+    // When signals update, components re-execute and create new fibers
+    // that need to claim the same nodeIds
+    nodeOwnership.clear();
+    batch(() => {
+        for (const [key, value] of Object.entries(outputs)) {
+            if (node.outputSignals.has(key)) {
+                const [, write] = node.outputSignals.get(key);
+                write(value); // Write value (plain or accessor) to signal
+            }
+            else {
+                node.outputSignals.set(key, createSignal(value));
+            }
+        }
+    });
+}
+/**
+ * Get a node by ID
+ * @internal
+ */
+export function getNodeById(nodeId) {
+    return nodeRegistry.get(nodeId);
+}
+/**
+ * Get all registered nodes
+ * @internal
+ */
+export function getAllNodes() {
+    return Array.from(nodeRegistry.values());
+}
+/**
+ * Clear node registry (for testing)
+ * @internal
+ */
+export function clearNodeRegistry() {
+    nodeRegistry.clear();
+    nodeOwnership.clear();
+}
+/**
+ * Clear node ownership (call at start of each render pass)
+ * @internal
+ */
+export function clearNodeOwnership() {
+    nodeOwnership.clear();
+}

package/dist/primitives/store.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Store - persistent state (non-reactive)
+ */
+export type SetStoreFunction<T> = {
+    <K extends keyof T>(key: K, value: T[K] | ((prev: T[K]) => T[K])): void;
+    <K1 extends keyof T, K2 extends keyof T[K1]>(k1: K1, k2: K2, value: T[K1][K2] | ((prev: T[K1][K2]) => T[K1][K2])): void;
+    (...args: any[]): void;
+};
+/**
+ * Create a persistent store (non-reactive)
+ */
+export declare function createStore<T extends object>(initial: T): [T, SetStoreFunction<T>];
+/**
+ * Prepare hydration from previous nodes
+ * @internal
+ */
+export declare function prepareHydration(previousNodes: any[]): void;
+/**
+ * Clear hydration map (for testing)
+ * @internal
+ */
+export declare function clearHydration(): void;

package/dist/primitives/store.js

@@ -0,0 +1,97 @@
+/**
+ * Store - persistent state (non-reactive)
+ */
+import { getCurrentFiber } from '../runtime/render';
+// Hydration map for restoring state across cycles
+// biome-ignore lint/suspicious/noExplicitAny: stores hold user-defined state of any type
+const hydrationMap = new Map();
+/**
+ * Create a persistent store (non-reactive)
+ */
+export function createStore(initial) {
+    const fiber = getCurrentFiber();
+    // Try to hydrate from previous cycle
+    const hydrated = fiber ? hydrateStore(fiber.path) : undefined;
+    const state = hydrated ?? { ...initial };
+    // Mark for persistence
+    if (fiber) {
+        fiber.store = state;
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: rest args for deep path updates
+    function setStore(...args) {
+        updatePath(state, args);
+    }
+    return [state, setStore];
+}
+/**
+ * Update a nested path in an object
+ */
+// biome-ignore lint/suspicious/noExplicitAny: operates on arbitrary nested objects
+function updatePath(obj, args) {
+    if (args.length === 2) {
+        const [key, value] = args;
+        obj[key] = typeof value === 'function' ? value(obj[key]) : value;
+    }
+    else if (args.length > 2) {
+        const key = args[0];
+        if (obj[key] === undefined) {
+            obj[key] = {};
+        }
+        updatePath(obj[key], args.slice(1));
+    }
+}
+/**
+ * Prepare hydration from previous nodes
+ * @internal
+ */
+// biome-ignore lint/suspicious/noExplicitAny: accepts serialized nodes with arbitrary structure
+export function prepareHydration(previousNodes) {
+    hydrationMap.clear();
+    for (const node of flattenNodes(previousNodes)) {
+        if (node.store) {
+            // Key by component path (parent of node)
+            const componentPath = node.path.slice(0, -1).join('.');
+            hydrationMap.set(componentPath, node.store);
+        }
+    }
+}
+/**
+ * Hydrate store from previous cycle
+ * Returns a deep clone to ensure previous and current stores are independent
+ */
+function hydrateStore(fiberPath) {
+    if (!fiberPath)
+        return undefined;
+    const key = fiberPath.join('.');
+    const stored = hydrationMap.get(key);
+    // Deep clone to ensure independence between runs
+    return stored ? JSON.parse(JSON.stringify(stored)) : undefined;
+}
+/**
+ * Flatten nested nodes
+ */
+// biome-ignore lint/suspicious/noExplicitAny: operates on serialized nodes with arbitrary structure
+function flattenNodes(nodes) {
+    // biome-ignore lint/suspicious/noExplicitAny: accumulates serialized nodes
+    const result = [];
+    // biome-ignore lint/suspicious/noExplicitAny: serialized node structure
+    function walk(node) {
+        result.push(node);
+        if (node.children) {
+            for (const child of node.children) {
+                walk(child);
+            }
+        }
+    }
+    for (const node of nodes) {
+        walk(node);
+    }
+    return result;
+}
+/**
+ * Clear hydration map (for testing)
+ * @internal
+ */
+export function clearHydration() {
+    hydrationMap.clear();
+}

package/dist/provider/backend.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Backend interface - abstracts state persistence
+ *
+ * The Backend enables:
+ * - Resume from crash (nodes with outputs are treated as deployed)
+ * - Incremental deploys (only changed resources)
+ * - State hydration (createStore values restored)
+ * - Drift detection (compare expected vs actual)
+ */
+import type { InstanceNode } from '../primitives/instance';
+/**
+ * Resource deployment state
+ */
+export type ResourceState = 'pending' | 'applying' | 'deployed' | 'failed';
+/**
+ * Deployment lifecycle status
+ */
+export type DeploymentStatus = 'pending' | 'applying' | 'deployed' | 'failed';
+/**
+ * Change set with deployment ordering
+ */
+export interface ChangeSet {
+    creates: InstanceNode[];
+    updates: InstanceNode[];
+    deletes: InstanceNode[];
+    deploymentOrder: string[];
+    parallelBatches: string[][];
+}
+/**
+ * Serializable node state for persistence
+ */
+export interface SerializedNode {
+    id: string;
+    path: string[];
+    constructType: string;
+    props: Record<string, any>;
+    outputs?: Record<string, any>;
+    state?: ResourceState;
+    store?: any;
+}
+/**
+ * Deployment state - persisted by backend
+ */
+export interface DeploymentState {
+    nodes: SerializedNode[];
+    status: DeploymentStatus;
+    applyingNodeId?: string;
+    stackName: string;
+    lastDeployedAt: number;
+    user?: string;
+    storeValues?: Record<string, any>;
+}
+/**
+ * Audit log entry for tracking deployment history
+ */
+export interface AuditLogEntry {
+    timestamp: number;
+    action: 'deploy_start' | 'deploy_complete' | 'deploy_failed' | 'resource_applied' | 'resource_destroyed';
+    nodeId?: string;
+    details?: Record<string, any>;
+    user?: string;
+}
+/**
+ * Backend interface - implement this to persist deployment state
+ *
+ * Example implementations:
+ * - InMemoryBackend: For testing
+ * - FileBackend: Local JSON file
+ * - DynamoDBBackend: AWS DynamoDB
+ * - S3Backend: AWS S3
+ * - PostgresBackend: Database
+ */
+export interface Backend {
+    /**
+     * Get current deployment state for a stack
+     */
+    getState(stackName: string): Promise<DeploymentState | null>;
+    /**
+     * Save deployment state
+     */
+    saveState(stackName: string, state: DeploymentState): Promise<void>;
+    /**
+     * Optional: Acquire lock for concurrent deploy protection
+     * @param stackName - Stack to lock
+     * @param holder - Identity of lock holder (e.g., deployment ID)
+     * @param ttlSeconds - Lock TTL in seconds
+     * @returns true if lock acquired, false if already locked
+     */
+    acquireLock?(stackName: string, holder: string, ttlSeconds: number): Promise<boolean>;
+    /**
+     * Optional: Release deployment lock
+     */
+    releaseLock?(stackName: string): Promise<void>;
+    /**
+     * Optional: Append to audit trail
+     */
+    appendAuditLog?(stackName: string, entry: AuditLogEntry): Promise<void>;
+    /**
+     * Optional: Get audit log entries
+     */
+    getAuditLog?(stackName: string, limit?: number): Promise<AuditLogEntry[]>;
+}
+/**
+ * Serialize an InstanceNode for persistence
+ */
+export declare function serializeNode(node: InstanceNode): SerializedNode;
+/**
+ * Serialize multiple nodes
+ */
+export declare function serializeNodes(nodes: InstanceNode[]): SerializedNode[];

package/dist/provider/backend.js

@@ -0,0 +1,37 @@
+/**
+ * Backend interface - abstracts state persistence
+ *
+ * The Backend enables:
+ * - Resume from crash (nodes with outputs are treated as deployed)
+ * - Incremental deploys (only changed resources)
+ * - State hydration (createStore values restored)
+ * - Drift detection (compare expected vs actual)
+ */
+/**
+ * Serialize an InstanceNode for persistence
+ */
+export function serializeNode(node) {
+    // Extract current output values from signals
+    // biome-ignore lint/suspicious/noExplicitAny: outputs are provider-returned with arbitrary types
+    const outputs = {};
+    for (const [key, [read]] of node.outputSignals) {
+        const value = read();
+        if (value !== undefined) {
+            outputs[key] = value;
+        }
+    }
+    return {
+        id: node.id,
+        path: node.path,
+        constructType: node.constructType,
+        props: node.props,
+        outputs: Object.keys(outputs).length > 0 ? outputs : undefined,
+        store: node.store,
+    };
+}
+/**
+ * Serialize multiple nodes
+ */
+export function serializeNodes(nodes) {
+    return nodes.map(serializeNode);
+}

package/dist/provider/interface.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Provider interface - abstracts the execution environment
+ */
+import type { InstanceNode } from '../primitives/instance';
+/**
+ * Event emitted when provider detects output changes
+ */
+export interface OutputChangeEvent {
+    resourceName: string;
+    outputs: Record<string, any>;
+    timestamp: number;
+}
+/**
+ * Provider interface - implement this to connect to any backend
+ */
+export interface Provider {
+    /** Initialize provider (async setup) */
+    initialize?(): Promise<void>;
+    /**
+     * Materialize nodes into cloud resources.
+     *
+     * Providers should call node.setOutputs() when outputs are available.
+     * This triggers reactive updates - dependent components re-render automatically.
+     *
+     * For sync providers: call node.setOutputs() immediately
+     * For async providers: call node.setOutputs() in the async callback
+     *
+     * Returns a Promise that resolves when all resources are materialized.
+     */
+    materialize(nodes: InstanceNode[]): Promise<void>;
+    /** Destroy a node */
+    destroy(node: InstanceNode): Promise<void>;
+    /** Lifecycle hooks */
+    preDeploy?(nodes: InstanceNode[]): Promise<void>;
+    postDeploy?(nodes: InstanceNode[], outputs: Record<string, any>): Promise<void>;
+    onError?(error: Error, nodes: InstanceNode[]): Promise<void>;
+    /** Event system (required for continuous runtime) */
+    on(event: 'outputsChanged', handler: (change: OutputChangeEvent) => void): void;
+    off(event: 'outputsChanged', handler: (change: OutputChangeEvent) => void): void;
+    stop(): void;
+}
+/**
+ * Create a mock provider for testing
+ */
+export declare function createMockProvider(handlers?: Partial<{
+    materialize: (nodes: InstanceNode[]) => Promise<void> | void;
+    destroy: (node: InstanceNode) => Promise<void> | void;
+}>): Provider;

package/dist/provider/interface.js

@@ -0,0 +1,39 @@
+/**
+ * Provider interface - abstracts the execution environment
+ */
+/**
+ * Create a mock provider for testing
+ */
+export function createMockProvider(handlers = {}) {
+    const eventHandlers = new Map();
+    return {
+        async materialize(nodes) {
+            if (handlers.materialize) {
+                await handlers.materialize(nodes);
+            }
+            else {
+                // Default: set empty outputs via reactive API
+                for (const node of nodes) {
+                    node.setOutputs({});
+                }
+            }
+        },
+        async destroy(node) {
+            if (handlers.destroy) {
+                await handlers.destroy(node);
+            }
+        },
+        on(event, handler) {
+            if (!eventHandlers.has(event)) {
+                eventHandlers.set(event, new Set());
+            }
+            eventHandlers.get(event)?.add(handler);
+        },
+        off(event, handler) {
+            eventHandlers.get(event)?.delete(handler);
+        },
+        stop() {
+            eventHandlers.clear();
+        },
+    };
+}

package/dist/reactive/effect.d.ts

@@ -0,0 +1,11 @@
+/**
+ * createEffect - run side effects when dependencies change
+ */
+/**
+ * Create a reactive effect that runs when dependencies change
+ */
+export declare function createEffect(fn: () => undefined | (() => void)): void;
+/**
+ * Register a cleanup function for the current computation
+ */
+export declare function onCleanup(fn: () => void): void;

package/dist/reactive/effect.js

@@ -0,0 +1,42 @@
+/**
+ * createEffect - run side effects when dependencies change
+ */
+import { getListener, runComputation } from './tracking';
+/**
+ * Create a reactive effect that runs when dependencies change
+ */
+export function createEffect(fn) {
+    const computation = {
+        fn: () => {
+            const cleanup = fn();
+            if (typeof cleanup === 'function') {
+                if (!computation.cleanups) {
+                    computation.cleanups = [cleanup];
+                }
+                else {
+                    computation.cleanups.push(cleanup);
+                }
+            }
+        },
+        sources: null,
+        sourceSlots: null,
+        state: 1, // STALE - needs initial run
+        cleanups: null,
+    };
+    // Run immediately
+    runComputation(computation);
+}
+/**
+ * Register a cleanup function for the current computation
+ */
+export function onCleanup(fn) {
+    const listener = getListener();
+    if (listener) {
+        if (!listener.cleanups) {
+            listener.cleanups = [fn];
+        }
+        else {
+            listener.cleanups.push(fn);
+        }
+    }
+}

package/dist/reactive/index.d.ts

@@ -0,0 +1,3 @@
+export { createEffect, onCleanup } from './effect';
+export { type Accessor, type Computation, createSignal, type Setter, type Signal } from './signal';
+export { batch, cleanComputation, flushSync, getListener, runComputation, scheduleComputation, setListener, untrack, } from './tracking';

package/dist/reactive/index.js

@@ -0,0 +1,3 @@
+export { createEffect, onCleanup } from './effect';
+export { createSignal } from './signal';
+export { batch, cleanComputation, flushSync, getListener, runComputation, scheduleComputation, setListener, untrack, } from './tracking';

package/dist/reactive/signal.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Signal - core reactive primitive (internal)
+ * Inspired by SolidJS createSignal
+ */
+/**
+ * Signal state - holds value and tracks observers
+ */
+export interface Signal<T> {
+    value: T | undefined;
+    observers: Computation<any>[] | null;
+    observerSlots: number[] | null;
+}
+/**
+ * Computation - tracks dependencies and re-runs when they change
+ */
+export interface Computation<T> {
+    fn: () => T;
+    sources: Signal<any>[] | null;
+    sourceSlots: number[] | null;
+    state: 0 | 1 | 2;
+    cleanups: (() => void)[] | null;
+}
+export type Accessor<T> = () => T | undefined;
+export type Setter<T> = (value: T) => void;
+/**
+ * Create a reactive signal (internal - not exported from package)
+ */
+export declare function createSignal<T>(initial?: T): [Accessor<T>, Setter<T>];
+/**
+ * Get raw signal value without tracking
+ */
+export declare function peekSignal<T>(signal: Signal<T>): T | undefined;