@but212/atom-effect 0.10.0 → 0.11.0

package/dist/index.d.ts

@@ -14,20 +14,8 @@ export declare type AsyncStateType = (typeof AsyncState)[keyof typeof AsyncState
 /**
  * Creates a reactive atom holding mutable state.
  *
- * Atoms are the building blocks of reactive state. When an atom's value changes,
- * any effects or computed atoms that depend on it will be automatically re-executed.
- *
  * @param initialValue - The initial value of the atom.
- * @param options - Configuration options.
- * @param options.sync - If true, notifications are delivered synchronously when the value changes.
- * @returns A writable atom object.
- *
- * @example
- * ```ts
- * const count = atom(0);
- * count.value = 1; // Notifies subscribers
- * console.log(count.value); // 1
- * ```
+ * @param options - Configuration options (sync: boolean).
  */
 export declare function atom<T>(initialValue: T, options?: AtomOptions): WritableAtom<T>;
 
@@ -224,6 +212,14 @@ export declare interface Dependency {
     /* Excluded from this release type: _tempUnsub */
     /* Excluded from this release type: _modifiedAtEpoch */
     /* Excluded from this release type: _visitedEpoch */
+    /**
+     * Calculates the logical distance (shift) between current and cached version.
+     * Used for priority scheduling - large shifts indicate stale updates.
+     *
+     * @param cachedVersion - The previously cached version
+     * @returns Non-negative shift distance (0 to 0x3fffffff)
+     */
+    getShift(cachedVersion: number): number;
     /**
      * Subscribe to dependency updates
      */
@@ -333,6 +329,14 @@ export declare function isComputed(obj: unknown): obj is ComputedAtom;
 /** Checks if the given object is an EffectObject. */
 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;
+}
+
 /**
  * Object pool configuration
  * Controls memory management and GC pressure reduction
@@ -366,15 +370,28 @@ export declare interface ReadonlyAtom<T = unknown> {
 }
 
 /**
- * Scheduler for reactive updates.
- * Manages the execution of effects and computed updates using batching and double-buffering.
- * Supports both asynchronous (microtask-based) and synchronous (manual or batch-end) flushing.
+ * 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.
  */
 declare class Scheduler {
     private queueA;
     private queueB;
     private queue;
     private queueSize;
+    private urgentQueueA;
+    private urgentQueueB;
+    private urgentQueue;
+    private urgentQueueSize;
     private _epoch;
     private isProcessing;
     isBatching: boolean;
@@ -385,16 +402,50 @@ declare class Scheduler {
     private maxFlushIterations;
     get phase(): SchedulerPhase;
     /**
-     * Schedules a task for execution.
-     * Tasks are deduplicated within the same flush cycle using epoch tracking.
-     * @param callback - The function to execute.
-     * @throws {SchedulerError} If the callback is not a function.
+     * 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): void;
+    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
+     *
+     * Correct formula: (shift >= THRESHOLD) ? 1 : 0
+     * Branchless: ((PHASE_THRESHOLD - 1 - shift) >>> 31)
+     *
+     * @returns 1 if urgent, 0 if normal
+     */
+    private _calculateUrgency;
     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.
+     */
     private _drainQueue;
+    /**
+     * Processes the urgent queue using double-buffering.
+     */
+    private _processUrgentQueue;
     private _processCurrentQueue;
     private _handleFlushOverflow;
     private _processJobs;
@@ -454,9 +505,16 @@ export declare class SchedulerError extends AtomError {
     constructor(message: string, cause?: Error | null);
 }
 
+/**
+ * Scheduler job interface with phase-shift tracking support.
+ * _cachedVersion enables priority calculation based on staleness.
+ */
 declare interface SchedulerJob {
     (): void;
+    /** Epoch for deduplication */
     _nextEpoch?: number;
+    /** Cached version for phase-shift priority calculation */
+    _cachedVersion?: number;
 }
 
 declare enum SchedulerPhase {