yaxa-svelte 2.6.0 → 2.8.0

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 {};

package/dist/client/query.test.js

@@ -0,0 +1,242 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { hashQueryKey, QueryClient, createQuery, createMutation, setQueryClient } from './index';
+describe('Runes Query Engine - hashQueryKey', () => {
+    it('returns string keys as-is', () => {
+        expect(hashQueryKey('projects')).toBe('projects');
+        expect(hashQueryKey('/api/items')).toBe('/api/items');
+    });
+    it('deterministically hashes arrays and nested objects regardless of key order', () => {
+        const keyA = ['projects', { orgId: '123', status: 'active' }];
+        const keyB = ['projects', { status: 'active', orgId: '123' }];
+        expect(hashQueryKey(keyA)).toBe(hashQueryKey(keyB));
+    });
+});
+describe('Runes Query Engine - QueryClient', () => {
+    let client;
+    beforeEach(() => {
+        client = new QueryClient();
+        setQueryClient(client);
+    });
+    it('creates, retrieves, and updates query cache entries', () => {
+        expect(client.getQueryData('users')).toBeNull();
+        client.setQueryData('users', [{ id: '1', name: 'Alice' }]);
+        expect(client.getQueryData('users')).toEqual([{ id: '1', name: 'Alice' }]);
+        // Functional updater
+        client.setQueryData('users', (prev) => [
+            ...(prev ?? []),
+            { id: '2', name: 'Bob' }
+        ]);
+        expect(client.getQueryData('users')).toHaveLength(2);
+    });
+    it('invalidates matching queries with exact and prefix filters', async () => {
+        const entry1 = client.getOrCreateEntry('projects-list');
+        const entry2 = client.getOrCreateEntry('projects-detail-1');
+        const entry3 = client.getOrCreateEntry('users');
+        const listener1 = vi.fn();
+        const listener2 = vi.fn();
+        const listener3 = vi.fn();
+        entry1.subscribers.add(listener1);
+        entry2.subscribers.add(listener2);
+        entry3.subscribers.add(listener3);
+        // Invalidate all projects
+        await client.invalidateQueries('projects');
+        expect(listener1).toHaveBeenCalledTimes(1);
+        expect(listener2).toHaveBeenCalledTimes(1);
+        expect(listener3).not.toHaveBeenCalled();
+        // Exact invalidation
+        await client.invalidateQueries({ key: 'projects-list', exact: true });
+        expect(listener1).toHaveBeenCalledTimes(2);
+        expect(listener2).toHaveBeenCalledTimes(1);
+    });
+});
+describe('Runes Query Engine - createQuery', () => {
+    let client;
+    beforeEach(() => {
+        client = new QueryClient();
+        setQueryClient(client);
+    });
+    it('fetches data and unwraps ClientResponse successfully', async () => {
+        const fetchMock = vi.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            data: [{ id: 'proj_1', name: 'Alpha' }],
+            error: null,
+            response: new Response()
+        });
+        const query = createQuery('test-projects', fetchMock, { client });
+        expect(query.isLoading).toBe(true);
+        expect(query.data).toBeNull();
+        const result = await query.refetch();
+        expect(result).toEqual([{ id: 'proj_1', name: 'Alpha' }]);
+        expect(query.data).toEqual([{ id: 'proj_1', name: 'Alpha' }]);
+        expect(query.isSuccess).toBe(true);
+        expect(query.isLoading).toBe(false);
+        expect(query.isError).toBe(false);
+    });
+    it('handles ClientResponse errors and RFC 7807 problem details', async () => {
+        const errorResponse = {
+            ok: false,
+            status: 404,
+            data: null,
+            error: {
+                type: 'https://yaxa.dev/errors/not-found',
+                title: 'Project Not Found',
+                status: 404,
+                detail: 'No project with ID 999 exists'
+            },
+            response: new Response(null, { status: 404 })
+        };
+        const fetchMock = vi.fn().mockResolvedValue(errorResponse);
+        const onError = vi.fn();
+        const query = createQuery('not-found-query', fetchMock, { client, onError });
+        await query.refetch();
+        expect(query.data).toBeNull();
+        expect(query.isError).toBe(true);
+        expect(query.error).toEqual(errorResponse.error);
+        expect(onError).toHaveBeenCalledWith(errorResponse.error);
+    });
+    it('coalesces multiple in-flight concurrent requests to the same key', async () => {
+        let resolveCall = () => { };
+        const fetchMock = vi.fn().mockImplementation(() => new Promise((res) => {
+            resolveCall = res;
+        }));
+        const query1 = createQuery('shared-key', fetchMock, { client });
+        const query2 = createQuery('shared-key', fetchMock, { client });
+        // Trigger both simultaneously
+        const p1 = query1.refetch();
+        const p2 = query2.refetch();
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        resolveCall({
+            ok: true,
+            status: 200,
+            data: { result: 'shared' },
+            error: null,
+            response: new Response()
+        });
+        const [res1, res2] = await Promise.all([p1, p2]);
+        expect(res1).toEqual({ result: 'shared' });
+        expect(res2).toEqual({ result: 'shared' });
+    });
+    it('respects staleTimeMs and avoids refetching when cache is fresh', async () => {
+        const fetchMock = vi.fn().mockResolvedValue('data-1');
+        const query = createQuery('stale-key', fetchMock, {
+            client,
+            staleTimeMs: 10_000
+        });
+        await query.refetch();
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        // Non-forced fetch should return cached data because staleTimeMs hasn't elapsed
+        client.getOrCreateEntry('stale-key').updatedAt = Date.now();
+        const entry = client.getOrCreateEntry('stale-key');
+        expect(entry.data).toBe('data-1');
+    });
+    it('hydrates with initialData with zero loading state', () => {
+        const query = createQuery('ssr-key', async () => 'fetched', {
+            client,
+            initialData: 'preloaded'
+        });
+        expect(query.data).toBe('preloaded');
+        expect(query.isLoading).toBe(false);
+        expect(query.isSuccess).toBe(true);
+    });
+    it('supports optimisticUpdate and setData', () => {
+        const query = createQuery('list-key', async () => ['item1'], {
+            client,
+            initialData: ['item1']
+        });
+        query.optimisticUpdate((prev) => [...(prev ?? []), 'item2']);
+        expect(query.data).toEqual(['item1', 'item2']);
+        query.setData(['item-override']);
+        expect(query.data).toEqual(['item-override']);
+    });
+    it('respects enabled: false and skips automatic fetching', async () => {
+        const fetchMock = vi.fn().mockResolvedValue('data');
+        const query = createQuery('disabled-key', fetchMock, {
+            client,
+            enabled: false
+        });
+        const res = await query.refetch();
+        expect(res).toBeNull();
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+    it('supports live invalidation via subscribeToSse', async () => {
+        const mockSse = {
+            on: vi.fn((_event, handler) => {
+                // Save handler
+                mockSse.trigger = handler;
+                return () => { };
+            })
+        };
+        const fetchMock = vi.fn().mockResolvedValue('sse-data');
+        createQuery('sse-query', fetchMock, {
+            client,
+            subscribeToSse: {
+                sse: mockSse,
+                event: 'project.updated'
+            }
+        });
+        expect(mockSse.on).toBeDefined();
+    });
+});
+describe('Runes Query Engine - createMutation', () => {
+    it('executes successful mutation and runs lifecycle hooks', async () => {
+        const onMutate = vi.fn().mockReturnValue({ tempId: 'temp_123' });
+        const onSuccess = vi.fn();
+        const onSettled = vi.fn();
+        const mutationFn = vi.fn().mockResolvedValue({
+            ok: true,
+            status: 201,
+            data: { id: 'real_123', name: 'Created' },
+            error: null,
+            response: new Response(null, { status: 201 })
+        });
+        const mutation = createMutation(mutationFn, {
+            onMutate,
+            onSuccess,
+            onSettled
+        });
+        expect(mutation.isIdle).toBe(true);
+        const promise = mutation.mutate({ name: 'Created' });
+        expect(mutation.isPending).toBe(true);
+        const result = await promise;
+        expect(result).toEqual({ id: 'real_123', name: 'Created' });
+        expect(mutation.data).toEqual({ id: 'real_123', name: 'Created' });
+        expect(mutation.isSuccess).toBe(true);
+        expect(mutation.isPending).toBe(false);
+        expect(onMutate).toHaveBeenCalledWith({ name: 'Created' });
+        expect(onSuccess).toHaveBeenCalledWith({ id: 'real_123', name: 'Created' }, { name: 'Created' }, { tempId: 'temp_123' });
+        expect(onSettled).toHaveBeenCalledWith({ id: 'real_123', name: 'Created' }, null, { name: 'Created' }, { tempId: 'temp_123' });
+    });
+    it('handles mutation errors, passes context for rollback, and re-throws', async () => {
+        const rollbackContext = { previousList: ['item1'] };
+        const onMutate = vi.fn().mockReturnValue(rollbackContext);
+        const onError = vi.fn();
+        const onSettled = vi.fn();
+        const errorResponse = {
+            ok: false,
+            status: 400,
+            data: null,
+            error: {
+                type: 'https://yaxa.dev/errors/validation',
+                title: 'Bad Request',
+                status: 400,
+                detail: 'Name must be at least 3 characters'
+            },
+            response: new Response(null, { status: 400 })
+        };
+        const mutation = createMutation(async () => errorResponse, {
+            onMutate,
+            onError,
+            onSettled
+        });
+        await expect(mutation.mutate(undefined)).rejects.toEqual(errorResponse.error);
+        expect(mutation.isError).toBe(true);
+        expect(mutation.error).toEqual(errorResponse.error);
+        expect(onError).toHaveBeenCalledWith(errorResponse.error, undefined, rollbackContext);
+        expect(onSettled).toHaveBeenCalledWith(null, errorResponse.error, undefined, rollbackContext);
+        mutation.reset();
+        expect(mutation.isIdle).toBe(true);
+        expect(mutation.error).toBeNull();
+        expect(mutation.data).toBeNull();
+    });
+});

package/dist/components/ai/ai.test.js

@@ -1,13 +1,80 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi, afterEach } from 'vitest';
 import AiChat from './AiChat.svelte';
 import PromptBar from './PromptBar.svelte';
 import AiThought from './AiThought.svelte';
 import AiToolCall from './AiToolCall.svelte';
+import { useAiChat } from './useAiChat.svelte';
 describe('AI-Native Components', () => {
     it('should export all AI component definitions', () => {
         expect(AiChat).toBeDefined();
         expect(PromptBar).toBeDefined();
         expect(AiThought).toBeDefined();
         expect(AiToolCall).toBeDefined();
+        expect(typeof useAiChat).toBe('function');
+    });
+});
+describe('useAiChat Runes Composable', () => {
+    const originalFetch = globalThis.fetch;
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+    it('initializes with default and initial messages', () => {
+        const chat = useAiChat({
+            initialMessages: [{ id: 'init-1', role: 'user', content: 'Initial message' }]
+        });
+        expect(chat.messages).toHaveLength(1);
+        expect(chat.messages[0].content).toBe('Initial message');
+        expect(chat.input).toBe('');
+        expect(chat.loading).toBe(false);
+        expect(chat.error).toBeNull();
+    });
+    it('streams SSE text deltas and thoughts progressively into assistant message', async () => {
+        const encoder = new TextEncoder();
+        const stream = new ReadableStream({
+            start(controller) {
+                controller.enqueue(encoder.encode('data: {"type":"thought","thought":{"running":true,"text":"Analyzing..."}}\n\n'));
+                controller.enqueue(encoder.encode('data: {"type":"text","delta":"Hello "}\n\n'));
+                controller.enqueue(encoder.encode('data: {"type":"text","delta":"World!"}\n\n'));
+                controller.enqueue(encoder.encode('data: {"type":"done"}\n\n'));
+                controller.close();
+            }
+        });
+        globalThis.fetch = vi.fn().mockResolvedValue(new Response(stream, {
+            headers: { 'Content-Type': 'text/event-stream' }
+        }));
+        const chat = useAiChat();
+        chat.input = 'Say hello';
+        await chat.send();
+        expect(chat.messages).toHaveLength(2);
+        expect(chat.messages[0].role).toBe('user');
+        expect(chat.messages[0].content).toBe('Say hello');
+        expect(chat.messages[1].role).toBe('assistant');
+        expect(chat.messages[1].content).toBe('Hello World!');
+        expect(chat.messages[1].thought?.text).toBe('Analyzing...');
+        expect(chat.messages[1].isStreaming).toBe(false);
+        expect(chat.loading).toBe(false);
+        expect(chat.error).toBeNull();
+    });
+    it('handles retries and message clearing', async () => {
+        const encoder = new TextEncoder();
+        const mockResponse = () => new Response(new ReadableStream({
+            start(controller) {
+                controller.enqueue(encoder.encode('data: {"type":"text","delta":"Response 1"}\n\n'));
+                controller.enqueue(encoder.encode('data: {"type":"done"}\n\n'));
+                controller.close();
+            }
+        }));
+        globalThis.fetch = vi.fn().mockImplementation(() => Promise.resolve(mockResponse()));
+        const chat = useAiChat();
+        await chat.send('Prompt 1');
+        expect(chat.messages).toHaveLength(2);
+        expect(chat.messages[1].content).toBe('Response 1');
+        // Retrying replaces the assistant answer
+        await chat.retry();
+        expect(chat.messages).toHaveLength(2);
+        expect(chat.messages[0].content).toBe('Prompt 1');
+        // Clear empties conversation
+        chat.clear();
+        expect(chat.messages).toHaveLength(0);
     });
 });

package/dist/components/ai/index.d.ts

@@ -6,3 +6,5 @@ export { default as AiThought } from './AiThought.svelte';
 export type { AiThoughtProps } from './AiThought.svelte';
 export { default as AiToolCall } from './AiToolCall.svelte';
 export type { AiToolCallProps, ToolCallStatus } from './AiToolCall.svelte';
+export { useAiChat } from './useAiChat.svelte';
+export type { UseAiChatOptions, UseAiChatReturn } from './useAiChat.svelte';

package/dist/components/ai/index.js

@@ -2,3 +2,4 @@ export { default as AiChat } from './AiChat.svelte';
 export { default as PromptBar } from './PromptBar.svelte';
 export { default as AiThought } from './AiThought.svelte';
 export { default as AiToolCall } from './AiToolCall.svelte';
+export { useAiChat } from './useAiChat.svelte';