dalila 1.4.2 → 1.4.4

package/dist/core/scheduler.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Low-level scheduler (runtime core).
+ *
+ * This module is intentionally independent from signals/effects to avoid circular
+ * dependencies and to keep the runtime easy to reason about.
+ *
+ * What it provides:
+ * - A RAF queue (`schedule`) for work that should be grouped per frame (DOM writes, batching flush)
+ * - A microtask queue (`scheduleMicrotask`) for reactive follow-ups and short jobs
+ * - A batching mechanism (`batch` + `queueInBatch`) to coalesce many notifications into one frame
+ * - Optional DOM discipline helpers (`measure`/`mutate`) to document read/write intent
+ *
+ * Invariants:
+ * - Tasks are executed in FIFO order within each queue.
+ * - Microtasks are drained fully (up to a hard iteration limit) before returning control.
+ * - RAF tasks are drained fully (up to a hard iteration limit) per frame.
+ *
+ * Safety:
+ * - Iteration caps prevent infinite loops from growing queues unbounded.
+ * - Flushes always drain with `splice(0)` to release references eagerly.
+ */
+type Task = () => void;
+/**
+ * Scheduler configuration.
+ */
+interface SchedulerConfig {
+    /**
+     * Maximum microtask iterations before stopping (prevents infinite loops).
+     * A high value is intentional: reactive systems may legitimately schedule
+     * multiple microtask waves. Default: 1000.
+     */
+    maxMicrotaskIterations: number;
+    /**
+     * Maximum RAF iterations before stopping (prevents infinite loops).
+     * RAF work is typically heavier (DOM), so keep it lower. Default: 100.
+     */
+    maxRafIterations: number;
+}
+/**
+ * Configure scheduler limits.
+ *
+ * Call this early in your app initialization if you need different limits.
+ *
+ * Example:
+ * ```ts
+ * configureScheduler({ maxMicrotaskIterations: 2000 });
+ * ```
+ */
+export declare function configureScheduler(config: Partial<SchedulerConfig>): void;
+/**
+ * Get the current scheduler configuration.
+ */
+export declare function getSchedulerConfig(): Readonly<SchedulerConfig>;
+/**
+ * Schedule work for the next animation frame.
+ *
+ * Use this for DOM-affecting work you want grouped per frame.
+ * (In Node tests, `requestAnimationFrame` is typically mocked.)
+ */
+export declare function schedule(task: Task): void;
+/**
+ * Schedule work in a microtask.
+ *
+ * Use this for reactive re-runs and short jobs where you want to:
+ * - run after the current call stack,
+ * - but before the next frame.
+ */
+export declare function scheduleMicrotask(task: Task): void;
+/**
+ * Returns true while inside a `batch()` call.
+ *
+ * Reactive primitives can use this to:
+ * - update state immediately,
+ * - but defer notification fan-out until the batch finishes.
+ */
+export declare function isBatching(): boolean;
+/**
+ * Enqueue work to run at the end of the *outermost* batch.
+ *
+ * Deduplication:
+ * - The same Task identity will run at most once per batch flush.
+ * - This is critical for effects/notifications: many signals can enqueue the same work.
+ */
+export declare function queueInBatch(task: Task): void;
+/**
+ * Batch multiple updates so their resulting notifications are grouped.
+ *
+ * Contract:
+ * - State updates inside the batch happen immediately.
+ * - Notifications/effects are deferred until the batch completes.
+ * - Nested batches are supported: only the outermost batch triggers a flush.
+ *
+ * Flush strategy:
+ * - We flush batched tasks in *one RAF* to group visible DOM work per frame.
+ */
+export declare function batch(fn: () => void): void;
+/**
+ * DOM read discipline helper.
+ *
+ * Currently a no-op wrapper. Its purpose is to make intent explicit:
+ * put layout reads inside `measure()` so future tooling/optimizations can hook in.
+ */
+export declare function measure<T>(fn: () => T): T;
+/**
+ * DOM write discipline helper.
+ *
+ * Writes are scheduled in a microtask so they don't interleave with synchronous reads.
+ * If you want stricter "writes only on RAF", you can swap this to `schedule(fn)`.
+ */
+export declare function mutate(fn: () => void): void;
+export {};

package/dist/core/scheduler.js

@@ -0,0 +1,243 @@
+/**
+ * Low-level scheduler (runtime core).
+ *
+ * This module is intentionally independent from signals/effects to avoid circular
+ * dependencies and to keep the runtime easy to reason about.
+ *
+ * What it provides:
+ * - A RAF queue (`schedule`) for work that should be grouped per frame (DOM writes, batching flush)
+ * - A microtask queue (`scheduleMicrotask`) for reactive follow-ups and short jobs
+ * - A batching mechanism (`batch` + `queueInBatch`) to coalesce many notifications into one frame
+ * - Optional DOM discipline helpers (`measure`/`mutate`) to document read/write intent
+ *
+ * Invariants:
+ * - Tasks are executed in FIFO order within each queue.
+ * - Microtasks are drained fully (up to a hard iteration limit) before returning control.
+ * - RAF tasks are drained fully (up to a hard iteration limit) per frame.
+ *
+ * Safety:
+ * - Iteration caps prevent infinite loops from growing queues unbounded.
+ * - Flushes always drain with `splice(0)` to release references eagerly.
+ */
+const schedulerConfig = {
+    maxMicrotaskIterations: 1000,
+    maxRafIterations: 100,
+};
+/**
+ * Configure scheduler limits.
+ *
+ * Call this early in your app initialization if you need different limits.
+ *
+ * Example:
+ * ```ts
+ * configureScheduler({ maxMicrotaskIterations: 2000 });
+ * ```
+ */
+export function configureScheduler(config) {
+    Object.assign(schedulerConfig, config);
+}
+/**
+ * Get the current scheduler configuration.
+ */
+export function getSchedulerConfig() {
+    return { ...schedulerConfig };
+}
+let rafScheduled = false;
+let microtaskScheduled = false;
+let isFlushingRaf = false;
+let isFlushingMicrotasks = false;
+/** FIFO queues. */
+const rafQueue = [];
+const microtaskQueue = [];
+const rafImpl = typeof globalThis !== 'undefined' && typeof globalThis.requestAnimationFrame === 'function'
+    ? (cb) => globalThis.requestAnimationFrame(() => cb())
+    : (cb) => setTimeout(cb, 0);
+/**
+ * Batching state.
+ *
+ * During `batch()`, producers enqueue "notifications" via `queueInBatch()`.
+ * When the outermost batch exits, we flush all queued tasks in a single RAF.
+ */
+let batchDepth = 0;
+/** Batched tasks (FIFO) + identity dedupe set. */
+const batchQueue = [];
+const batchQueueSet = new Set();
+/**
+ * Schedule work for the next animation frame.
+ *
+ * Use this for DOM-affecting work you want grouped per frame.
+ * (In Node tests, `requestAnimationFrame` is typically mocked.)
+ */
+export function schedule(task) {
+    rafQueue.push(task);
+    if (!rafScheduled) {
+        rafScheduled = true;
+        rafImpl(flushRaf);
+    }
+}
+/**
+ * Schedule work in a microtask.
+ *
+ * Use this for reactive re-runs and short jobs where you want to:
+ * - run after the current call stack,
+ * - but before the next frame.
+ */
+export function scheduleMicrotask(task) {
+    microtaskQueue.push(task);
+    if (!microtaskScheduled) {
+        microtaskScheduled = true;
+        Promise.resolve().then(flushMicrotasks);
+    }
+}
+/**
+ * Returns true while inside a `batch()` call.
+ *
+ * Reactive primitives can use this to:
+ * - update state immediately,
+ * - but defer notification fan-out until the batch finishes.
+ */
+export function isBatching() {
+    return batchDepth > 0;
+}
+/**
+ * Enqueue work to run at the end of the *outermost* batch.
+ *
+ * Deduplication:
+ * - The same Task identity will run at most once per batch flush.
+ * - This is critical for effects/notifications: many signals can enqueue the same work.
+ */
+export function queueInBatch(task) {
+    if (batchQueueSet.has(task))
+        return;
+    batchQueue.push(task);
+    batchQueueSet.add(task);
+}
+/**
+ * Batch multiple updates so their resulting notifications are grouped.
+ *
+ * Contract:
+ * - State updates inside the batch happen immediately.
+ * - Notifications/effects are deferred until the batch completes.
+ * - Nested batches are supported: only the outermost batch triggers a flush.
+ *
+ * Flush strategy:
+ * - We flush batched tasks in *one RAF* to group visible DOM work per frame.
+ */
+export function batch(fn) {
+    batchDepth++;
+    try {
+        fn();
+    }
+    finally {
+        batchDepth--;
+        if (batchDepth === 0)
+            flushBatch();
+    }
+}
+/**
+ * Flush batched tasks by scheduling a single RAF job.
+ *
+ * This keeps "batch outputs" aligned to frames:
+ * multiple signal sets -> one notification wave -> one render frame.
+ */
+function flushBatch() {
+    if (batchQueue.length === 0)
+        return;
+    const tasks = batchQueue.splice(0);
+    batchQueueSet.clear();
+    schedule(() => {
+        for (const t of tasks)
+            t();
+    });
+}
+/**
+ * Drain the microtask queue.
+ *
+ * Implementation notes:
+ * - Uses `splice(0)` to drop references eagerly.
+ * - Runs until the queue is empty, but caps the number of drain waves.
+ *   (A single task can enqueue more microtasks; that still counts as another iteration.)
+ */
+function flushMicrotasks() {
+    if (isFlushingMicrotasks)
+        return;
+    isFlushingMicrotasks = true;
+    let iterations = 0;
+    const maxIterations = schedulerConfig.maxMicrotaskIterations;
+    try {
+        while (microtaskQueue.length > 0 && iterations < maxIterations) {
+            iterations++;
+            const tasks = microtaskQueue.splice(0);
+            for (const t of tasks)
+                t();
+        }
+        if (iterations >= maxIterations && microtaskQueue.length > 0) {
+            console.error(`[Dalila] Scheduler exceeded ${maxIterations} microtask iterations. ` +
+                `Possible infinite loop detected. Remaining ${microtaskQueue.length} tasks discarded.`);
+            microtaskQueue.length = 0;
+        }
+    }
+    finally {
+        isFlushingMicrotasks = false;
+        microtaskScheduled = false;
+        // If tasks were queued after we stopped flushing, reschedule a new microtask turn.
+        if (microtaskQueue.length > 0 && !microtaskScheduled) {
+            microtaskScheduled = true;
+            Promise.resolve().then(flushMicrotasks);
+        }
+    }
+}
+/**
+ * Drain the RAF queue.
+ *
+ * Implementation notes:
+ * - RAF work is typically heavier (DOM), so we cap iterations more aggressively.
+ * - Like microtasks, a task may enqueue more RAF tasks; that triggers another flush cycle.
+ */
+function flushRaf() {
+    if (isFlushingRaf)
+        return;
+    isFlushingRaf = true;
+    let iterations = 0;
+    const maxIterations = schedulerConfig.maxRafIterations;
+    try {
+        while (rafQueue.length > 0 && iterations < maxIterations) {
+            iterations++;
+            const tasks = rafQueue.splice(0);
+            for (const t of tasks)
+                t();
+        }
+        if (iterations >= maxIterations && rafQueue.length > 0) {
+            console.error(`[Dalila] Scheduler exceeded ${maxIterations} RAF iterations. ` +
+                `Possible infinite loop detected. Remaining ${rafQueue.length} tasks discarded.`);
+            rafQueue.length = 0;
+        }
+    }
+    finally {
+        isFlushingRaf = false;
+        rafScheduled = false;
+        // If tasks were queued during the flush, schedule another frame.
+        if (rafQueue.length > 0 && !rafScheduled) {
+            rafScheduled = true;
+            rafImpl(flushRaf);
+        }
+    }
+}
+/**
+ * DOM read discipline helper.
+ *
+ * Currently a no-op wrapper. Its purpose is to make intent explicit:
+ * put layout reads inside `measure()` so future tooling/optimizations can hook in.
+ */
+export function measure(fn) {
+    return fn();
+}
+/**
+ * DOM write discipline helper.
+ *
+ * Writes are scheduled in a microtask so they don't interleave with synchronous reads.
+ * If you want stricter "writes only on RAF", you can swap this to `schedule(fn)`.
+ */
+export function mutate(fn) {
+    scheduleMicrotask(fn);
+}

package/dist/core/scope.d.ts

@@ -0,0 +1,74 @@
+/**
+ * A Scope is a simple lifecycle container.
+ * Anything registered via `onCleanup` will run when `dispose()` is called.
+ *
+ * This is the foundation for "automatic cleanup" in Dalila:
+ * - effects can be disposed when a view/controller scope ends
+ * - event listeners / timers / abort controllers can be tied to scope lifetime
+ */
+export interface Scope {
+    /** Register a cleanup callback to run when the scope is disposed. */
+    onCleanup(fn: () => void): void;
+    /** Dispose the scope and run all registered cleanups. */
+    dispose(): void;
+    /** Parent scope in the hierarchy (for context lookup). */
+    readonly parent: Scope | null;
+}
+/**
+ * Subscribe to scope creation events.
+ * Returns an unsubscribe function.
+ */
+export declare function onScopeCreate(fn: (scope: Scope) => void): () => void;
+/**
+ * Subscribe to scope disposal events.
+ * Returns an unsubscribe function.
+ */
+export declare function onScopeDispose(fn: (scope: Scope) => void): () => void;
+/** Returns true if the given scope has been disposed. */
+export declare function isScopeDisposed(scope: Scope): boolean;
+/**
+ * Creates a new Scope instance.
+ *
+ * Notes:
+ * - Cleanups run in FIFO order (registration order).
+ * - If a cleanup registers another cleanup during disposal, it will NOT run
+ *   in the same dispose pass (because we snapshot via `splice(0)`).
+ * - Parent is captured from the current scope context (set by withScope).
+ */
+export declare function createScope(parentOverride?: Scope | null): Scope;
+/** Returns the current active scope (or null if none). */
+export declare function getCurrentScope(): Scope | null;
+/**
+ * Returns the current scope hierarchy, from current scope up to the root.
+ */
+export declare function getCurrentScopeHierarchy(): Scope[];
+/**
+ * Sets the current active scope.
+ * Prefer using `withScope()` unless you are implementing low-level internals.
+ */
+export declare function setCurrentScope(scope: Scope | null): void;
+/**
+ * Runs a function with the given scope set as current, then restores the previous scope.
+ *
+ * This enables scope-aware primitives:
+ * - `signal()` can register cleanup in the current scope
+ * - `effect()` can auto-dispose when the scope ends
+ */
+export declare function withScope<T>(scope: Scope, fn: () => T): T;
+/**
+ * Async version of withScope that properly maintains scope during await.
+ *
+ * IMPORTANT: Use this instead of withScope when fn is async, because
+ * withScope() restores the previous scope immediately when the Promise
+ * is returned, not when it resolves. This means anything created after
+ * an await would not be in the scope.
+ *
+ * Example:
+ * ```ts
+ * await withScopeAsync(scope, async () => {
+ *   await fetch(...);
+ *   const sig = signal(0);  // ← This will be in scope
+ * });
+ * ```
+ */
+export declare function withScopeAsync<T>(scope: Scope, fn: () => Promise<T>): Promise<T>;

package/dist/core/scope.js

@@ -0,0 +1,171 @@
+/** Tracks disposed scopes without mutating the public interface. */
+const disposedScopes = new WeakSet();
+const scopeCreateListeners = new Set();
+const scopeDisposeListeners = new Set();
+/**
+ * Subscribe to scope creation events.
+ * Returns an unsubscribe function.
+ */
+export function onScopeCreate(fn) {
+    scopeCreateListeners.add(fn);
+    return () => scopeCreateListeners.delete(fn);
+}
+/**
+ * Subscribe to scope disposal events.
+ * Returns an unsubscribe function.
+ */
+export function onScopeDispose(fn) {
+    scopeDisposeListeners.add(fn);
+    return () => scopeDisposeListeners.delete(fn);
+}
+/** Returns true if the given scope has been disposed. */
+export function isScopeDisposed(scope) {
+    return disposedScopes.has(scope);
+}
+/**
+ * Creates a new Scope instance.
+ *
+ * Notes:
+ * - Cleanups run in FIFO order (registration order).
+ * - If a cleanup registers another cleanup during disposal, it will NOT run
+ *   in the same dispose pass (because we snapshot via `splice(0)`).
+ * - Parent is captured from the current scope context (set by withScope).
+ */
+export function createScope(parentOverride) {
+    const cleanups = [];
+    const parent = parentOverride === undefined ? currentScope : parentOverride === null ? null : parentOverride;
+    const runCleanupSafely = (fn) => {
+        try {
+            fn();
+            return undefined;
+        }
+        catch (err) {
+            return err;
+        }
+    };
+    const scope = {
+        onCleanup(fn) {
+            if (isScopeDisposed(scope)) {
+                const error = runCleanupSafely(fn);
+                if (error) {
+                    console.error('[Dalila] cleanup registered after dispose() threw:', error);
+                }
+                return;
+            }
+            cleanups.push(fn);
+        },
+        dispose() {
+            if (isScopeDisposed(scope))
+                return;
+            disposedScopes.add(scope);
+            const snapshot = cleanups.splice(0);
+            const errors = [];
+            for (const fn of snapshot) {
+                const error = runCleanupSafely(fn);
+                if (error)
+                    errors.push(error);
+            }
+            if (errors.length > 0) {
+                console.error('[Dalila] scope.dispose() had cleanup errors:', errors);
+            }
+            for (const listener of scopeDisposeListeners) {
+                try {
+                    listener(scope);
+                }
+                catch (err) {
+                    console.error('[Dalila] scope.dispose() listener threw:', err);
+                }
+            }
+        },
+        parent,
+    };
+    if (parent) {
+        parent.onCleanup(() => scope.dispose());
+    }
+    for (const listener of scopeCreateListeners) {
+        try {
+            listener(scope);
+        }
+        catch (err) {
+            console.error('[Dalila] scope.create() listener threw:', err);
+        }
+    }
+    return scope;
+}
+/**
+ * The currently active scope for the running code path.
+ * This is set by `withScope()` and read by reactive primitives.
+ */
+let currentScope = null;
+/** Returns the current active scope (or null if none). */
+export function getCurrentScope() {
+    return currentScope;
+}
+/**
+ * Returns the current scope hierarchy, from current scope up to the root.
+ */
+export function getCurrentScopeHierarchy() {
+    const scopes = [];
+    let current = currentScope;
+    while (current) {
+        scopes.push(current);
+        current = current.parent;
+    }
+    return scopes;
+}
+/**
+ * Sets the current active scope.
+ * Prefer using `withScope()` unless you are implementing low-level internals.
+ */
+export function setCurrentScope(scope) {
+    currentScope = scope;
+}
+/**
+ * Runs a function with the given scope set as current, then restores the previous scope.
+ *
+ * This enables scope-aware primitives:
+ * - `signal()` can register cleanup in the current scope
+ * - `effect()` can auto-dispose when the scope ends
+ */
+export function withScope(scope, fn) {
+    if (isScopeDisposed(scope)) {
+        throw new Error('[Dalila] withScope() cannot enter a disposed scope.');
+    }
+    const prevScope = currentScope;
+    currentScope = scope;
+    try {
+        return fn();
+    }
+    finally {
+        currentScope = prevScope;
+    }
+}
+/**
+ * Async version of withScope that properly maintains scope during await.
+ *
+ * IMPORTANT: Use this instead of withScope when fn is async, because
+ * withScope() restores the previous scope immediately when the Promise
+ * is returned, not when it resolves. This means anything created after
+ * an await would not be in the scope.
+ *
+ * Example:
+ * ```ts
+ * await withScopeAsync(scope, async () => {
+ *   await fetch(...);
+ *   const sig = signal(0);  // ← This will be in scope
+ * });
+ * ```
+ */
+export async function withScopeAsync(scope, fn) {
+    if (isScopeDisposed(scope)) {
+        throw new Error('[Dalila] withScopeAsync() cannot enter a disposed scope.');
+    }
+    const prevScope = currentScope;
+    currentScope = scope;
+    try {
+        return await fn();
+    }
+    finally {
+        currentScope = prevScope;
+    }
+}

package/dist/core/signal.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Register a global error handler for effects/computed invalidations.
+ *
+ * Use this to report errors without crashing the reactive graph.
+ */
+export declare function setEffectErrorHandler(handler: (error: Error, source: string) => void): void;
+export interface Signal<T> {
+    /** Read the current value (with dependency tracking if inside an effect). */
+    (): T;
+    /** Set a new value and notify subscribers. */
+    set(value: T): void;
+    /** Update the value using a function. */
+    update(fn: (v: T) => T): void;
+    /** Read the current value without creating a dependency (no tracking). */
+    peek(): T;
+    /** Subscribe to value changes manually (outside of effects). Returns unsubscribe function. */
+    on(callback: (value: T) => void): () => void;
+}
+/**
+ * Create a signal: a mutable value with automatic dependency tracking.
+ *
+ * Reads:
+ * - if there is an active effect, subscribe it (dynamic deps supported)
+ *
+ * Writes:
+ * - update the value immediately
+ * - notify subscribers (immediately, or deferred via batch queue)
+ *
+ * Lifecycle:
+ * - effects remove themselves from subscriber sets on re-run and on dispose
+ * - signals do not "own" subscriber lifetimes; they only maintain the set
+ */
+export declare function signal<T>(initialValue: T): Signal<T>;
+/**
+ * Create an effect: reruns `fn` whenever any tracked signal changes.
+ *
+ * Scheduling:
+ * - the initial run is scheduled (microtask) to coalesce multiple writes
+ *
+ * Dependency tracking:
+ * - before each run, the effect unsubscribes from previous dependencies
+ * - during the run, reads resubscribe to the new dependencies (dynamic deps)
+ *
+ * Scope:
+ * - if created inside a scope, the effect runs inside that scope
+ * - the effect is disposed automatically when the scope disposes
+ */
+export declare function effect(fn: () => void): () => void;
+/**
+ * Create a computed signal (derived, cached, read-only).
+ *
+ * Semantics:
+ * - lazy: computes on first read
+ * - cached: returns the cached value until invalidated
+ * - synchronous invalidation: dependencies mark it dirty immediately
+ *
+ * Dependency tracking:
+ * - while computing, we collect dependencies into an internal "markDirty" effect
+ * - those dependencies will synchronously mark this computed as dirty on change
+ *
+ * Subscription:
+ * - other effects can subscribe to the computed like a normal signal
+ */
+export declare function computed<T>(fn: () => T): Signal<T>;
+/**
+ * Async effect with cancellation.
+ *
+ * Semantics:
+ * - provides an AbortSignal to the callback
+ * - on re-run, aborts the previous run before starting the next
+ * - when disposed, aborts the current run and stops future scheduling
+ */
+export declare function effectAsync(fn: (signal: AbortSignal) => void): () => void;
+/**
+ * Run a function without tracking any signal reads as dependencies.
+ *
+ * Use this inside an effect when you want to read a signal's value
+ * without creating a dependency on it.
+ *
+ * Example:
+ * ```ts
+ * effect(() => {
+ *   const tracked = count();        // This read is tracked
+ *   const untracked = untrack(() => other()); // This read is NOT tracked
+ * });
+ * ```
+ */
+export declare function untrack<T>(fn: () => T): T;