@but212/atom-effect-jquery 0.25.0 → 0.26.0

package/dist/index.d.ts

@@ -19,6 +19,19 @@ declare type AsyncReactiveValue<T> = T | ReadonlyAtom<T | Promise<T>> | Promise<
 
 export { atom }
 
+/**
+ * Creates a two-way "lens" for a specific property path on an object-based atom.
+ * Optimized for performance using structural sharing and equality guards.
+ *
+ * This "fake" atom allows fine-grained binding to deep properties of a
+ * monolithic state atom without extra memory or complex computed logic.
+ *
+ * @param atom The source atom containing the object.
+ * @param path Dot-separated path to the property (e.g. 'user.profile.name').
+ * @returns A WritableAtom that reads from and writes to the specified path.
+ */
+export declare function atomLens<T extends object, P extends Paths<T>>(atom: WritableAtom<T>, path: P): WritableAtom<PathValue<T, P>>;
+
 export { batch }
 
 /**
@@ -88,6 +101,15 @@ declare class BindingRegistry {
  */
 export declare type ComponentFn<P = Record<string, unknown>> = ($el: JQuery, props: P) => EffectResult;
 
+/**
+ * Composes an existing lens with a sub-path to create a deeper lens.
+ *
+ * @param lens The parent lens.
+ * @param path Sub-path relative to the parent lens.
+ * @returns A new lens pointing to the deeper path.
+ */
+export declare function composeLens<T extends object, P extends Paths<T>>(lens: WritableAtom<T>, path: P): WritableAtom<PathValue<T, P>>;
+
 export { computed }
 
 export { ComputedAtom }
@@ -199,6 +221,16 @@ declare type KeysOfType<T, V> = {
     [K in keyof T]: T[K] extends V ? K : never;
 }[keyof T];
 
+/**
+ * Creates a lens factory bound to a specific atom.
+ * Eliminates the need to pass the atom reference on every call.
+ *
+ * @example
+ * const lens = lensFor(userAtom);
+ * const email = lens('settings.notifications.email'); // WritableAtom<boolean>
+ */
+export declare function lensFor<T extends object>(atom: WritableAtom<T>): <P extends Paths<T>>(path: P) => WritableAtom<PathValue<T, P>>;
+
 /** Key type for Map/Set inside list.ts */
 declare type ListKey = string | number;
 
@@ -238,6 +270,12 @@ export declare interface ListOptions<T> {
 /** Possible return types for render() / empty */
 declare type ListRenderResult = string | Element | DocumentFragment | JQuery;
 
+/**
+ * Maximum recursion depth for path generation.
+ * Prevents TypeScript compiler from hitting recursion limits on deeply nested types.
+ */
+declare type MaxDepth = 8;
+
 /**
  * Resolves after all pending microtask-scheduled reactive effects have flushed.
  *
@@ -257,6 +295,18 @@ declare type ListRenderResult = string | Element | DocumentFragment | JQuery;
  */
 export declare function nextTick(): Promise<void>;
 
+/**
+ * Generates a union of all valid dot-separated paths for type T.
+ */
+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;
+
+/**
+ * Extracts the value type at path P within type T.
+ */
+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;
+
 /**
  * Values allowed for DOM properties and attributes.
  */
@@ -308,6 +358,12 @@ export declare interface Router {
     destroy: () => void;
 }
 
+/**
+ * Helper to convert a numeric string to a number type, otherwise returns the string.
+ * Used for array indexing in paths.
+ */
+declare type StringKeyToNumber<S extends string> = S extends `${infer N extends number}` ? N : S;
+
 export declare interface TemplateRoute extends RouteLifecycle {
     template: string;
     render?: never;