@cripty2001/utils 0.0.159 → 0.0.160

package/dist/react-whispr.d.ts

@@ -1,4 +1,5 @@
 import { Whispr } from "@cripty2001/whispr";
+import { JSONEncodable } from ".";
 import { Dispatcher } from "./Dispatcher";
 import { SearcherData } from "./Searcher";
 /**
@@ -130,3 +131,70 @@ export declare function useSearcher<T>(data: SearcherData<T>[], q: string): Sear
  * @returns
  */
 export declare function useSafeRef<T>(value: (() => T)): T;
+export type AsyncInputValue<C extends Record<string, JSONEncodable>, R extends Record<string, JSONEncodable>> = R & {
+    _meta: {
+        ts: number;
+        config: C;
+    };
+};
+/**
+ * Creates a bidirectional async input handler that manages synchronous config updates
+ * and asynchronous result computation with automatic deduplication and conflict resolution.
+ *
+ * This hook acts as a "gateway" between controlled input components and expensive async
+ * operations (like autocomplete, search, or validation). It maintains two separate concerns:
+ *
+ * 1. **External state** (`value`/`setValue` params): Contains only valid, complete data.
+ *    Updates when async operations complete. Parent components see no debouncing/loading states.
+ *
+ * 2. **Internal state** (returned `value`/`setValue`): Synchronously tracks user input/config.
+ *    Updates immediately on user interaction without waiting for async results.
+ *
+ * The hook automatically:
+ * - Merges updates from both external (param) and internal (returned) setValue calls
+ * - Detects and discards stale async results
+ * - Handles concurrent updates gracefully with last-write-wins semantics
+ *
+ * @template C - Configuration object type (the input/config that triggers async work)
+ * @template R - Result object type (the output of the async handler)
+ *
+ * @param value - Current external value containing both result data and metadata with config/timestamp. Metadata should be considered opaque, and always carried araoud as they are
+ * @param setValue - Callback to update external value when async operations complete
+ * @param handler - Async function that computes results from config.
+ *
+ * @returns Array containing:
+ *   - `value`: Current config (updates synchronously with user input)
+ *   - `setValue`: Function to update config (triggers new async operation)
+ *   - `result`: Latest computed result or null if no result yet. Useful for displaying loaders
+ *
+ * @example
+ * ```tsx
+ * // Parent component manages complete, valid autocomplete selections
+ * const [selectedUser, setSelectedUser] = useState<AsyncInputValue<{query: string}, {id: string, name: string}>>(...)
+ *
+ * function AutocompleteInput({selectedUser, setSelectedUser}) {
+ *   const [ value, setValue, result ] = useAsyncInput<{query: string}, {id: string, name: string}>(
+ *     selectedUser,
+ *     setSelectedUser,
+ *     async ({query}) => fetchUsers(query) // Debounced by useAsync
+ *   );
+ *
+ *   return (
+ *     <input
+ *       value={value.query}
+ *       onChange={e => setValue({query: e.target.value})} // Immediate update
+ *     />
+ *     {result === null ? <Spinner /> : <UserList users={result} />}
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * The returned `result` will lag behind `value` during async processing. Consider showing a loader or some other similar indication
+ * Handler is NOT reactive. Conceptually it is a pure function that derives an async status from the value input, so there is no reason for it to be reactive, and this saves a lot heachaches with react reactivity loops.
+ */
+export declare function useAsyncInput<C extends Record<string, JSONEncodable>, R extends Record<string, JSONEncodable>>(value: AsyncInputValue<C, R>, setValue: (value: AsyncInputValue<C, R>) => void, handler: (config: C) => Promise<R>): [
+    value: C,
+    setValue: (value: C) => void,
+    result: R | null
+];

package/dist/react-whispr.js

@@ -11,6 +11,7 @@ exports.useAsyncEffect = useAsyncEffect;
 exports.useRelTime = useRelTime;
 exports.useSearcher = useSearcher;
 exports.useSafeRef = useSafeRef;
+exports.useAsyncInput = useAsyncInput;
 const whispr_1 = require("@cripty2001/whispr");
 const react_1 = require("react");
 const lodash_1 = require("lodash");
@@ -108,7 +109,7 @@ function useSynced(def, value, setValue) {
     const [v, setV] = (0, react_1.useState)(def);
     if ((value !== undefined && setValue === undefined) ||
         (value === undefined && setValue !== undefined))
-        throw new Error('Either value and setValue must be provided, or both must be undefined');
+        throw new Error('Either both value and setValue must be provided, or both must be undefined');
     const setValueRef = (0, react_1.useRef)(setValue);
     (0, react_1.useEffect)(() => {
         setValueRef.current = setValue;
@@ -294,3 +295,111 @@ function useSafeRef(value) {
     }
     return ref.current;
 }
+/**
+ * Creates a bidirectional async input handler that manages synchronous config updates
+ * and asynchronous result computation with automatic deduplication and conflict resolution.
+ *
+ * This hook acts as a "gateway" between controlled input components and expensive async
+ * operations (like autocomplete, search, or validation). It maintains two separate concerns:
+ *
+ * 1. **External state** (`value`/`setValue` params): Contains only valid, complete data.
+ *    Updates when async operations complete. Parent components see no debouncing/loading states.
+ *
+ * 2. **Internal state** (returned `value`/`setValue`): Synchronously tracks user input/config.
+ *    Updates immediately on user interaction without waiting for async results.
+ *
+ * The hook automatically:
+ * - Merges updates from both external (param) and internal (returned) setValue calls
+ * - Detects and discards stale async results
+ * - Handles concurrent updates gracefully with last-write-wins semantics
+ *
+ * @template C - Configuration object type (the input/config that triggers async work)
+ * @template R - Result object type (the output of the async handler)
+ *
+ * @param value - Current external value containing both result data and metadata with config/timestamp. Metadata should be considered opaque, and always carried araoud as they are
+ * @param setValue - Callback to update external value when async operations complete
+ * @param handler - Async function that computes results from config.
+ *
+ * @returns Array containing:
+ *   - `value`: Current config (updates synchronously with user input)
+ *   - `setValue`: Function to update config (triggers new async operation)
+ *   - `result`: Latest computed result or null if no result yet. Useful for displaying loaders
+ *
+ * @example
+ * ```tsx
+ * // Parent component manages complete, valid autocomplete selections
+ * const [selectedUser, setSelectedUser] = useState<AsyncInputValue<{query: string}, {id: string, name: string}>>(...)
+ *
+ * function AutocompleteInput({selectedUser, setSelectedUser}) {
+ *   const [ value, setValue, result ] = useAsyncInput<{query: string}, {id: string, name: string}>(
+ *     selectedUser,
+ *     setSelectedUser,
+ *     async ({query}) => fetchUsers(query) // Debounced by useAsync
+ *   );
+ *
+ *   return (
+ *     <input
+ *       value={value.query}
+ *       onChange={e => setValue({query: e.target.value})} // Immediate update
+ *     />
+ *     {result === null ? <Spinner /> : <UserList users={result} />}
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * The returned `result` will lag behind `value` during async processing. Consider showing a loader or some other similar indication
+ * Handler is NOT reactive. Conceptually it is a pure function that derives an async status from the value input, so there is no reason for it to be reactive, and this saves a lot heachaches with react reactivity loops.
+ */
+function useAsyncInput(value, setValue, handler) {
+    const [meta, setMeta] = (0, react_1.useState)({
+        config: value._meta.config,
+        ts: value._meta.ts
+    });
+    (0, react_1.useEffect)(() => {
+        if (value._meta.ts > meta.ts) {
+            setMeta(value._meta);
+        }
+    }, [value, meta, setMeta]);
+    // // React has always random problems with stale closures, expecially in async environment.
+    // // On the other side, the watched param of useAsync is always perfect
+    // // We aren't taking any risks, here
+    // type AsyncPack = {
+    //   c: C,
+    //   ts: number,
+    // }
+    // const asyncPack: AsyncPack = useMemo(() => {
+    //   return {
+    //     c: meta.config,
+    //     ts: meta.ts,
+    //   }
+    // }, [meta]);
+    const result_d = useAsync(async ({ config, ts }) => {
+        console.log("useAsyncInput", { config, ts });
+        const r = await handler(config);
+        return {
+            ...r,
+            _meta: {
+                ts: ts,
+                config: config,
+            },
+        };
+    }, meta, 0);
+    const result = useWhisprValue(result_d.filtered);
+    (0, react_1.useEffect)(() => {
+        if (result === null)
+            return;
+        setValue(result);
+    }, [result, setValue]);
+    const returnedSetValue = (0, react_1.useCallback)((v) => {
+        setMeta({
+            config: v,
+            ts: Date.now(),
+        });
+    }, [setMeta]);
+    return [
+        meta.config,
+        returnedSetValue,
+        result,
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cripty2001/utils",
-  "version": "0.0.159",
+  "version": "0.0.160",
   "description": "Internal Set of utils. If you need them use them, otherwise go to the next package ;)",
   "homepage": "https://github.com/cripty2001/utils#readme",
   "bugs": {