@but212/atom-effect 0.27.0 → 0.28.0

package/dist/index.d.ts

@@ -31,6 +31,17 @@ export declare class AtomError extends Error {
     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.
  */
@@ -47,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
@@ -186,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.
  *
@@ -203,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;
@@ -319,6 +370,15 @@ declare interface SchedulerJobObject {
     _nextEpoch?: number;
 }
 
+/**
+ * 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;
 }