@neovici/cosmoz-form 2.1.0 → 2.2.0

package/dist/test/use-async-form-core.test.js

@@ -0,0 +1,238 @@
+import { renderHook } from '@neovici/testing';
+import { assert, waitUntil } from '@open-wc/testing';
+import { spy } from 'sinon';
+import { delay } from '../async-rule';
+import { makeDebounceRunner } from '../make-debounce-runner';
+import { touched } from '../touch';
+import { useAsyncFormCore } from '../use-async-form-core';
+import { useForm } from '../use-form';
+// ── Helpers ───────────────────────────────────────────────────────────────────
+const tick = (ms = 0) => new Promise((r) => setTimeout(r, ms));
+// ── Suite ─────────────────────────────────────────────────────────────────────
+suite('useAsyncFormCore', () => {
+    // Basic rule: when name changes, set city = name + '-city'
+    const cityFromName = [
+        async (current) => ({ city: current.name + '-city' }),
+        ({ name }) => [name],
+    ];
+    test('rule runs on initialization (prev deps are null → runs)', async () => {
+        const { result } = await renderHook(() => {
+            const form = useForm({ name: 'Alice', city: '' });
+            useAsyncFormCore(form, [cityFromName]);
+            return form;
+        });
+        await waitUntil(() => result.current.values.city === 'Alice-city');
+    });
+    test('rule does NOT run again if deps unchanged (onChange with unrelated field)', async () => {
+        const { result } = await renderHook(() => {
+            const form = useForm({ name: 'Alice', city: '' });
+            useAsyncFormCore(form, [cityFromName]);
+            return form;
+        });
+        await waitUntil(() => result.current.values.city === 'Alice-city');
+        // change city manually — name (dep) didn't change so rule should NOT re-run
+        result.current.onChange({ city: 'manual' });
+        await tick(50); // give rule time to NOT re-run
+        assert.equal(result.current.values.city, 'manual');
+    });
+    test('rule runs again when deps change (name changes → city updated)', async () => {
+        const { result } = await renderHook(() => {
+            const form = useForm({ name: 'Alice', city: '' });
+            useAsyncFormCore(form, [cityFromName]);
+            return form;
+        });
+        await waitUntil(() => result.current.values.city === 'Alice-city');
+        result.current.onChange({ name: 'Bob' }); // dep changed
+        await waitUntil(() => result.current.values.city === 'Bob-city');
+    });
+    test('takeLatest — slow rule is cancelled when deps change again', async () => {
+        const slowRule = [
+            async (current, { signal }) => {
+                await delay(signal, 200);
+                return { city: current.name + '-slow' };
+            },
+            ({ name }) => [name],
+        ];
+        const { result } = await renderHook(() => {
+            const form = useForm({ name: 'Alice', city: '' });
+            useAsyncFormCore(form, [slowRule]);
+            return form;
+        });
+        // initial rule for Alice kicked off (slow, 200ms)
+        await tick(10); // let Alice rule start
+        result.current.onChange({ name: 'Bob' }); // triggers second rule, cancels first
+        await waitUntil(() => result.current.values.city === 'Bob-slow', 'Bob-slow should appear', { timeout: 2000 });
+        // Alice-slow must never appear
+        assert.notEqual(result.current.values.city, 'Alice-slow');
+    });
+    test('opts.update() fires intermediate patch before rule completes', async () => {
+        const loadingRule = [
+            async (current, { update, signal }) => {
+                update({ city: 'loading...' });
+                await delay(signal, 50);
+                return { city: current.name + '-done' };
+            },
+            ({ name }) => [name],
+        ];
+        const { result } = await renderHook(() => {
+            const form = useForm({ name: 'Alice', city: '' });
+            useAsyncFormCore(form, [loadingRule]);
+            return form;
+        });
+        // loading patch fires before the delay
+        await waitUntil(() => result.current.values.city === 'loading...');
+        // then the final patch arrives after the delay
+        await waitUntil(() => result.current.values.city === 'Alice-done', 'Alice-done should appear', { timeout: 2000 });
+    });
+    test('async patches do not set form.touched', async () => {
+        const { result } = await renderHook(() => {
+            const form = useForm({ name: 'Alice', city: '' });
+            useAsyncFormCore(form, [cityFromName]);
+            return form;
+        });
+        await waitUntil(() => result.current.values.city === 'Alice-city');
+        assert.isFalse(touched(result.current.values));
+    });
+    test('onError called with (err, rule) when rule throws', async () => {
+        const boom = [
+            async () => {
+                throw new Error('rule boom');
+            },
+            ({ name }) => [name],
+        ];
+        const onError = spy();
+        await renderHook(() => {
+            const form = useForm({ name: 'Alice', city: '' });
+            useAsyncFormCore(form, [boom], { onError });
+            return form;
+        });
+        await waitUntil(() => onError.called, 'onError should be called');
+        assert.instanceOf(onError.args[0][0], Error);
+        assert.equal(onError.args[0][0].message, 'rule boom');
+        assert.equal(onError.args[0][1], boom);
+    });
+    test('uses runner factory from the rule — debounce semantics observed', async () => {
+        const debounceRule = [
+            async (current) => ({ city: current.name + '-debounced' }),
+            ({ name }) => [name],
+            () => makeDebounceRunner(100),
+        ];
+        const { result } = await renderHook(() => {
+            const form = useForm({ name: 'Alice', city: '' });
+            useAsyncFormCore(form, [debounceRule]);
+            return form;
+        });
+        // Two rapid dep changes within the 100ms debounce window
+        result.current.onChange({ name: 'Bob' });
+        await tick(30); // within debounce window
+        result.current.onChange({ name: 'Carol' });
+        // Wait long enough for the debounce to fire and rule to complete
+        await waitUntil(() => result.current.values.city !== '', 'city should be set', { timeout: 2000 });
+        // Only Carol's rule should have applied — Bob's was debounced away
+        assert.equal(result.current.values.city, 'Carol-debounced');
+        assert.notEqual(result.current.values.city, 'Bob-debounced');
+    });
+    test('processing is false initially', async () => {
+        const { result } = await renderHook(() => {
+            const form = useForm({ name: 'Alice', city: '' });
+            return useAsyncFormCore(form, [cityFromName]);
+        });
+        await waitUntil(() => result.current.processing === false);
+        assert.isFalse(result.current.processing);
+    });
+    test('processing is true while a rule is in flight', async () => {
+        const slowRule = [
+            async (current, { signal }) => {
+                await delay(signal, 100);
+                return { city: current.name + '-slow' };
+            },
+            ({ name }) => [name],
+        ];
+        const { result } = await renderHook(() => {
+            const form = useForm({ name: 'Alice', city: '' });
+            return useAsyncFormCore(form, [slowRule]);
+        });
+        await waitUntil(() => result.current.processing === true);
+        assert.isTrue(result.current.processing);
+        await waitUntil(() => result.current.processing === false, undefined, {
+            timeout: 2000,
+        });
+        assert.isFalse(result.current.processing);
+    });
+    test('processing stays true while multiple rules are in flight', async () => {
+        const slowRule1 = [
+            async (current, { signal }) => {
+                await delay(signal, 80);
+                return { city: current.name + '-1' };
+            },
+            ({ name }) => [name],
+        ];
+        const slowRule2 = [
+            async (current, { signal }) => {
+                await delay(signal, 160);
+                return { city: current.name + '-2' };
+            },
+            ({ name }) => [name],
+        ];
+        const { result } = await renderHook(() => {
+            const form = useForm({ name: 'Alice', city: '' });
+            return useAsyncFormCore(form, [slowRule1, slowRule2]);
+        });
+        await waitUntil(() => result.current.processing === true);
+        // After first settles (~80ms) processing must still be true (second still running)
+        await tick(100);
+        assert.isTrue(result.current.processing);
+        // After both settle — processing false
+        await waitUntil(() => result.current.processing === false, undefined, {
+            timeout: 2000,
+        });
+        assert.isFalse(result.current.processing);
+    });
+    test('processing returns to false when a rule is cancelled (runner returns null)', async () => {
+        const slowRule = [
+            async (current, { signal }) => {
+                await delay(signal, 200);
+                return { city: current.name + '-slow' };
+            },
+            ({ name }) => [name],
+        ];
+        const { result } = await renderHook(() => {
+            const form = useForm({ name: 'Alice', city: '' });
+            return useAsyncFormCore(form, [slowRule]);
+        });
+        await waitUntil(() => result.current.processing === true);
+        // Trigger a new dep change — cancels previous rule, starts a new one
+        result.current.onChange({ name: 'Bob' });
+        await waitUntil(() => result.current.processing === false, undefined, {
+            timeout: 2000,
+        });
+        assert.isFalse(result.current.processing);
+    });
+    test('cleanup — no state update after unmount', async () => {
+        const slowRule = [
+            async (current, { signal }) => {
+                await delay(signal, 100);
+                return { city: current.name + '-after-unmount' };
+            },
+            ({ name }) => [name],
+        ];
+        const onChangeSpy = spy();
+        const { unmount } = await renderHook(() => {
+            const form = useForm({ name: 'Alice', city: '' });
+            const wrappedForm = {
+                ...form,
+                onChange: (...args) => {
+                    onChangeSpy(...args);
+                    return form.onChange(...args);
+                },
+            };
+            useAsyncFormCore(wrappedForm, [slowRule]);
+            return wrappedForm;
+        });
+        await tick(10); // mid-delay
+        const callsBefore = onChangeSpy.callCount;
+        unmount(); // cancel in-flight rule
+        await tick(200); // wait for what would have been the delay
+        assert.equal(onChangeSpy.callCount, callsBefore, 'no onChange after unmount');
+    });
+});

package/dist/test/use-async-rules.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=use-async-rules.test.d.ts.map

package/dist/test/use-async-rules.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-async-rules.test.d.ts","sourceRoot":"","sources":["../../src/test/use-async-rules.test.ts"],"names":[],"mappings":""}

package/dist/test/use-async-rules.test.js

@@ -0,0 +1,180 @@
+import { renderHook } from '@neovici/testing';
+import { assert, waitUntil } from '@open-wc/testing';
+import { spy } from 'sinon';
+import { delay } from '../async-rule';
+import { makeDebounceRunner } from '../make-debounce-runner';
+import { useItems } from '../use-items';
+import { useAsyncRules } from '../use-items/use-async-rules';
+// ── Helpers ───────────────────────────────────────────────────────────────────
+const tick = (ms = 0) => new Promise((r) => setTimeout(r, ms));
+// ── Suite ─────────────────────────────────────────────────────────────────────
+suite('useAsyncRules (items)', () => {
+    // Basic rule: derived = name + '-' + idx
+    const derivedFromName = [
+        async (current, { index }) => ({ derived: current.name + '-' + index }),
+        ({ name }, idx) => [name, idx],
+    ];
+    test('rule runs per-item on initialization', async () => {
+        const { result } = await renderHook(() => {
+            const core = useItems({
+                initial: [{ name: 'A' }, { name: 'B' }],
+            });
+            useAsyncRules(core.items, [derivedFromName], core.update);
+            return core;
+        });
+        await waitUntil(() => result.current.items[0]?.derived !== undefined &&
+            result.current.items[1]?.derived !== undefined);
+        assert.equal(result.current.items[0].derived, 'A-0');
+        assert.equal(result.current.items[1].derived, 'B-1');
+    });
+    test('rule result applied to correct item index', async () => {
+        const { result } = await renderHook(() => {
+            const core = useItems({
+                initial: [{ name: 'X' }, { name: 'Y' }],
+            });
+            useAsyncRules(core.items, [derivedFromName], core.update);
+            return core;
+        });
+        await waitUntil(() => result.current.items[0]?.derived !== undefined);
+        assert.equal(result.current.items[0].derived, 'X-0');
+        assert.equal(result.current.items[1].derived, 'Y-1');
+    });
+    test('rule does not run for items whose deps are unchanged', async () => {
+        const { result } = await renderHook(() => {
+            const core = useItems({ initial: [{ name: 'A' }] });
+            useAsyncRules(core.items, [derivedFromName], core.update);
+            return core;
+        });
+        await waitUntil(() => result.current.items[0]?.derived === 'A-0');
+        // Manually set derived to 'manual', then trigger a re-render without changing name/idx
+        result.current.update(0, { derived: 'manual' });
+        await tick(50); // give rule time to NOT re-run
+        assert.equal(result.current.items[0].derived, 'manual');
+    });
+    test('changing item[0] triggers rule for item[0] only, not item[1]', async () => {
+        const runCounts = { 0: 0, 1: 0 };
+        const countingRule = [
+            async (current, { index }) => {
+                runCounts[index]++;
+                return { derived: current.name + '-' + index };
+            },
+            ({ name }, idx) => [name, idx],
+        ];
+        const { result } = await renderHook(() => {
+            const core = useItems({
+                initial: [{ name: 'A' }, { name: 'B' }],
+            });
+            useAsyncRules(core.items, [countingRule], core.update);
+            return core;
+        });
+        await waitUntil(() => result.current.items[0]?.derived !== undefined);
+        const runBefore1 = runCounts[1];
+        result.current.update(0, { name: 'A2' }); // only item[0] changes
+        await waitUntil(() => result.current.items[0].derived === 'A2-0');
+        assert.equal(runCounts[1], runBefore1);
+    });
+    test('per-item takeLatest — item[0] rule cancelled independently of item[1]', async () => {
+        const slowRule = [
+            async (current, { signal, index }) => {
+                await delay(signal, 150);
+                return { derived: current.name + '-slow-' + index };
+            },
+            ({ name }, idx) => [name, idx],
+        ];
+        const { result } = await renderHook(() => {
+            const core = useItems({
+                initial: [{ name: 'A' }, { name: 'B' }],
+            });
+            useAsyncRules(core.items, [slowRule], core.update);
+            return core;
+        });
+        await tick(10);
+        // Change item[0] name mid-flight (cancels item[0] first rule)
+        result.current.update(0, { name: 'A2' });
+        await waitUntil(() => result.current.items[0]?.derived === 'A2-slow-0', 'A2-slow-0 should appear', { timeout: 2000 });
+        assert.equal(result.current.items[1].derived, 'B-slow-1');
+        assert.notEqual(result.current.items[0].derived, 'A-slow-0');
+    });
+    test('intermediate opts.update patch applied to correct item only', async () => {
+        const loadingRule = [
+            async (current, { update, signal, index }) => {
+                update({ derived: 'loading-' + index });
+                await delay(signal, 50);
+                return { derived: current.name + '-done-' + index };
+            },
+            ({ name }, idx) => [name, idx],
+        ];
+        const { result } = await renderHook(() => {
+            const core = useItems({
+                initial: [{ name: 'A' }, { name: 'B' }],
+            });
+            useAsyncRules(core.items, [loadingRule], core.update);
+            return core;
+        });
+        await waitUntil(() => result.current.items[0]?.derived === 'loading-0');
+        assert.equal(result.current.items[1].derived, 'loading-1');
+        await waitUntil(() => result.current.items[0]?.derived === 'A-done-0', undefined, { timeout: 2000 });
+        assert.equal(result.current.items[1].derived, 'B-done-1');
+    });
+    test('onError called with (err, rule, index)', async () => {
+        const boom = [
+            async () => {
+                throw new Error('item boom');
+            },
+            ({ name }, idx) => [name, idx],
+        ];
+        const onError = spy();
+        await renderHook(() => {
+            const core = useItems({ initial: [{ name: 'A' }] });
+            useAsyncRules(core.items, [boom], core.update, { onError });
+            return core;
+        });
+        await waitUntil(() => onError.called, 'onError should be called');
+        assert.instanceOf(onError.args[0][0], Error);
+        assert.equal(onError.args[0][1], boom);
+        assert.equal(onError.args[0][2], 0); // index
+    });
+    test('runner map grows when items are appended — new item rule runs', async () => {
+        const { result } = await renderHook(() => {
+            const core = useItems({ initial: [{ name: 'A' }] });
+            useAsyncRules(core.items, [derivedFromName], core.update);
+            return core;
+        });
+        await waitUntil(() => result.current.items[0]?.derived === 'A-0');
+        result.current.update(1, { name: 'B' }); // append
+        await waitUntil(() => result.current.items[1]?.derived === 'B-1');
+    });
+    test('uses runner factory from the rule — debounce semantics observed', async () => {
+        const debounceRule = [
+            async (current, { index }) => ({
+                derived: current.name + '-debounced-' + index,
+            }),
+            ({ name }, idx) => [name, idx],
+            () => makeDebounceRunner(100),
+        ];
+        const { result } = await renderHook(() => {
+            const core = useItems({ initial: [{ name: 'A' }] });
+            useAsyncRules(core.items, [debounceRule], core.update);
+            return core;
+        });
+        // Two rapid dep changes within the 100ms debounce window
+        result.current.update(0, { name: 'B' });
+        await tick(30);
+        result.current.update(0, { name: 'C' });
+        await waitUntil(() => result.current.items[0]?.derived !== undefined, 'derived should be set', { timeout: 2000 });
+        assert.equal(result.current.items[0].derived, 'C-debounced-0');
+        assert.notEqual(result.current.items[0].derived, 'B-debounced-0');
+    });
+    test('no stale runner for removed item — new item at index 0 gets a fresh rule', async () => {
+        const { result } = await renderHook(() => {
+            const core = useItems({
+                initial: [{ name: 'A' }, { name: 'B' }],
+            });
+            useAsyncRules(core.items, [derivedFromName], core.update);
+            return core;
+        });
+        await waitUntil(() => result.current.items[0]?.derived === 'A-0');
+        result.current.remove(0); // remove item[0], 'B' shifts to index 0
+        await waitUntil(() => result.current.items[0]?.derived === 'B-0', 'B-0 should appear after removal', { timeout: 2000 });
+    });
+});

package/dist/types/index.d.ts

@@ -7,7 +7,7 @@ export type Invokable<T, F, V, R> = R | Invoked<T, F, V, R>;
 export type Resolvable<T, A extends unknown[] = []> = T | PromiseLike<T> | ((...args: A) => T | PromiseLike<T>);
 export type OnFocusFn<T, F, V> = (onChange: (value: V, touched?: boolean) => void, value: V, values: T, field: F) => (event: FocusEvent) => void;
 export type OnChange<T, K, V> = (update: (changes: Partial<T>, touched?: boolean) => void, id: K, value: V, values: T) => void;
-export type Rule<T extends object, K extends keyof T, V extends T[K]> = (value: V, values: T, field: Field<T, K, V>) => false | string;
+export type Rule<T extends object, K extends keyof T, V extends T[K]> = (value: V, values?: T, field?: Field<T, K, V>) => false | string;
 export type Errors = {
     [key: string]: string | true | undefined;
 };

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,MAAM,MAAM,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;AAEvE,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAE5D,MAAM,MAAM,UAAU,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,EAAE,GAAG,EAAE,IAC/C,CAAC,GACD,WAAW,CAAC,CAAC,CAAC,GACd,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AAExC,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAChC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,EAC/C,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,CAAC,KACJ,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;AAEjC,MAAM,MAAM,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAC/B,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,EACxD,EAAE,EAAE,CAAC,EACL,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,CAAC,KACL,IAAI,CAAC;AAEV,MAAM,MAAM,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CACvE,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KACjB,KAAK,GAAG,MAAM,CAAC;AAEpB,MAAM,MAAM,MAAM,GAAG;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IACrE,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACb,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AAEnB,MAAM,MAAM,UAAU,GACnB,IAAI,GACJ,SAAS,GACT;IAAE,QAAQ,IAAI,MAAM,CAAA;CAAE,GACtB,aAAa,CAAC,UAAU,CAAC,CAAC;AAE7B,MAAM,WAAW,UAAU,CAC1B,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,MAAM,CAAC,EACjB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CACb,SAAQ,OAAO,CAAC,CAAC,CAAC;IACnB,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACtB,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CACjB;AAGD,MAAM,WAAW,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACzE,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,UAAU,CAAC;CACxC;AAED,MAAM,MAAM,KAAK,CAChB,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,MAAM,CAAC,EACjB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IACX,SAAS;IACZ,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;IACtC,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;CACtC,CAAC;AAEF,MAAM,WAAW,KAAK,CACrB,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,MAAM,CAAC,EACjB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAGrB,SACC,gBAAgB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACzB,aAAa,EACb,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC1B,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAClB,mBAAmB;IACpB,EAAE,EAAE,CAAC,CAAC;IACN,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;IACf,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IACtD,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7B,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;IACrD,QAAQ,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;IACpD,MAAM,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;IAClD,OAAO,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;IACtD,MAAM,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;IACrD,MAAM,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;IAErD,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7B,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IACtB,MAAM,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IACjD,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CACvB;AAED,MAAM,MAAM,MAAM,CAAC,CAAC,SAAS,MAAM,IAAI,SAAS;KAC9C,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7C,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;AAEb,OAAO,EAAE,cAAc,IAAI,aAAa,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/use-async-form-core.d.ts

@@ -0,0 +1,21 @@
+import type { AsyncItemRule } from './async-rule';
+import type { UseForm } from './use-form-core';
+/**
+ * Composes with UseForm<T> to add async rules.
+ * Returns UseForm<T> & { processing } where processing is true while any
+ * async rule is in flight.
+ *
+ * Async patches call onChange(patch, false) — they do not mark the form touched.
+ * Intermediate patches (from opts.update(...)) go through onChange like any other
+ * patch — sync rules cascade on top of them, which is expected.
+ *
+ * Usage:
+ *   const form = useValidatedForm({ fields, initial, rules });
+ *   const { processing } = useAsyncFormCore(form, asyncRules);
+ */
+export declare const useAsyncFormCore: <T extends object>(form: UseForm<T>, asyncRules: readonly AsyncItemRule<T>[] | undefined, opts?: {
+    onError?: (err: unknown, rule: AsyncItemRule<T>) => void;
+}) => UseForm<T> & {
+    processing: boolean;
+};
+//# sourceMappingURL=use-async-form-core.d.ts.map

package/dist/use-async-form-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-async-form-core.d.ts","sourceRoot":"","sources":["../src/use-async-form-core.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,cAAc,CAAC;AAE/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAU/C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,MAAM,EAChD,MAAM,OAAO,CAAC,CAAC,CAAC,EAChB,YAAY,SAAS,aAAa,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,EACnD,OAAO;IAAE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;CAAE,KACjE,OAAO,CAAC,CAAC,CAAC,GAAG;IAAE,UAAU,EAAE,OAAO,CAAA;CAkEpC,CAAC"}

package/dist/use-async-form-core.js

@@ -0,0 +1,71 @@
+import { useEffect, useRef, useState } from '@pionjs/pion';
+import { makeTakeLatestRunner } from './make-take-latest-runner';
+const changed = (a, b) => a.length !== b.length || a.some((v, i) => !Object.is(v, b[i]));
+const DEFAULT_ON_ERROR = (err) => {
+    // eslint-disable-next-line no-console
+    console.error('[cosmoz-form] async rule error:', err);
+};
+/**
+ * Composes with UseForm<T> to add async rules.
+ * Returns UseForm<T> & { processing } where processing is true while any
+ * async rule is in flight.
+ *
+ * Async patches call onChange(patch, false) — they do not mark the form touched.
+ * Intermediate patches (from opts.update(...)) go through onChange like any other
+ * patch — sync rules cascade on top of them, which is expected.
+ *
+ * Usage:
+ *   const form = useValidatedForm({ fields, initial, rules });
+ *   const { processing } = useAsyncFormCore(form, asyncRules);
+ */
+export const useAsyncFormCore = (form, asyncRules, opts) => {
+    const onError = opts?.onError ?? DEFAULT_ON_ERROR;
+    // Refs persist across renders without triggering re-renders
+    const runnersRef = useRef(new Map());
+    const prevDepsRef = useRef(new Map());
+    // pendingCount tracks in-flight rules without causing re-renders itself.
+    // processing state is updated only on 0→1 and 1→0 transitions.
+    const pendingCount = useRef(0);
+    const [processing, setProcessing] = useState(false);
+    // Cleanup: cancel all in-flight rules on unmount
+    useEffect(() => () => {
+        for (const runner of runnersRef.current.values())
+            runner.cancel();
+    }, []);
+    // Dep-check + rule dispatch: runs after every values change
+    useEffect(() => {
+        if (!asyncRules?.length)
+            return;
+        for (const rule of asyncRules) {
+            const [ruleFn, depsFn, runnerFactory = makeTakeLatestRunner] = rule;
+            if (!runnersRef.current.has(rule)) {
+                runnersRef.current.set(rule, runnerFactory());
+            }
+            const deps = depsFn(form.values);
+            const prev = prevDepsRef.current.get(rule);
+            // Skip if deps unchanged (Object.is per element, same as applyRules)
+            if (prev != null && !changed(deps, prev)) {
+                continue;
+            }
+            prevDepsRef.current.set(rule, deps);
+            const runner = runnersRef.current.get(rule);
+            pendingCount.current++;
+            if (pendingCount.current === 1)
+                setProcessing(true);
+            runner
+                .run(ruleFn, form.values, (patch) => form.onChange(patch, false))
+                .then((result) => {
+                if (result !== null) {
+                    form.onChange(result, false); // final: no touch
+                }
+            })
+                .catch((err) => onError(err, rule))
+                .finally(() => {
+                pendingCount.current--;
+                if (pendingCount.current === 0)
+                    setProcessing(false);
+            });
+        }
+    }, [form.values]);
+    return { ...form, processing };
+};

package/dist/use-items/use-async-rules.d.ts

@@ -0,0 +1,17 @@
+import type { AsyncItemRule } from '../async-rule';
+import type { UseItemsCore } from './use-items';
+/**
+ * Composes with useItemsCore / useItems to add async rules.
+ * One runner per (rule, itemIndex) pair — item rules are independent.
+ *
+ * Usage:
+ *   const core = useItems({ initial, rules });
+ *   useAsyncRules(core.items, asyncRules, core.update);
+ *   return core;
+ */
+export declare const useAsyncRules: <T extends object>(items: T[], asyncRules: readonly AsyncItemRule<T>[] | undefined, update: UseItemsCore<T>["update"], opts?: {
+    onError?: (err: unknown, rule: AsyncItemRule<T>, index: number) => void;
+}) => {
+    processing: boolean;
+};
+//# sourceMappingURL=use-async-rules.d.ts.map

package/dist/use-items/use-async-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-async-rules.d.ts","sourceRoot":"","sources":["../../src/use-items/use-async-rules.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,eAAe,CAAC;AAEhE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAuBhD;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,MAAM,EAC7C,OAAO,CAAC,EAAE,EACV,YAAY,SAAS,aAAa,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,EACnD,QAAQ,YAAY,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EACjC,OAAO;IACN,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACxE,KACC;IAAE,UAAU,EAAE,OAAO,CAAA;CA0EvB,CAAC"}

package/dist/use-items/use-async-rules.js

@@ -0,0 +1,78 @@
+import { useEffect, useRef, useState } from '@pionjs/pion';
+import { makeTakeLatestRunner } from '../make-take-latest-runner';
+const changed = (a, b) => a.length !== b.length || a.some((v, i) => !Object.is(v, b[i]));
+const DEFAULT_ON_ERROR = (err) => {
+    // eslint-disable-next-line no-console
+    console.error('[cosmoz-form] async rule error:', err);
+};
+const ensureRuleTracking = (rule, runnersRef, prevDepsRef) => {
+    if (runnersRef.current.has(rule))
+        return;
+    runnersRef.current.set(rule, new Map());
+    prevDepsRef.current.set(rule, new Map());
+};
+/**
+ * Composes with useItemsCore / useItems to add async rules.
+ * One runner per (rule, itemIndex) pair — item rules are independent.
+ *
+ * Usage:
+ *   const core = useItems({ initial, rules });
+ *   useAsyncRules(core.items, asyncRules, core.update);
+ *   return core;
+ */
+export const useAsyncRules = (items, asyncRules, update, opts) => {
+    const onError = opts?.onError ?? DEFAULT_ON_ERROR;
+    const pendingCount = useRef(0);
+    const [processing, setProcessing] = useState(false);
+    const runnersRef = useRef(new Map());
+    const prevDepsRef = useRef(new Map());
+    // Cleanup on unmount
+    useEffect(() => () => {
+        for (const perItem of runnersRef.current.values()) {
+            for (const runner of perItem.values()) {
+                runner.cancel();
+            }
+        }
+    }, []);
+    // Dep-check + rule dispatch: runs after every items change
+    useEffect(() => {
+        if (!asyncRules?.length) {
+            return;
+        }
+        for (const rule of asyncRules) {
+            const [ruleFn, depsFn, runnerFactory = makeTakeLatestRunner] = rule;
+            ensureRuleTracking(rule, runnersRef, prevDepsRef);
+            for (const [idx, item] of items.entries()) {
+                const runnersForRule = runnersRef.current.get(rule);
+                if (!runnersForRule.has(idx)) {
+                    runnersForRule.set(idx, runnerFactory());
+                }
+                const deps = depsFn(item, idx);
+                const prev = prevDepsRef.current.get(rule).get(idx);
+                if (prev != null && !changed(deps, prev)) {
+                    continue;
+                }
+                prevDepsRef.current.get(rule).set(idx, deps);
+                const runner = runnersForRule.get(idx);
+                pendingCount.current++;
+                if (pendingCount.current === 1)
+                    setProcessing(true);
+                runner
+                    .run(ruleFn, item, (patch) => update(idx, patch), // intermediate: no touch
+                { index: idx })
+                    .then((result) => {
+                    if (result !== null) {
+                        update(idx, result);
+                    }
+                })
+                    .catch((err) => onError(err, rule, idx))
+                    .finally(() => {
+                    pendingCount.current--;
+                    if (pendingCount.current === 0)
+                        setProcessing(false);
+                });
+            }
+        }
+    }, [items]);
+    return { processing };
+};