yaxa-svelte 2.5.0 → 2.7.0

package/dist/client/index.js

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './client';
+export * from './query-cache.svelte';
+export * from './query.svelte';
+export * from './mutation.svelte';

package/dist/client/mutation.svelte.d.ts

@@ -0,0 +1,37 @@
+import type { ClientResponse, ProblemDetails } from './types';
+export type MutationFn<TData = any, TVariables = any> = (variables: TVariables) => Promise<ClientResponse<TData> | TData>;
+export interface CreateMutationOptions<TData = any, TVariables = any, TError = ProblemDetails | Error, TContext = unknown> {
+    /**
+     * Callback fired immediately before the mutation runs.
+     * Ideal for optimistic updates; returned context will be passed to onError and onSettled.
+     */
+    onMutate?: (variables: TVariables) => Promise<TContext> | TContext;
+    /**
+     * Callback fired when mutation succeeds.
+     */
+    onSuccess?: (data: TData, variables: TVariables, context: TContext | undefined) => Promise<void> | void;
+    /**
+     * Callback fired when mutation fails.
+     */
+    onError?: (error: TError, variables: TVariables, context: TContext | undefined) => Promise<void> | void;
+    /**
+     * Callback fired when mutation completes (either success or error).
+     */
+    onSettled?: (data: TData | null, error: TError | null, variables: TVariables, context: TContext | undefined) => Promise<void> | void;
+}
+export interface CreateMutationResult<TData = any, TVariables = any, TError = ProblemDetails | Error> {
+    readonly data: TData | null;
+    readonly error: TError | null;
+    readonly status: 'idle' | 'pending' | 'success' | 'error';
+    readonly isPending: boolean;
+    readonly isSuccess: boolean;
+    readonly isError: boolean;
+    readonly isIdle: boolean;
+    mutate: (variables: TVariables) => Promise<TData>;
+    reset: () => void;
+}
+/**
+ * Idiomatic Svelte 5 Runes Mutation Composable.
+ * Features optimistic rollbacks, lifecycle callbacks, and RFC 7807 problem details unwrapping.
+ */
+export declare function createMutation<TData = any, TVariables = void, TError = ProblemDetails | Error, TContext = unknown>(mutationFn: MutationFn<TData, TVariables>, options?: CreateMutationOptions<TData, TVariables, TError, TContext>): CreateMutationResult<TData, TVariables, TError>;

package/dist/client/mutation.svelte.js

@@ -0,0 +1,87 @@
+/**
+ * Checks if a response is a Yaxa ClientResponse.
+ */
+function isClientResponse(res) {
+    return (typeof res === 'object' &&
+        res !== null &&
+        'ok' in res &&
+        'status' in res &&
+        ('data' in res || 'error' in res));
+}
+/**
+ * Idiomatic Svelte 5 Runes Mutation Composable.
+ * Features optimistic rollbacks, lifecycle callbacks, and RFC 7807 problem details unwrapping.
+ */
+export function createMutation(mutationFn, options = {}) {
+    let data = $state(null);
+    let error = $state(null);
+    let status = $state('idle');
+    const isPending = $derived(status === 'pending');
+    const isSuccess = $derived(status === 'success');
+    const isError = $derived(status === 'error');
+    const isIdle = $derived(status === 'idle');
+    async function mutate(variables) {
+        status = 'pending';
+        error = null;
+        let context;
+        try {
+            if (options.onMutate) {
+                context = await options.onMutate(variables);
+            }
+            const result = await mutationFn(variables);
+            let finalData;
+            if (isClientResponse(result)) {
+                if (!result.ok) {
+                    throw result.error;
+                }
+                finalData = result.data;
+            }
+            else {
+                finalData = result;
+            }
+            data = finalData;
+            status = 'success';
+            await options.onSuccess?.(finalData, variables, context);
+            await options.onSettled?.(finalData, null, variables, context);
+            return finalData;
+        }
+        catch (err) {
+            const errPayload = err;
+            error = errPayload;
+            status = 'error';
+            await options.onError?.(errPayload, variables, context);
+            await options.onSettled?.(null, errPayload, variables, context);
+            throw err;
+        }
+    }
+    function reset() {
+        data = null;
+        error = null;
+        status = 'idle';
+    }
+    return {
+        get data() {
+            return data;
+        },
+        get error() {
+            return error;
+        },
+        get status() {
+            return status;
+        },
+        get isPending() {
+            return isPending;
+        },
+        get isSuccess() {
+            return isSuccess;
+        },
+        get isError() {
+            return isError;
+        },
+        get isIdle() {
+            return isIdle;
+        },
+        mutate,
+        reset
+    };
+}

package/dist/client/query-cache.svelte.d.ts

@@ -0,0 +1,51 @@
+import { SvelteSet } from 'svelte/reactivity';
+export type QueryKey = string | readonly unknown[];
+/**
+ * Deterministically serializes a QueryKey into a cache string.
+ */
+export declare function hashQueryKey(key: QueryKey): string;
+export type QueryStatus = 'idle' | 'loading' | 'success' | 'error';
+export interface QueryCacheEntry<TData = any, TError = any> {
+    readonly key: string;
+    data: TData | null;
+    error: TError | null;
+    status: QueryStatus;
+    isFetching: boolean;
+    updatedAt: number;
+    inFlightPromise: Promise<TData | null> | null;
+    subscribers: SvelteSet<() => void>;
+    invalidate: () => Promise<void>;
+}
+export interface InvalidateOptions {
+    key?: QueryKey;
+    exact?: boolean;
+}
+/**
+ * Runes-native Query Client managing cache entries, request coalescing,
+ * and real-time invalidation.
+ */
+export declare class QueryClient {
+    private entries;
+    /**
+     * Retrieves or initializes a cache entry for a given key string.
+     */
+    getOrCreateEntry<TData = any, TError = any>(keyHash: string, initialData?: TData): QueryCacheEntry<TData, TError>;
+    /**
+     * Retrieves current data for a query key from the cache.
+     */
+    getQueryData<TData = any>(key: QueryKey): TData | null;
+    /**
+     * Manually sets or optimistically updates data for a query key.
+     */
+    setQueryData<TData = any>(key: QueryKey, updater: TData | ((previous: TData | null) => TData)): TData;
+    /**
+     * Invalidates queries matching a key or filter, triggering active subscribers to refetch.
+     */
+    invalidateQueries(filter?: InvalidateOptions | QueryKey): Promise<void>;
+    /**
+     * Clears the cache completely.
+     */
+    clear(): void;
+}
+export declare function getQueryClient(): QueryClient;
+export declare function setQueryClient(client: QueryClient): void;

package/dist/client/query-cache.svelte.js

@@ -0,0 +1,172 @@
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+/**
+ * Deterministically serializes a QueryKey into a cache string.
+ */
+export function hashQueryKey(key) {
+    if (typeof key === 'string')
+        return key;
+    try {
+        return JSON.stringify(key, (_, val) => {
+            if (typeof val === 'object' && val !== null && !Array.isArray(val)) {
+                // Sort object keys deterministically
+                return Object.keys(val)
+                    .sort()
+                    .reduce((acc, k) => {
+                    acc[k] = val[k];
+                    return acc;
+                }, {});
+            }
+            return val;
+        });
+    }
+    catch {
+        return String(key);
+    }
+}
+/**
+ * Runes-native Query Client managing cache entries, request coalescing,
+ * and real-time invalidation.
+ */
+export class QueryClient {
+    entries = new SvelteMap();
+    /**
+     * Retrieves or initializes a cache entry for a given key string.
+     */
+    getOrCreateEntry(keyHash, initialData) {
+        const entry = this.entries.get(keyHash);
+        if (!entry) {
+            let data = $state(initialData !== undefined ? initialData : null);
+            let error = $state(null);
+            let status = $state(initialData !== undefined ? 'success' : 'idle');
+            let isFetching = $state(false);
+            let updatedAt = $state(initialData !== undefined ? Date.now() : 0);
+            const subscribers = new SvelteSet();
+            const newEntry = {
+                key: keyHash,
+                get data() {
+                    return data;
+                },
+                set data(val) {
+                    data = val;
+                },
+                get error() {
+                    return error;
+                },
+                set error(val) {
+                    error = val;
+                },
+                get status() {
+                    return status;
+                },
+                set status(val) {
+                    status = val;
+                },
+                get isFetching() {
+                    return isFetching;
+                },
+                set isFetching(val) {
+                    isFetching = val;
+                },
+                get updatedAt() {
+                    return updatedAt;
+                },
+                set updatedAt(val) {
+                    updatedAt = val;
+                },
+                inFlightPromise: null,
+                subscribers,
+                invalidate: async () => {
+                    for (const notify of Array.from(subscribers)) {
+                        try {
+                            notify();
+                        }
+                        catch {
+                            // Ignored
+                        }
+                    }
+                }
+            };
+            this.entries.set(keyHash, newEntry);
+            return newEntry;
+        }
+        // If entry exists but has no data and initialData was provided, populate it
+        if (entry.data === null && initialData !== undefined && entry.status === 'idle') {
+            entry.data = initialData;
+            entry.status = 'success';
+            entry.updatedAt = Date.now();
+        }
+        return entry;
+    }
+    /**
+     * Retrieves current data for a query key from the cache.
+     */
+    getQueryData(key) {
+        const hash = hashQueryKey(key);
+        const entry = this.entries.get(hash);
+        return entry ? entry.data : null;
+    }
+    /**
+     * Manually sets or optimistically updates data for a query key.
+     */
+    setQueryData(key, updater) {
+        const hash = hashQueryKey(key);
+        const entry = this.getOrCreateEntry(hash);
+        const nextData = typeof updater === 'function'
+            ? updater(entry.data)
+            : updater;
+        entry.data = nextData;
+        entry.error = null;
+        entry.status = 'success';
+        entry.updatedAt = Date.now();
+        return nextData;
+    }
+    /**
+     * Invalidates queries matching a key or filter, triggering active subscribers to refetch.
+     */
+    async invalidateQueries(filter) {
+        if (!filter) {
+            for (const entry of this.entries.values()) {
+                await entry.invalidate();
+            }
+            return;
+        }
+        const isKey = typeof filter === 'string' || Array.isArray(filter);
+        const key = isKey ? filter : filter.key;
+        const exact = isKey ? false : Boolean(filter.exact);
+        if (!key) {
+            for (const entry of this.entries.values()) {
+                await entry.invalidate();
+            }
+            return;
+        }
+        const targetHash = hashQueryKey(key);
+        for (const [hash, entry] of this.entries.entries()) {
+            if (exact) {
+                if (hash === targetHash) {
+                    await entry.invalidate();
+                }
+            }
+            else {
+                if (hash.startsWith(targetHash) || hash === targetHash) {
+                    await entry.invalidate();
+                }
+            }
+        }
+    }
+    /**
+     * Clears the cache completely.
+     */
+    clear() {
+        this.entries.clear();
+    }
+}
+/**
+ * Global default query client singleton.
+ */
+let globalClient = new QueryClient();
+export function getQueryClient() {
+    return globalClient;
+}
+export function setQueryClient(client) {
+    globalClient = client;
+}

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

@@ -0,0 +1,71 @@
+import { type QueryClient, type QueryKey, type QueryStatus } from './query-cache.svelte';
+import type { ClientResponse, ProblemDetails } from './types';
+import type { SSEResult } from '../composables/useSSE.svelte';
+export type QueryFn<TData = any> = () => Promise<ClientResponse<TData> | TData>;
+export interface CreateQueryOptions<TData = any, TError = ProblemDetails | Error> {
+    /**
+     * Explicit cache key or reactive key getter. If omitted, an auto-derived key is used.
+     */
+    key?: QueryKey | (() => QueryKey);
+    /**
+     * Whether the query should execute automatically (defaults to true).
+     * Can be a boolean or a reactive boolean getter: `() => !!userId`.
+     */
+    enabled?: boolean | (() => boolean);
+    /**
+     * Initial data (useful for SSR hydration to avoid loading flashes).
+     */
+    initialData?: TData;
+    /**
+     * Time in milliseconds before data is considered stale (defaults to 0).
+     */
+    staleTimeMs?: number;
+    /**
+     * Whether to refetch data when the browser window regains focus (defaults to true).
+     */
+    refetchOnWindowFocus?: boolean;
+    /**
+     * Whether to refetch data when network reconnects (defaults to true).
+     */
+    refetchOnReconnect?: boolean;
+    /**
+     * Custom query client instance (defaults to global client).
+     */
+    client?: QueryClient;
+    /**
+     * Server-Sent Events stream or channel for live real-time cache invalidation.
+     */
+    subscribeToSse?: string | {
+        sse?: SSEResult;
+        event?: string;
+    };
+    /**
+     * Callback on successful fetch.
+     */
+    onSuccess?: (data: TData) => void;
+    /**
+     * Callback on error.
+     */
+    onError?: (error: TError) => void;
+}
+export interface CreateQueryResult<TData = any, TError = ProblemDetails | Error> {
+    readonly data: TData | null;
+    readonly error: TError | null;
+    readonly status: QueryStatus;
+    readonly isLoading: boolean;
+    readonly isFetching: boolean;
+    readonly isSuccess: boolean;
+    readonly isError: boolean;
+    readonly updatedAt: number;
+    refetch: () => Promise<TData | null>;
+    invalidate: () => Promise<void>;
+    setData: (updater: TData | ((prev: TData | null) => TData)) => void;
+    optimisticUpdate: (updater: (prev: TData | null) => TData) => void;
+    destroy: () => void;
+}
+/**
+ * Idiomatic Svelte 5 Runes Query Composable.
+ * Features automatic dependency tracking, request coalescing, stale-while-revalidate,
+ * window focus revalidation, and SSE live invalidation.
+ */
+export declare function createQuery<TData = any, TError = ProblemDetails | Error>(keyOrFn: QueryKey | (() => QueryKey) | QueryFn<TData>, fnOrOptions?: QueryFn<TData> | CreateQueryOptions<TData, TError>, maybeOptions?: CreateQueryOptions<TData, TError>): CreateQueryResult<TData, TError>;

package/dist/client/query.svelte.js

@@ -0,0 +1,213 @@
+import { hashQueryKey, getQueryClient } from './query-cache.svelte';
+/**
+ * Checks if a response is a Yaxa ClientResponse.
+ */
+function isClientResponse(res) {
+    return (typeof res === 'object' &&
+        res !== null &&
+        'ok' in res &&
+        'status' in res &&
+        ('data' in res || 'error' in res));
+}
+/**
+ * Normalizes query key evaluation.
+ */
+function resolveKey(keyOrFn, fallback) {
+    if (typeof keyOrFn === 'function') {
+        return keyOrFn();
+    }
+    if (keyOrFn !== undefined) {
+        return keyOrFn;
+    }
+    return fallback || 'default-query-key';
+}
+/**
+ * Idiomatic Svelte 5 Runes Query Composable.
+ * Features automatic dependency tracking, request coalescing, stale-while-revalidate,
+ * window focus revalidation, and SSE live invalidation.
+ */
+export function createQuery(keyOrFn, fnOrOptions, maybeOptions) {
+    let keyConfig;
+    let queryFn;
+    let options;
+    if (typeof keyOrFn === 'function' && fnOrOptions && typeof fnOrOptions === 'function') {
+        // createQuery(keyFn, queryFn, options)
+        keyConfig = keyOrFn;
+        queryFn = fnOrOptions;
+        options = maybeOptions || {};
+    }
+    else if (typeof keyOrFn === 'function' && (!fnOrOptions || typeof fnOrOptions === 'object')) {
+        // createQuery(queryFn, options)
+        queryFn = keyOrFn;
+        options = fnOrOptions || {};
+        keyConfig = options.key;
+    }
+    else {
+        // createQuery(key, queryFn, options)
+        keyConfig = keyOrFn;
+        queryFn = fnOrOptions;
+        options = maybeOptions || {};
+    }
+    const client = options.client || getQueryClient();
+    const staleTimeMs = options.staleTimeMs ?? 0;
+    const refetchOnWindowFocus = options.refetchOnWindowFocus ?? true;
+    const refetchOnReconnect = options.refetchOnReconnect ?? true;
+    const fallbackKey = queryFn.toString();
+    const initialKey = resolveKey(keyConfig, fallbackKey);
+    const initialHash = hashQueryKey(initialKey);
+    // Pre-seed entry immediately on creation with initialData if provided
+    client.getOrCreateEntry(initialHash, options.initialData);
+    function getCurrentKey() {
+        return resolveKey(keyConfig, fallbackKey);
+    }
+    function getCurrentHash() {
+        return hashQueryKey(getCurrentKey());
+    }
+    function getIsEnabled() {
+        return typeof options.enabled === 'function'
+            ? options.enabled()
+            : options.enabled !== undefined
+                ? options.enabled
+                : true;
+    }
+    function getEntry() {
+        return client.getOrCreateEntry(getCurrentHash(), options.initialData);
+    }
+    async function executeFetch(force = false) {
+        if (!getIsEnabled())
+            return null;
+        const targetEntry = getEntry();
+        // 1. Check Stale Time if not forced
+        if (!force && targetEntry.updatedAt > 0) {
+            const age = Date.now() - targetEntry.updatedAt;
+            if (age < staleTimeMs && targetEntry.data !== null) {
+                return targetEntry.data;
+            }
+        }
+        // 2. Request Coalescing: Reuse in-flight Promise if already running
+        if (targetEntry.inFlightPromise) {
+            return targetEntry.inFlightPromise;
+        }
+        targetEntry.isFetching = true;
+        if (targetEntry.status === 'idle') {
+            targetEntry.status = 'loading';
+        }
+        const promise = (async () => {
+            try {
+                const result = await queryFn();
+                let finalData;
+                if (isClientResponse(result)) {
+                    if (!result.ok) {
+                        throw result.error;
+                    }
+                    finalData = result.data;
+                }
+                else {
+                    finalData = result;
+                }
+                targetEntry.data = finalData;
+                targetEntry.error = null;
+                targetEntry.status = 'success';
+                targetEntry.updatedAt = Date.now();
+                options.onSuccess?.(finalData);
+                return finalData;
+            }
+            catch (err) {
+                targetEntry.error = err;
+                targetEntry.status = 'error';
+                options.onError?.(err);
+                return null;
+            }
+            finally {
+                targetEntry.isFetching = false;
+                targetEntry.inFlightPromise = null;
+            }
+        })();
+        targetEntry.inFlightPromise = promise;
+        return promise;
+    }
+    // Subscriber notification callback
+    const subscriber = () => {
+        executeFetch(true);
+    };
+    const initialEntry = getEntry();
+    initialEntry.subscribers.add(subscriber);
+    // Initial execution if enabled and not already hydrated/fresh
+    if (getIsEnabled() && initialEntry.status === 'idle') {
+        executeFetch(false);
+    }
+    // Window listeners
+    let cleanupWindowListeners;
+    if (typeof window !== 'undefined') {
+        const onFocus = () => {
+            if (refetchOnWindowFocus && getIsEnabled()) {
+                executeFetch(false);
+            }
+        };
+        const onOnline = () => {
+            if (refetchOnReconnect && getIsEnabled()) {
+                executeFetch(true);
+            }
+        };
+        window.addEventListener('focus', onFocus);
+        window.addEventListener('online', onOnline);
+        cleanupWindowListeners = () => {
+            window.removeEventListener('focus', onFocus);
+            window.removeEventListener('online', onOnline);
+        };
+    }
+    // SSE Live-Invalidation Bridge
+    let cleanupSse;
+    if (options.subscribeToSse && typeof options.subscribeToSse === 'object') {
+        const sseOption = options.subscribeToSse;
+        if (sseOption.sse && sseOption.event) {
+            cleanupSse = sseOption.sse.on(sseOption.event, () => {
+                executeFetch(true);
+            });
+        }
+    }
+    function destroy() {
+        const currentEntry = getEntry();
+        currentEntry.subscribers.delete(subscriber);
+        cleanupWindowListeners?.();
+        cleanupSse?.();
+    }
+    return {
+        get data() {
+            return getEntry().data;
+        },
+        get error() {
+            return getEntry().error;
+        },
+        get status() {
+            return getEntry().status;
+        },
+        get isLoading() {
+            const e = getEntry();
+            return e.status === 'loading' && e.data === null;
+        },
+        get isFetching() {
+            return getEntry().isFetching;
+        },
+        get isSuccess() {
+            return getEntry().status === 'success';
+        },
+        get isError() {
+            return getEntry().status === 'error';
+        },
+        get updatedAt() {
+            return getEntry().updatedAt;
+        },
+        refetch: () => executeFetch(true),
+        invalidate: async () => {
+            await getEntry().invalidate();
+        },
+        setData: (updater) => {
+            client.setQueryData(getCurrentKey(), updater);
+        },
+        optimisticUpdate: (updater) => {
+            client.setQueryData(getCurrentKey(), updater);
+        },
+        destroy
+    };
+}

package/dist/client/query.test.d.ts

@@ -0,0 +1 @@
+export {};