@azure-net/kit 5.4.0 → 5.5.0

package/dist/svelte/async-signal/AsyncSignal.svelte.d.ts

@@ -23,6 +23,16 @@ export interface AsyncSignalSvelte<TData, TError = Error> {
     reset: () => void;
     abort: () => void;
 }
+export interface AsyncSignalBatchOptions {
+    parallel?: boolean;
+}
+export interface AsyncSignalBatchFactory {
+    <TData, TError = Error>(handler: (signal?: AbortSignal) => Promise<TData>, options?: Omit<AsyncSignalOptions<TData, TError>, 'immediate'>): AsyncSignalSvelte<TData, TError>;
+}
+export interface AsyncSignalBatch<TSignals extends readonly AsyncSignalSvelte<unknown, unknown>[]> {
+    execute: () => TSignals;
+}
 export declare const createAsyncSignal: <TData, TError = Error>(handler: (signal?: AbortSignal) => Promise<TData>, options?: AsyncSignalOptions<TData, TError>) => AsyncSignalSvelte<TData, TError>;
+export declare const createAsyncSignalBatch: <const TSignals extends readonly AsyncSignalSvelte<unknown, unknown>[]>(factory: (createSignal: AsyncSignalBatchFactory) => TSignals, options?: AsyncSignalBatchOptions) => AsyncSignalBatch<TSignals>;
 export declare const refreshAsyncSignal: (key: string) => Promise<void>;
 export declare const refreshAllAsyncSignals: () => Promise<void>;

package/dist/svelte/async-signal/AsyncSignal.svelte.js

@@ -1,5 +1,6 @@
 import { untrack } from 'svelte';
 import { BROWSER } from '../../external/tools/index.js';
+const ASYNC_SIGNAL_BATCH_INTERNAL = Symbol('async-signal-batch-internal');
 const createAsyncSignalManager = () => {
     const instances = BROWSER ? new Map() : undefined;
     const generateUid = () => {
@@ -56,6 +57,9 @@ export const createAsyncSignal = (handler, options = {}) => {
     let currentPromise = null;
     let currentRunId = 0;
     let started = false;
+    let batchLocked = false;
+    let batchGate = null;
+    let batchSkipRequested = false;
     const run = async (runId, source) => {
         const initial = !started;
         started = true;
@@ -117,7 +121,16 @@ export const createAsyncSignal = (handler, options = {}) => {
         currentPromise = localPromise;
         return localPromise;
     };
+    const startWhenUnlocked = (source) => {
+        if (batchLocked)
+            return batchGate ?? Promise.resolve(data);
+        return start(source);
+    };
     const execute = async () => {
+        if (batchLocked) {
+            await batchGate;
+            return;
+        }
         if (currentPromise) {
             await currentPromise;
             return;
@@ -125,11 +138,15 @@ export const createAsyncSignal = (handler, options = {}) => {
         await start('manual');
     };
     const refresh = async () => {
+        if (batchLocked) {
+            await batchGate;
+            return;
+        }
         await start('manual');
     };
     if (BROWSER) {
         const signalKey = key ?? asyncSignalManager.generateKey();
-        const callback = (source) => start(source);
+        const callback = (source) => startWhenUnlocked(source);
         asyncSignalManager.register(signalKey, callback);
         $effect(() => {
             return () => {
@@ -147,7 +164,7 @@ export const createAsyncSignal = (handler, options = {}) => {
             void start('auto');
         }
     }
-    return {
+    const asyncSignal = {
         get data() {
             return data;
         },
@@ -161,6 +178,8 @@ export const createAsyncSignal = (handler, options = {}) => {
             return pending;
         },
         get ready() {
+            if (batchLocked)
+                return (batchGate ?? Promise.resolve(data));
             if (currentPromise)
                 return currentPromise;
             return start('auto');
@@ -168,6 +187,8 @@ export const createAsyncSignal = (handler, options = {}) => {
         execute,
         refresh,
         reset: () => {
+            if (batchLocked)
+                batchSkipRequested = true;
             currentRunId += 1;
             abortController?.abort();
             abortController = null;
@@ -177,6 +198,8 @@ export const createAsyncSignal = (handler, options = {}) => {
             status = 'idle';
         },
         abort: () => {
+            if (batchLocked)
+                batchSkipRequested = true;
             currentRunId += 1;
             abortController?.abort();
             abortController = null;
@@ -185,6 +208,100 @@ export const createAsyncSignal = (handler, options = {}) => {
             status = 'idle';
         }
     };
+    Object.defineProperty(asyncSignal, ASYNC_SIGNAL_BATCH_INTERNAL, {
+        value: {
+            lock: (gate) => {
+                batchLocked = true;
+                batchGate = gate ?? null;
+                batchSkipRequested = false;
+            },
+            unlock: () => {
+                batchLocked = false;
+                batchGate = null;
+            },
+            start: (source) => {
+                if (batchSkipRequested)
+                    return Promise.resolve(undefined);
+                return start(source);
+            }
+        }
+    });
+    return asyncSignal;
+};
+const createDeferred = () => {
+    let resolve;
+    const promise = new Promise((promiseResolve) => {
+        resolve = promiseResolve;
+    });
+    return { promise, resolve };
+};
+export const createAsyncSignalBatch = (factory, options = {}) => {
+    const internals = new Map();
+    const createSignal = (handler, signalOptions = {}) => {
+        const signal = createAsyncSignal(handler, { ...signalOptions, immediate: false });
+        const internal = signal[ASYNC_SIGNAL_BATCH_INTERNAL];
+        internal.lock();
+        internals.set(signal, internal);
+        return signal;
+    };
+    const signals = factory(createSignal);
+    const uniqueSignals = new Set(signals);
+    if (uniqueSignals.size !== signals.length || signals.some((signal) => !internals.has(signal))) {
+        throw new Error('[AsyncSignalBatch] Factory must return each signal created by createSignal exactly once.');
+    }
+    if (internals.size !== signals.length) {
+        throw new Error('[AsyncSignalBatch] Factory must return every signal created by createSignal.');
+    }
+    let running = false;
+    const execute = () => {
+        if (running || signals.length === 0)
+            return signals;
+        running = true;
+        const gates = signals.map(() => createDeferred());
+        signals.forEach((signal, index) => {
+            internals.get(signal)?.lock(gates[index].promise);
+        });
+        queueMicrotask(() => {
+            if (options.parallel !== false) {
+                let remaining = signals.length;
+                signals.forEach((signal, index) => {
+                    const internal = internals.get(signal);
+                    void internal
+                        .start('manual')
+                        .catch(() => undefined)
+                        .then((result) => {
+                        gates[index].resolve(result);
+                        internal.unlock();
+                        remaining -= 1;
+                        if (remaining === 0)
+                            running = false;
+                    });
+                });
+                return;
+            }
+            void (async () => {
+                for (let index = 0; index < signals.length; index += 1) {
+                    const signal = signals[index];
+                    const internal = internals.get(signal);
+                    const result = await internal.start('manual').catch(() => undefined);
+                    gates[index].resolve(result);
+                    internal.unlock();
+                    if (signal.status !== 'success') {
+                        for (let skippedIndex = index + 1; skippedIndex < signals.length; skippedIndex += 1) {
+                            const skippedSignal = signals[skippedIndex];
+                            gates[skippedIndex].resolve(undefined);
+                            internals.get(skippedSignal)?.unlock();
+                        }
+                        break;
+                    }
+                }
+            })().finally(() => {
+                running = false;
+            });
+        });
+        return signals;
+    };
+    return { execute };
 };
 export const refreshAsyncSignal = async (key) => {
     return await asyncSignalManager.refreshByKey(key);

package/dist/svelte/effect/Effect.svelte.d.ts

@@ -0,0 +1,4 @@
+export type EffectCleanup = () => void;
+export type EffectCallback = () => EffectCleanup | Promise<unknown> | void;
+export type EffectDependency<T = unknown> = () => T;
+export declare const createEffect: (callback: EffectCallback, dependencies: readonly EffectDependency[]) => void;

package/dist/svelte/effect/Effect.svelte.js

@@ -0,0 +1,27 @@
+import { untrack } from 'svelte';
+export const createEffect = (callback, dependencies) => {
+    let cleanup;
+    let initialized = false;
+    let previousValues = [];
+    $effect(() => {
+        const values = dependencies.map((dependency) => dependency());
+        const changed = !initialized || values.some((value, index) => !Object.is(value, previousValues[index]));
+        if (!changed)
+            return;
+        initialized = true;
+        previousValues = values;
+        untrack(() => {
+            cleanup?.();
+            cleanup = undefined;
+            const result = callback();
+            if (typeof result === 'function')
+                cleanup = result;
+        });
+    });
+    $effect(() => {
+        return () => {
+            untrack(() => cleanup?.());
+            cleanup = undefined;
+        };
+    });
+};

package/dist/svelte/effect/index.d.ts

@@ -0,0 +1 @@
+export * from './Effect.svelte.js';

package/dist/svelte/effect/index.js

@@ -0,0 +1 @@
+export * from './Effect.svelte.js';

package/dist/svelte/index.d.ts

@@ -1,3 +1,4 @@
-export { createAsyncSignal, refreshAsyncSignal, refreshAllAsyncSignals, type AsyncSignalOptions, type AsyncSignalSvelte, type AsyncStatus, type AsyncSignalSource } from './async-signal/AsyncSignal.svelte.js';
+export { createAsyncSignal, createAsyncSignalBatch, refreshAsyncSignal, refreshAllAsyncSignals, type AsyncSignalBatch, type AsyncSignalBatchFactory, type AsyncSignalBatchOptions, type AsyncSignalOptions, type AsyncSignalSvelte, type AsyncStatus, type AsyncSignalSource } from './async-signal/AsyncSignal.svelte.js';
 export { createActiveForm, type ActiveForm, type ActiveFormCallbackContext, type ActiveFormController, type ActiveFormResponse, type ActiveFormStatus, type FormConfig, type InitialValuesHelpers, type LinkPromise, type LinkSignal, type LinkSignalOptions, type ResetBehaviors } from './active-form/ActiveForm.svelte.js';
-export { createQuery, type QueryController, type CreateQueryOptions } from './query/Query.svelte.js';
+export { createEffect, type EffectCallback, type EffectCleanup, type EffectDependency } from './effect/Effect.svelte.js';
+export { createQuery, type CreateQueryOptions, type QueryController, type QueryPath, type QuerySearchParamsSync } from './query/Query.svelte.js';

package/dist/svelte/index.js

@@ -1,3 +1,4 @@
-export { createAsyncSignal, refreshAsyncSignal, refreshAllAsyncSignals } from './async-signal/AsyncSignal.svelte.js';
+export { createAsyncSignal, createAsyncSignalBatch, refreshAsyncSignal, refreshAllAsyncSignals } from './async-signal/AsyncSignal.svelte.js';
 export { createActiveForm } from './active-form/ActiveForm.svelte.js';
+export { createEffect } from './effect/Effect.svelte.js';
 export { createQuery } from './query/Query.svelte.js';

package/dist/svelte/query/Query.svelte.d.ts

@@ -1,20 +1,23 @@
-export interface QueryOnChangeContext<T extends Record<string, unknown>> {
-    snapshot: T;
-    changedKeys: (keyof T)[];
-    signal: AbortSignal;
-}
-export interface QueryOnChangeOptions<T extends Record<string, unknown>> {
-    include: (keyof T)[];
-    handler: (ctx: QueryOnChangeContext<T>) => Promise<void> | void;
+import { type EffectCallback } from '../effect/Effect.svelte.js';
+type QueryPathDepth = readonly [unknown, unknown, unknown, unknown, unknown, unknown, unknown, unknown];
+type QueryLeaf = bigint | boolean | Date | File | Blob | ((...args: never[]) => unknown) | Map<unknown, unknown> | null | number | readonly unknown[] | RegExp | Set<unknown> | string | symbol | undefined | URL | URLSearchParams;
+export type QueryPath<T, Depth extends readonly unknown[] = QueryPathDepth> = Depth extends readonly [unknown, ...infer Rest] ? T extends QueryLeaf ? never : T extends object ? {
+    [K in Extract<keyof T, string>]: NonNullable<T[K]> extends QueryLeaf ? K : K | `${K}.${QueryPath<NonNullable<T[K]>, Rest>}`;
+}[Extract<keyof T, string>] : never : never;
+export interface QuerySearchParamsSync<T extends Record<string, unknown>> {
+    fromSearchParams?: (params: URLSearchParams, initial: Readonly<T>) => Partial<T>;
+    toSearchParams?: (data: Readonly<T>, initial: Readonly<T>) => URLSearchParams;
 }
 export interface CreateQueryOptions<T extends Record<string, unknown>> {
-    onChange?: QueryOnChangeOptions<T>;
+    syncWithSearchParams?: boolean | QuerySearchParamsSync<T>;
 }
 export interface QueryController<T extends Record<string, unknown>> {
     data: T;
     patch: (value: Partial<T>) => void;
     reset: () => void;
-    snapshot: () => T;
-    initial: () => T;
+    createSnapshot: () => T;
+    getInitial: () => T;
+    createEffect: (callback: EffectCallback, dependencies?: readonly QueryPath<T>[]) => void;
 }
 export declare const createQuery: <T extends Record<string, unknown>>(initialValue: T, options?: CreateQueryOptions<T>) => QueryController<T>;
+export {};

package/dist/svelte/query/Query.svelte.js

@@ -1,97 +1,106 @@
-import { untrack } from 'svelte';
-import { ObjectUtil } from '../../external/tools/index.js';
+import { replaceState } from '$app/navigation';
+import { page } from '$app/state';
+import { createEffect } from '../effect/Effect.svelte.js';
 import { cloneStateValue } from '../shared/cloneStateValue.js';
-const trackDeep = (value, seen = new WeakSet()) => {
-    if (value === null || typeof value !== 'object' || seen.has(value))
+import { fromSearchParams, toSearchParams } from './SearchParamsSync.js';
+const trackDeep = (value, seen) => {
+    if (value === null || typeof value !== 'object')
         return;
-    seen.add(value);
+    const visited = seen ?? new WeakSet();
+    if (visited.has(value))
+        return;
+    visited.add(value);
     if (Array.isArray(value)) {
         for (const item of value)
-            trackDeep(item, seen);
+            trackDeep(item, visited);
         return;
     }
     if (value instanceof Map) {
         for (const [key, item] of value) {
-            trackDeep(key, seen);
-            trackDeep(item, seen);
+            trackDeep(key, visited);
+            trackDeep(item, visited);
         }
         return;
     }
     if (value instanceof Set) {
         for (const item of value)
-            trackDeep(item, seen);
+            trackDeep(item, visited);
         return;
     }
     const prototype = Object.getPrototypeOf(value);
     if (prototype !== Object.prototype && prototype !== null)
         return;
-    for (const key of Reflect.ownKeys(value)) {
-        trackDeep(Reflect.get(value, key), seen);
+    for (const key of Reflect.ownKeys(value))
+        trackDeep(Reflect.get(value, key), visited);
+};
+const readPath = (source, path) => {
+    let value = source;
+    for (const key of path.split('.')) {
+        if (value === null || typeof value !== 'object')
+            return undefined;
+        value = Reflect.get(value, key);
     }
+    return value;
+};
+const createDeepDependency = (read) => {
+    let version = 0;
+    return () => {
+        const value = read();
+        if (value === null || typeof value !== 'object')
+            return value;
+        trackDeep(value);
+        return ++version;
+    };
 };
 export const createQuery = (initialValue, options) => {
     const baseInitial = cloneStateValue(initialValue);
-    let data = $state(cloneStateValue(baseInitial));
-    const includeKeys = [...new Set(options?.onChange?.include ?? [])];
-    const hasWatch = Boolean(options?.onChange?.handler) && includeKeys.length > 0;
-    const lastSnapshots = new Map();
-    let onChangeController = null;
-    let onChangeRunId = 0;
-    if (hasWatch) {
-        includeKeys.forEach((key) => {
-            lastSnapshots.set(key, cloneStateValue(data[key]));
-        });
-        $effect(() => {
-            const changedKeys = [];
-            includeKeys.forEach((key) => {
-                const nextValue = data[key];
-                trackDeep(nextValue);
-                const nextSnapshot = cloneStateValue(nextValue);
-                if (!ObjectUtil.equals(lastSnapshots.get(key), nextSnapshot)) {
-                    changedKeys.push(key);
-                    lastSnapshots.set(key, nextSnapshot);
-                }
-            });
-            if (!changedKeys.length)
-                return;
-            const previousController = onChangeController;
-            if (previousController)
-                previousController.abort();
-            const localController = new AbortController();
-            onChangeController = localController;
-            const localRunId = ++onChangeRunId;
-            const run = async () => {
-                await options.onChange.handler({
-                    changedKeys,
-                    signal: localController.signal,
-                    snapshot: cloneStateValue(data)
-                });
-            };
-            untrack(() => {
-                void run()
-                    .catch(() => undefined)
-                    .finally(() => {
-                    if (onChangeRunId === localRunId && onChangeController === localController) {
-                        onChangeController = null;
-                    }
-                });
-            });
-        });
-        $effect(() => {
-            return () => {
-                if (onChangeController)
-                    onChangeController.abort();
-            };
-        });
-    }
+    const searchParamsSync = options?.syncWithSearchParams;
+    const syncSettings = typeof searchParamsSync === 'object' ? searchParamsSync : undefined;
+    const syncEnabled = Boolean(searchParamsSync);
+    const parseSearchParams = syncSettings?.fromSearchParams ?? (fromSearchParams);
+    const serializeSearchParams = syncSettings?.toSearchParams ?? (toSearchParams);
+    const parsedInitial = syncEnabled ? parseSearchParams(new URLSearchParams(page.url.searchParams), cloneStateValue(baseInitial)) : undefined;
+    let data = $state(parsedInitial ? { ...cloneStateValue(baseInitial), ...cloneStateValue(parsedInitial) } : cloneStateValue(baseInitial));
     const reset = () => {
         data = cloneStateValue(baseInitial);
     };
     const patch = (value) => {
         data = { ...data, ...value };
     };
-    const snapshot = () => cloneStateValue(data);
-    const initial = () => cloneStateValue(baseInitial);
+    const createSnapshot = () => cloneStateValue(data);
+    const getInitial = () => cloneStateValue(baseInitial);
+    const createQueryEffect = (callback, dependencies) => {
+        const effectDependencies = dependencies === undefined
+            ? [createDeepDependency(() => data)]
+            : [...new Set(dependencies)].map((path) => createDeepDependency(() => readPath(data, path)));
+        createEffect(callback, effectDependencies);
+    };
+    if (syncEnabled) {
+        const managedKeys = new Set(Object.keys(baseInitial));
+        const captureInitialSyncedData = () => cloneStateValue(data);
+        const initialSyncedData = captureInitialSyncedData();
+        let initialized = false;
+        createEffect(() => {
+            const nextParams = serializeSearchParams(data, baseInitial);
+            for (const key of nextParams.keys())
+                managedKeys.add(key);
+            if (!initialized) {
+                initialized = true;
+                const initialParams = serializeSearchParams(initialSyncedData, baseInitial);
+                for (const key of initialParams.keys())
+                    managedKeys.add(key);
+                if (nextParams.toString() === initialParams.toString())
+                    return;
+            }
+            const url = new URL(page.url);
+            for (const key of managedKeys)
+                url.searchParams.delete(key);
+            for (const [key, value] of nextParams)
+                url.searchParams.append(key, value);
+            if (url.search !== page.url.search)
+                replaceState(url, page.state);
+        }, [createDeepDependency(() => data)]);
+    }
     return {
         get data() {
             return data;
@@ -101,7 +110,8 @@ export const createQuery = (initialValue, options) => {
         },
         patch,
         reset,
-        snapshot,
-        initial
+        createSnapshot,
+        getInitial,
+        createEffect: createQueryEffect
     };
 };

package/dist/svelte/query/SearchParamsSync.d.ts

@@ -0,0 +1,2 @@
+export declare const fromSearchParams: <T extends Record<string, unknown>>(params: URLSearchParams, initial: Readonly<T>) => Partial<T>;
+export declare const toSearchParams: <T extends Record<string, unknown>>(data: Readonly<T>) => URLSearchParams;

package/dist/svelte/query/SearchParamsSync.js

@@ -0,0 +1,119 @@
+const INVALID_VALUE = Symbol('invalid-query-search-param');
+const isPlainObject = (value) => {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+const parseScalar = (value, initial) => {
+    if (typeof initial === 'string')
+        return value;
+    if (typeof initial === 'number') {
+        if (!value.trim())
+            return INVALID_VALUE;
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : INVALID_VALUE;
+    }
+    if (typeof initial === 'boolean') {
+        const normalized = value.toLowerCase();
+        if (normalized === 'true' || normalized === '1')
+            return true;
+        if (normalized === 'false' || normalized === '0')
+            return false;
+        return INVALID_VALUE;
+    }
+    if (typeof initial === 'bigint') {
+        if (!value.trim())
+            return INVALID_VALUE;
+        try {
+            return BigInt(value);
+        }
+        catch {
+            return INVALID_VALUE;
+        }
+    }
+    if (initial instanceof Date) {
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.getTime()) ? INVALID_VALUE : parsed;
+    }
+    if (initial instanceof URL) {
+        try {
+            return new URL(value, initial);
+        }
+        catch {
+            return INVALID_VALUE;
+        }
+    }
+    if (initial instanceof URLSearchParams)
+        return new URLSearchParams(value);
+    if (isPlainObject(initial)) {
+        try {
+            const parsed = JSON.parse(value);
+            return isPlainObject(parsed) ? parsed : INVALID_VALUE;
+        }
+        catch {
+            return INVALID_VALUE;
+        }
+    }
+    return INVALID_VALUE;
+};
+const parseValue = (params, key, initial) => {
+    if (Array.isArray(initial)) {
+        const values = params.getAll(key);
+        if (!values.length)
+            return INVALID_VALUE;
+        if (!initial.length)
+            return values;
+        const parsed = values.map((value) => parseScalar(value, initial[0]));
+        return parsed.some((value) => value === INVALID_VALUE) ? INVALID_VALUE : parsed;
+    }
+    const value = params.get(key);
+    return value === null ? INVALID_VALUE : parseScalar(value, initial);
+};
+const serializeScalar = (value) => {
+    if (typeof value === 'string' || typeof value === 'boolean' || typeof value === 'bigint')
+        return String(value);
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? String(value) : undefined;
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? undefined : value.toISOString();
+    if (value instanceof URL || value instanceof URLSearchParams)
+        return value.toString();
+    if (isPlainObject(value)) {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+};
+export const fromSearchParams = (params, initial) => {
+    const result = {};
+    for (const key of Object.keys(initial)) {
+        if (!params.has(key))
+            continue;
+        const parsed = parseValue(params, key, initial[key]);
+        if (parsed !== INVALID_VALUE)
+            Reflect.set(result, key, parsed);
+    }
+    return result;
+};
+export const toSearchParams = (data) => {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(data)) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                const serialized = serializeScalar(item);
+                if (serialized !== undefined)
+                    params.append(key, serialized);
+            }
+            continue;
+        }
+        const serialized = serializeScalar(value);
+        if (serialized !== undefined)
+            params.set(key, serialized);
+    }
+    return params;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-net/kit",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "license": "MIT",
   "author": "Pixel1917",
   "description": "Universal toolkit and library collection, developed as part of the Azure-net ecosystem",