@but212/atom-effect 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -205,6 +205,7 @@ export declare interface DebugConfig {
 export declare interface Dependency {
     readonly id: DependencyId;
     version: number;
+    flags: number;
     /**
      * Last epoch seen by this dependency (used for invalidation)
      */
@@ -362,7 +363,6 @@ export declare function isEffect(obj: unknown): obj is EffectObject;
 
 /**
  * Interface for nodes that support phase-shift priority calculation.
- * Used by Scheduler to determine job urgency.
  */
 declare interface PhaseShiftNode {
     getShift(cachedVersion: number): number;
@@ -419,28 +419,13 @@ export declare interface ReadonlyAtom<T = unknown> {
 }
 
 /**
- * Scheduler for reactive updates with phase-shift priority scheduling.
- *
- * Features:
- * - Double-buffered queue for efficient processing
- * - Urgent queue for high-priority updates (glitch reduction)
- * - Branchless priority calculation using phase-shift
- * - Batching support for transactional updates
- *
- * Priority Logic:
- * When a job's phase shift exceeds PHASE_THRESHOLD (90° equivalent),
- * it's considered "urgent" and processed before normal jobs.
- * This reduces glitches by prioritizing stale updates.
+ * Scheduler for reactive updates with double-buffered priority queues.
  */
 declare class Scheduler {
-    private queueA;
-    private queueB;
-    private queue;
-    private queueSize;
-    private urgentQueueA;
-    private urgentQueueB;
-    private urgentQueue;
-    private urgentQueueSize;
+    private _queueBuffers;
+    private _bufferIndices;
+    private _sizes;
+    private _activeQueues;
     private _epoch;
     private isProcessing;
     isBatching: boolean;
@@ -449,66 +434,51 @@ declare class Scheduler {
     private batchQueueSize;
     private isFlushingSync;
     private maxFlushIterations;
+    constructor();
+    /**
+     * Returns the current operational phase of the scheduler.
+     */
     get phase(): SchedulerPhase;
+    /** Current number of pending normal jobs. */
+    get queueSize(): number;
+    /** Current number of pending urgent jobs. */
+    get urgentQueueSize(): number;
     /**
      * Schedules a task for execution with optional priority based on phase shift.
-     *
-     * Priority Calculation (Branchless):
-     * - If sourceNode and cachedVersion are provided, calculates shift
-     * - Jobs with shift >= PHASE_THRESHOLD go to urgentQueue
-     * - Uses branchless bit manipulation: ((shift - THRESHOLD) >>> 31) ^ 1
-     *
-     * @param callback - The function to execute
-     * @param sourceNode - Optional reactive node for shift calculation
-     * @throws {SchedulerError} If the callback is not a function
      */
     schedule(callback: SchedulerJob, sourceNode?: PhaseShiftNode): void;
     /**
      * Calculates urgency flag using branchless bit manipulation.
      *
-     * Formula: ((shift - PHASE_THRESHOLD) >>> 31) ^ 1
-     * - If shift >= THRESHOLD: (negative >>> 31) = 0, XOR 1 = 1 (urgent)
-     * - If shift < THRESHOLD: (positive >>> 31) = 0... wait, that's wrong
+     * Logic:
+     * 1. Calculate the 'shift' (rotation distance) from the cached version.
+     * 2. Compare against PHASE_THRESHOLD (180° rotation equivalent).
+     * 3. Use (N >>> 31) to extract the sign bit in O(1) time.
      *
-     * Correct formula: (shift >= THRESHOLD) ? 1 : 0
-     * Branchless: ((PHASE_THRESHOLD - 1 - shift) >>> 31)
-     *
-     * @returns 1 if urgent, 0 if normal
+     * @returns 1 if urgent (shift >= PHASE_THRESHOLD), 0 otherwise.
      */
     private _calculateUrgency;
+    /**
+     * Schedules a microtask-based flush of the queues.
+     * Coalesces multiple schedule calls into a single microtask execution.
+     */
     private flush;
-    private flushSync;
-    private _mergeBatchQueue;
     /**
-     * Drains all queues, processing urgent queue completely first.
-     *
-     * Processing Order:
-     * 1. Process all urgent jobs (high phase shift = stale updates)
-     * 2. Process normal jobs
-     * 3. Repeat until both queues are empty
-     *
-     * This ordering reduces glitches by ensuring that the most
-     * impactful state changes are propagated first.
+     * Immediately flushes all queues synchronously.
+     * Used at the end of a batch block or when immediate reflection is required.
      */
-    private _drainQueue;
+    private flushSync;
     /**
-     * Processes the urgent queue using double-buffering.
+     * Merges jobs from the batching queue into the primary normal queue.
+     * Increments the epoch/uses provided epoch to ensure deduplication.
      */
-    private _processUrgentQueue;
-    private _processCurrentQueue;
+    private _mergeBatchQueue;
+    private _drainQueue;
+    private _processQueue;
     private _handleFlushOverflow;
     private _processJobs;
-    /** Starts a new batch of updates. Updates will be deferred until endBatch is called. */
     startBatch(): void;
-    /**
-     * Ends the current batch. If the batch depth reaches zero, all pending updates are flushed synchronously.
-     */
     endBatch(): void;
-    /**
-     * Configures the maximum number of iterations allowed during a synchronous flush.
-     * Used to prevent infinite loops.
-     * @param max - Maximum iterations count.
-     */
     setMaxFlushIterations(max: number): void;
 }
 
@@ -537,6 +507,8 @@ export declare const SCHEDULER_CONFIG: {
     readonly MAX_FLUSH_ITERATIONS: 1000;
     /** Minimum allowed value for max flush iterations */
     readonly MIN_FLUSH_ITERATIONS: 10;
+    /** Threshold for shrinking the batch queue to assist GC */
+    readonly BATCH_QUEUE_SHRINK_THRESHOLD: 1000;
 };
 
 /**
@@ -556,7 +528,6 @@ export declare class SchedulerError extends AtomError {
 
 /**
  * Scheduler job interface with phase-shift tracking support.
- * _cachedVersion enables priority calculation based on staleness.
  */
 declare interface SchedulerJob {
     (): void;
@@ -566,9 +537,15 @@ declare interface SchedulerJob {
     _cachedVersion?: number;
 }
 
+/**
+ * Current state of the scheduler.
+ */
 declare enum SchedulerPhase {
+    /** No pending jobs, not currently flushing. */
     IDLE = 0,
+    /** Currently within a batch() block. */
     BATCHING = 1,
+    /** Currently executing queued jobs. */
     FLUSHING = 2
 }