@but212/atom-effect 0.26.0 → 0.28.0

package/dist/index.d.ts

@@ -27,9 +27,21 @@ export declare function atom<T>(initialValue: T, options?: AtomOptions): Writabl
 export declare class AtomError extends Error {
     cause: Error | null;
     recoverable: boolean;
+    name: string;
     constructor(message: string, cause?: Error | null, recoverable?: boolean);
 }
 
+/**
+ * Creates a two-way "lens" for a specific property path on an object-based atom.
+ *
+ * @example
+ * const store = atom({ user: { name: 'Alice' } });
+ * const nameLens = atomLens(store, 'user.name');
+ * console.log(nameLens.value); // 'Alice'
+ * nameLens.value = 'Bob'; // Updates store.user.name immutably
+ */
+export declare function atomLens<T extends object, P extends Paths<T>>(atom: WritableAtom<T>, path: P): WritableAtom<PathValue<T, P>>;
+
 /**
  * Atom options.
  */
@@ -46,6 +58,11 @@ export declare interface AtomOptions {
  */
 export declare function batch<T>(fn: () => T): T;
 
+/**
+ * Composes an existing lens with a sub-path to create a deeper lens.
+ */
+export declare const composeLens: <T extends object, P extends Paths<T>>(lens: WritableAtom<T>, path: P) => WritableAtom<PathValue<T, P>>;
+
 /**
  * Creates a computed value.
  * @param fn - Computation function
@@ -76,6 +93,7 @@ export declare interface ComputedAtom<T = unknown> extends ReadonlyAtom<T>, Disp
 
 /** Computed error. */
 export declare class ComputedError extends AtomError {
+    name: string;
     constructor(message: string, cause?: Error | null);
 }
 
@@ -104,7 +122,7 @@ export declare const DEBUG_CONFIG: {
 };
 
 /**
- * Debug controller.
+ * Global debug controller singleton.
  */
 export declare const DEBUG_RUNTIME: DebugConfig;
 
@@ -129,6 +147,8 @@ export declare interface Dependency {
     /* Excluded from this release type: version */
     /* Excluded from this release type: flags */
     /* Excluded from this release type: _lastSeenEpoch */
+    /* Excluded from this release type: isComputed */
+    /* Excluded from this release type: hasError */
     /**
      * Adds a subscriber to this dependency.
      * The listener may optionally receive the new and previous values.
@@ -157,6 +177,7 @@ export declare function effect(fn: EffectFunction, options?: EffectOptions): Eff
 
 /** Effect error. */
 export declare class EffectError extends AtomError {
+    name: string;
     constructor(message: string, cause?: Error | null);
 }
 
@@ -181,6 +202,11 @@ export declare interface EffectOptions {
     onError?: (error: unknown) => void;
 }
 
+/**
+ * Helper to retrieve a nested value from an object/array at a given path.
+ */
+export declare function getPathValue(source: unknown, parts: string[]): unknown;
+
 /**
  * Readonly atom check.
  *
@@ -198,6 +224,36 @@ export declare function isComputed(obj: unknown): obj is ComputedAtom;
  */
 export declare function isEffect(obj: unknown): obj is EffectObject;
 
+/**
+ * Creates a lens factory bound to a specific atom.
+ */
+export declare const lensFor: <T extends object>(atom: WritableAtom<T>) => <P extends Paths<T>>(path: P) => WritableAtom<PathValue<T, P>>;
+
+/** Max recursion depth for dot-paths. */
+export declare type MaxDepth = 8;
+
+/**
+ * Generates a union of all possible dot-separated paths for a given type T.
+ *
+ * Used for `atomLens` to provide IDE autocomplete and type safety when
+ * zooming into deeply nested reactive objects.
+ *
+ * @example
+ * type User = { profile: { name: string } };
+ * type P = Paths<User>; // "profile" | "profile.name"
+ */
+export declare type Paths<T, D extends unknown[] = []> = D['length'] extends MaxDepth ? never : T extends object ? {
+    [K in keyof T & (string | number)]-?: `${K}` | (T[K] extends object ? `${K}.${Paths<T[K], [...D, 1]>}` : never);
+}[keyof T & (string | number)] : never;
+
+/**
+ * Resolves the type of a value at a specific dot-path P within type T.
+ *
+ * Works in tandem with `Paths<T>` to ensure that lensed atoms have
+ * the correct inferred type for the member they point to.
+ */
+export declare type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? StringKeyToNumber<K> extends keyof T ? PathValue<T[StringKeyToNumber<K> & keyof T], Rest> : never : StringKeyToNumber<P> extends keyof T ? T[StringKeyToNumber<P> & keyof T] : never;
+
 export declare interface PoolStats {
     acquired: number;
     released: number;
@@ -235,7 +291,7 @@ export declare interface ReadonlyAtom<T = unknown> {
 /**
  * Scheduler implementation.
  */
-declare class Scheduler {
+declare class Scheduler_2 {
     /** Queue buffer */
     _queueBuffer: [SchedulerJob[], SchedulerJob[]];
     _bufferIndex: number;
@@ -244,7 +300,6 @@ declare class Scheduler {
     _epoch: number;
     /** State flags */
     _isProcessing: boolean;
-    _isBatching: boolean;
     _isFlushingSync: boolean;
     /** Batching state */
     _batchDepth: number;
@@ -256,7 +311,6 @@ declare class Scheduler {
     onOverflow: ((droppedCount: number) => void) | null;
     /** Bound run loop for microtask */
     private readonly _boundRunLoop;
-    get phase(): SchedulerPhase;
     get queueSize(): number;
     get isBatching(): boolean;
     /**
@@ -281,7 +335,8 @@ declare class Scheduler {
     setMaxFlushIterations(max: number): void;
 }
 
-export declare const scheduler: Scheduler;
+declare const scheduler_2: Scheduler_2;
+export { scheduler_2 as scheduler }
 
 /**
  * Scheduler configuration.
@@ -297,6 +352,7 @@ export declare const SCHEDULER_CONFIG: {
 
 /** Scheduler error. */
 export declare class SchedulerError extends AtomError {
+    name: string;
     constructor(message: string, cause?: Error | null);
 }
 
@@ -314,11 +370,14 @@ declare interface SchedulerJobObject {
     _nextEpoch?: number;
 }
 
-declare enum SchedulerPhase {
-    IDLE = 0,
-    BATCHING = 1,
-    FLUSHING = 2
-}
+/**
+ * Internal recursive helper for creating deep immutable copies with structural sharing.
+ * Only clones nodes along the path where changes occur.
+ */
+export declare function setDeepValue(obj: unknown, keys: string[], index: number, value: unknown): unknown;
+
+/** Helper to convert numeric string to number for array indexing. */
+export declare type StringKeyToNumber<S extends string> = S extends `${infer N extends number}` ? N : S;
 
 export declare interface Subscriber {
     execute(): void;