@azure-net/kit 6.0.0-next.1 → 6.0.0-next.11

package/dist/shared/boundary-provider/Provider.js

@@ -1,4 +1,5 @@
-import { RequestContext } from '../../external/edges/ServerContext.js';
+import { getContextInternals } from '../../shared/request-context/Internal.js';
+import { RequestContext } from '../../shared/request-context/Internal.js';
 import { BROWSER } from '../../external/tools/index.js';
 import { AzureNetKitInternalError } from '../app-error/AppError.js';
 const clientCache = new Map();
@@ -14,30 +15,36 @@ const getProviderCache = (providerName) => {
     }
     else {
         const context = RequestContext.current();
-        if (!context.data.azureNetKitBoundaryProviders) {
-            context.data.azureNetKitBoundaryProviders = new Map();
+        if (!getContextInternals(context).azureNetKitBoundaryProviders) {
+            getContextInternals(context).azureNetKitBoundaryProviders = new Map();
         }
-        const providers = context.data.azureNetKitBoundaryProviders;
+        const providers = getContextInternals(context).azureNetKitBoundaryProviders;
         if (!providers.has(providerName)) {
             providers.set(providerName, new Map());
         }
-        if (!context.data.azureNetKitBoundaryProvidersToCleanup) {
-            context.data.azureNetKitBoundaryProvidersToCleanup = new Set();
+        if (!getContextInternals(context).azureNetKitBoundaryProvidersToCleanup) {
+            getContextInternals(context).azureNetKitBoundaryProvidersToCleanup = new Set();
         }
-        context.data.azureNetKitBoundaryProvidersToCleanup.add(providerName);
+        getContextInternals(context).azureNetKitBoundaryProvidersToCleanup.add(providerName);
         return providers.get(providerName);
     }
 };
+const getProxyCache = () => {
+    if (BROWSER)
+        return providerProxyCache;
+    const context = RequestContext.current();
+    return (getContextInternals(context).azureNetKitBoundaryProviderProxies ??= new Map());
+};
 const getBootFlag = (providerName) => {
     if (BROWSER) {
         return clientBootFlags.get(providerName) ?? false;
     }
     else {
         const context = RequestContext.current();
-        if (!context.data.bootFlags) {
-            context.data.bootFlags = new Map();
+        if (!getContextInternals(context).bootFlags) {
+            getContextInternals(context).bootFlags = new Map();
         }
-        const bootFlags = context.data.bootFlags;
+        const bootFlags = getContextInternals(context).bootFlags;
         return bootFlags.get(providerName) ?? false;
     }
 };
@@ -47,10 +54,10 @@ const setBootFlag = (providerName, value) => {
     }
     else {
         const context = RequestContext.current();
-        if (!context.data.bootFlags) {
-            context.data.bootFlags = new Map();
+        if (!getContextInternals(context).bootFlags) {
+            getContextInternals(context).bootFlags = new Map();
         }
-        const bootFlags = context.data.bootFlags;
+        const bootFlags = getContextInternals(context).bootFlags;
         bootFlags.set(providerName, value);
     }
 };
@@ -58,30 +65,32 @@ const getConstructionStack = () => {
     if (BROWSER)
         return clientConstructionStack;
     const context = RequestContext.current();
-    return (context.data.boundaryProviderConstructionStack ??= []);
+    return (getContextInternals(context).boundaryProviderConstructionStack ??= []);
 };
-const runWithCycleGuard = (key, callback) => {
+const runWithCycleGuard = (provider, member, callback) => {
     const stack = getConstructionStack();
-    if (stack.includes(key)) {
-        const cycleStart = stack.indexOf(key);
-        const cyclePath = [...stack.slice(cycleStart), key].join(' -> ');
+    const cycleStart = stack.findIndex((entry) => entry.provider === provider && entry.member === member);
+    const entry = { provider, member };
+    if (cycleStart !== -1) {
+        const cyclePath = [...stack.slice(cycleStart), entry].map(({ provider, member }) => `${String(provider)}.${member}`).join(' -> ');
         throw new AzureNetKitInternalError(`[BoundaryProvider] Circular provider dependency detected: ${cyclePath}`);
     }
-    stack.push(key);
+    stack.push(entry);
     try {
         return callback();
     }
     finally {
-        const idx = stack.lastIndexOf(key);
+        const idx = stack.lastIndexOf(entry);
         if (idx !== -1)
             stack.splice(idx, 1);
     }
 };
-export const createBoundaryProvider = (name, settings) => {
+export const CreateServiceContainer = (name, settings) => {
     const { dependsOn = {}, boot, register } = settings;
     const providerFn = () => {
-        if (BROWSER && providerProxyCache.has(name)) {
-            return providerProxyCache.get(name);
+        const proxies = getProxyCache();
+        if (proxies.has(name)) {
+            return proxies.get(name);
         }
         const cache = getProviderCache(name);
         let factories = null;
@@ -101,7 +110,7 @@ export const createBoundaryProvider = (name, settings) => {
                     }
                 });
             }
-            factories = register(deps);
+            factories = runWithCycleGuard(name, 'register', () => register(deps));
             return factories;
         };
         const providerProxy = new Proxy({}, {
@@ -117,15 +126,15 @@ export const createBoundaryProvider = (name, settings) => {
                         return undefined;
                     if (Reflect.has(target, key))
                         return Reflect.get(target, key, receiver);
-                    throw new AzureNetKitInternalError(`[BoundaryProvider] Service '${key}' not found in provider '${name}'`);
+                    throw new AzureNetKitInternalError(`[BoundaryProvider] Service '${key}' not found in provider '${String(name)}'`);
                 }
                 const factory = factories[key];
                 if (typeof factory !== 'function') {
                     throw new AzureNetKitInternalError('[BoundaryProvider] Factory must be a function');
                 }
-                const instance = runWithCycleGuard(`${name}.${key}`, () => factory());
+                const instance = runWithCycleGuard(name, key, () => factory());
                 if (instance && typeof instance?.then === 'function') {
-                    throw new AzureNetKitInternalError(`[BoundaryProvider] Service '${key}' in provider '${name}' returned Promise.`);
+                    throw new AzureNetKitInternalError(`[BoundaryProvider] Service '${key}' in provider '${String(name)}' returned Promise.`);
                 }
                 cache.set(key, instance);
                 return instance;
@@ -157,17 +166,21 @@ export const createBoundaryProvider = (name, settings) => {
                 };
             }
         });
-        if (BROWSER) {
-            providerProxyCache.set(name, providerProxy);
-        }
-        if (boot && !getBootFlag(name)) {
-            getFactories();
-            const bootResult = boot(providerProxy);
-            if (bootResult && typeof bootResult.then === 'function') {
-                void Promise.resolve(bootResult).catch(() => undefined);
-                throw new AzureNetKitInternalError(`[BoundaryProvider] Boot for provider '${name}' must be synchronous.`);
+        proxies.set(name, providerProxy);
+        try {
+            if (boot && !getBootFlag(name)) {
+                getFactories();
+                const bootResult = boot(providerProxy);
+                if (bootResult && typeof bootResult.then === 'function') {
+                    void Promise.resolve(bootResult).catch(() => undefined);
+                    throw new AzureNetKitInternalError(`[BoundaryProvider] Boot for provider '${String(name)}' must be synchronous.`);
+                }
+                setBootFlag(name, true);
             }
-            setBootFlag(name, true);
+        }
+        catch (error) {
+            proxies.delete(name);
+            throw error;
         }
         return providerProxy;
     };
@@ -180,10 +193,10 @@ export async function cleanupProvider(name) {
             if (service && typeof service === 'object' && 'dispose' in service) {
                 try {
                     const disposeResult = service.dispose();
-                    promises.push(Promise.resolve(disposeResult).catch((err) => console.error(`Error disposing ${name}.${key}:`, err)));
+                    promises.push(Promise.resolve(disposeResult).catch((err) => console.error(`Error disposing ${String(name)}.${key}:`, err)));
                 }
                 catch (err) {
-                    console.error(`Error disposing ${name}.${key}:`, err);
+                    console.error(`Error disposing ${String(name)}.${key}:`, err);
                 }
             }
         }
@@ -200,7 +213,10 @@ export async function cleanupProvider(name) {
     }
     else {
         const context = RequestContext.current();
-        const providers = context.data.azureNetKitBoundaryProviders;
+        const providers = getContextInternals(context).azureNetKitBoundaryProviders;
+        getProxyCache().delete(name);
+        setBootFlag(name, false);
+        getContextInternals(context).azureNetKitBoundaryProvidersToCleanup?.delete(name);
         if (providers?.has(name)) {
             const cache = providers.get(name);
             providers.delete(name);

package/dist/shared/boundary-provider/index.d.ts

@@ -1 +1,2 @@
 export * from './Provider.js';
+export { CompositionRoot, type CompositionRootSettings } from './CompositionRoot.js';

package/dist/shared/boundary-provider/index.js

@@ -1 +1,2 @@
 export * from './Provider.js';
+export { CompositionRoot } from './CompositionRoot.js';

package/dist/shared/cookie/UniversalCookie.js

@@ -1,5 +1,5 @@
 import { BROWSER, Cookies } from '../../external/tools/index.js';
-import { RequestContext } from '../../external/edges/ServerContext.js';
+import { RequestContext } from '../../shared/request-context/Internal.js';
 const cloneCookieOptions = (options) => ({
     ...options,
     expires: options.expires instanceof Date ? new Date(options.expires) : options.expires

package/dist/shared/index.d.ts

@@ -1,8 +1,7 @@
 export { UniversalCookie, UniversalCookieInstance, UniversalNamedCookieInstance, type CookieOptions } from './cookie/index.js';
 export { BackgroundTask } from './background-task/index.js';
-export { AppEvents } from './event-bus/index.js';
 export { ClassMirror } from './class-mirror/index.js';
-export { createBoundaryProvider, cleanupProvider, type ProviderSettings } from './boundary-provider/index.js';
+export { CreateServiceContainer, cleanupProvider, type ProviderSettings, type ProviderKey } from './boundary-provider/index.js';
+export { CompositionRoot, type CompositionRootSettings } from './boundary-provider/index.js';
 export * from './app/index.js';
 export { useLogger, LoggerErrors, type ILoggerError, type ILoggerSettings } from './logger/index.js';
-export { useRedirect, type IRedirectSettings, type RedirectStatus } from './redirect/index.js';

package/dist/shared/index.js

@@ -1,8 +1,7 @@
 export { UniversalCookie, UniversalCookieInstance, UniversalNamedCookieInstance } from './cookie/index.js';
 export { BackgroundTask } from './background-task/index.js';
-export { AppEvents } from './event-bus/index.js';
 export { ClassMirror } from './class-mirror/index.js';
-export { createBoundaryProvider, cleanupProvider } from './boundary-provider/index.js';
+export { CreateServiceContainer, cleanupProvider } from './boundary-provider/index.js';
+export { CompositionRoot } from './boundary-provider/index.js';
 export * from './app/index.js';
 export { useLogger, LoggerErrors } from './logger/index.js';
-export { useRedirect } from './redirect/index.js';

package/dist/shared/logger/index.js

@@ -1,6 +1,6 @@
 import { AppError, AzureNetKitInternalError } from '../app-error/index.js';
 import { BROWSER } from '../../external/tools/index.js';
-import { RequestContext } from '../../external/edges/ServerContext.js';
+import { RequestContext } from '../../shared/request-context/Internal.js';
 import { BackgroundTask } from '../background-task/index.js';
 export var LoggerErrors;
 (function (LoggerErrors) {

package/dist/shared/request-context/Internal.d.ts

@@ -0,0 +1,16 @@
+import type { RequestEvent } from '@sveltejs/kit';
+declare global {
+    namespace App {
+        interface RequestContextState {
+        }
+    }
+}
+export interface ContextData {
+    readonly event: RequestEvent;
+    readonly state: App.RequestContextState;
+}
+export declare function initializeRequestContext(resolve: () => ContextData | undefined): void;
+export declare function getContextInternals(context: ContextData): Record<PropertyKey, unknown>;
+export declare const RequestContext: Readonly<{
+    current(): ContextData;
+}>;

package/dist/shared/request-context/Internal.js

@@ -0,0 +1,24 @@
+import { BROWSER } from '../../external/tools/index.js';
+let getter;
+const internals = new WeakMap();
+export function initializeRequestContext(resolve) {
+    getter = resolve;
+}
+export function getContextInternals(context) {
+    let data = internals.get(context);
+    if (!data) {
+        data = {};
+        internals.set(context, data);
+    }
+    return data;
+}
+export const RequestContext = Object.freeze({
+    current() {
+        if (BROWSER)
+            throw new Error('[AzureNetKit] RequestContext is server-only.');
+        const context = getter?.();
+        if (!context)
+            throw new Error('[AzureNetKit] No active RequestContext. Use AzureNetPlugin and resolve services inside a request.');
+        return context;
+    }
+});

package/dist/shared/request-context/index.d.ts

@@ -0,0 +1 @@
+export { RequestContext, type ContextData } from './Internal.js';

package/dist/shared/request-context/index.js

@@ -0,0 +1,2 @@
+// Safe to import from universal program.ts; current() rejects browser calls.
+export { RequestContext } from './Internal.js';

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

@@ -1,7 +1,6 @@
 export type AsyncStatus = 'idle' | 'pending' | 'success' | 'error';
 export type AsyncSignalSource = 'auto' | 'manual' | 'global';
-export interface AsyncSignalOptions<TData, TError = Error> {
-    server?: boolean;
+interface AsyncSignalBaseOptions<TData, TError = Error> {
     immediate?: boolean;
     initialData?: TData | (() => TData);
     beforeSend?: (meta: {
@@ -12,6 +11,15 @@ export interface AsyncSignalOptions<TData, TError = Error> {
     onError?: (error: TError) => void | Promise<void>;
     key?: string;
 }
+export type AsyncSignalOptions<TData, TError = Error> = AsyncSignalBaseOptions<TData, TError> & ({
+    server: true;
+    key: string;
+} | {
+    server?: false;
+});
+type AsyncSignalBatchSignalOptions<TData, TError> = Omit<AsyncSignalBaseOptions<TData, TError>, 'immediate'> & {
+    server?: false;
+};
 export interface AsyncSignalSvelte<TData, TError = Error> {
     response?: TData;
     error?: TError;
@@ -27,13 +35,21 @@ 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>;
+    <TData, TError = Error>(handler: (signal?: AbortSignal) => Promise<TData>, options?: AsyncSignalBatchSignalOptions<TData, TError>): AsyncSignalSvelte<TData, TError>;
 }
 export interface AsyncSignalBatch<TSignals extends readonly AsyncSignalSvelte<unknown, unknown>[]> {
     execute: () => TSignals;
 }
 export declare const isAsyncSignalScheduledForClient: (signal: AsyncSignalSvelte<unknown, unknown>) => boolean;
-export declare const createAsyncSignal: <TData, TError = Error>(handler: (signal?: AbortSignal) => Promise<TData>, options?: AsyncSignalOptions<TData, TError>) => AsyncSignalSvelte<TData, TError>;
+export declare function createAsyncSignal<TData, TError = Error>(handler: (signal?: AbortSignal) => Promise<TData>, options: AsyncSignalBaseOptions<TData, TError> & {
+    server: true;
+    key: string;
+}): Promise<AsyncSignalSvelte<TData, TError>>;
+export declare function createAsyncSignal<TData, TError = Error>(handler: (signal?: AbortSignal) => Promise<TData>, options?: AsyncSignalBaseOptions<TData, TError> & {
+    server?: false;
+}): AsyncSignalSvelte<TData, TError>;
+export declare function createAsyncSignal<TData, TError = Error>(handler: (signal?: AbortSignal) => Promise<TData>, options: AsyncSignalOptions<TData, TError>): AsyncSignalSvelte<TData, TError> | Promise<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>;
+export {};

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

@@ -1,4 +1,4 @@
-import { untrack } from 'svelte';
+import { hydratable, untrack } from 'svelte';
 import { BROWSER } from '../../external/tools/index.js';
 const ASYNC_SIGNAL_BATCH_INTERNAL = Symbol('async-signal-batch-internal');
 const ASYNC_SIGNAL_SCHEDULED_FOR_CLIENT = Symbol('async-signal-scheduled-for-client');
@@ -60,7 +60,14 @@ const createAsyncSignalManager = () => {
     return { refreshAll, refreshByKey, generateKey, register, unregister };
 };
 const asyncSignalManager = createAsyncSignalManager();
-export const createAsyncSignal = (handler, options = {}) => {
+export function createAsyncSignal(handler, options = {}) {
+    if (options.server && (typeof options.key !== 'string' || !options.key.trim())) {
+        throw new Error('[AsyncSignal] server: true requires a stable, non-empty key.');
+    }
+    const signal = createAsyncSignalInstance(handler, options, options.server && options.immediate !== false ? options.key : undefined);
+    return options.server ? signal.ready.then(() => signal) : signal;
+}
+const createAsyncSignalInstance = (handler, options = {}, hydrationKey) => {
     const { server = false, immediate = true, initialData = undefined, key } = options;
     const resolvedInitialData = typeof initialData === 'function' ? initialData() : initialData;
     let scheduledForClient = immediate && !BROWSER && !server;
@@ -105,15 +112,43 @@ export const createAsyncSignal = (handler, options = {}) => {
         status = 'pending';
         error = undefined;
         try {
-            if (options.beforeSend) {
-                const beforeSendResult = options.beforeSend({ initial, source });
-                if (beforeSendResult && typeof beforeSendResult.then === 'function')
-                    await beforeSendResult;
+            const request = async () => {
+                if (options.beforeSend) {
+                    const beforeSendResult = options.beforeSend({ initial, source });
+                    if (beforeSendResult && typeof beforeSendResult.then === 'function')
+                        await beforeSendResult;
+                }
+                if (runId !== currentRunId || abortController !== localController || localController.signal.aborted) {
+                    return undefined;
+                }
+                return handler(localController.signal);
+            };
+            let result;
+            if (initial && hydrationKey !== undefined) {
+                let originalError;
+                // Call before yielding: hydratable needs the component's active render context.
+                const outcome = await hydratable(`@azure-net/kit/async-signal:${hydrationKey}`, async () => {
+                    try {
+                        return { ok: true, data: await request() };
+                    }
+                    catch (error) {
+                        originalError = { value: error };
+                        // Error instances are not devalue-serializable; do not expose server stacks.
+                        return error instanceof Error
+                            ? { ok: false, native: true, error: { name: error.name, message: error.message } }
+                            : { ok: false, native: false, error };
+                    }
+                });
+                if (!outcome.ok) {
+                    if (originalError)
+                        throw originalError.value;
+                    throw outcome.native ? Object.assign(new Error(outcome.error.message), { name: outcome.error.name }) : outcome.error;
+                }
+                result = outcome.data;
             }
-            if (runId !== currentRunId || abortController !== localController || localController.signal.aborted) {
-                return undefined;
+            else {
+                result = await request();
             }
-            const result = await handler(localController.signal);
             if (runId !== currentRunId || abortController !== localController || localController.signal.aborted) {
                 return undefined;
             }
@@ -183,21 +218,23 @@ export const createAsyncSignal = (handler, options = {}) => {
     if (BROWSER) {
         const signalKey = key ?? asyncSignalManager.generateKey();
         const callback = (source) => startWhenUnlocked(source);
-        asyncSignalManager.register(signalKey, callback);
         $effect(() => {
+            // Initialization may be abandoned before this effect can own the registration.
+            asyncSignalManager.register(signalKey, callback);
             return () => {
                 asyncSignalManager.unregister(signalKey, callback);
             };
         });
     }
     if (immediate) {
+        // Automatic runs have no caller to catch a rejected onError callback.
         if (!BROWSER && server) {
             untrack(() => {
-                void start('auto');
+                void start('auto').catch(() => undefined);
             });
         }
         else if (BROWSER) {
-            void start('auto');
+            void start('auto').catch(() => undefined);
         }
     }
     const asyncSignal = {
@@ -272,7 +309,10 @@ export const createAsyncSignal = (handler, options = {}) => {
 export const createAsyncSignalBatch = (factory, options = {}) => {
     const internals = new Map();
     const createSignal = (handler, signalOptions = {}) => {
-        const signal = createAsyncSignal(handler, { ...signalOptions, immediate: false });
+        if (signalOptions.server) {
+            throw new Error('[AsyncSignalBatch] server: true is not supported. Await createAsyncSignal during component initialization instead.');
+        }
+        const signal = createAsyncSignalInstance(handler, { ...signalOptions, immediate: false });
         const internal = signal[ASYNC_SIGNAL_BATCH_INTERNAL];
         internal.lock();
         internals.set(signal, internal);

package/dist/svelte/async-signal/README.md

@@ -0,0 +1,89 @@
+# AsyncSignal server hydration
+
+`createAsyncSignal(handler)` and `{ server: false }` return a signal synchronously,
+with the existing client-only automatic execution behavior. With `{ server: true }`,
+the return type is `Promise<AsyncSignalSvelte<T>>`; await it to obtain the settled
+initial signal on both the server and the browser.
+
+```svelte
+<script lang="ts">
+	import { createAsyncSignal } from '@azure-net/kit';
+
+	let { api } = $props<{
+		api: { getProfile(signal?: AbortSignal): Promise<{ name: string }> };
+	}>();
+
+	const profile = await createAsyncSignal((signal) => api.getProfile(signal), {
+		server: true,
+		key: 'profile:current-user'
+	});
+</script>
+
+<p>{profile.response?.name}</p>
+<button onclick={() => profile.refresh()}>Refresh</button>
+```
+
+Enable Svelte's `compilerOptions.experimental.async`. Call the factory during
+component initialization, directly in the component script as above, or through a
+synchronous helper called there. Do not first await inside an ordinary async helper,
+or create a server-hydratable signal in a module singleton, event handler, `onMount`,
+or `$effect`: Svelte needs the active component render context when `hydratable` is
+called. The request handler itself may await normally. Supply a handler that can run
+in both environments. In this example the parent supplies an API service created
+for the current SSR request, and independently creates its browser counterpart.
+Do not serialize the service through `load` data. Its server implementation must
+capture the current request's fetch/auth context, or use an absolute trusted API
+URL with explicitly scoped credentials. Global server `fetch('/api/profile')`
+cannot resolve a relative URL, and `credentials: 'include'` does not automatically
+forward the incoming user's cookies on the server. Forward only the credentials
+needed by a trusted destination; never put them in the hydration payload.
+
+The key must be non-empty, stable between SSR and hydration, and unique for each
+logically distinct request in a render (include parameters when relevant). The
+library namespaces it. Svelte owns the per-render payload; AsyncSignal does not add
+a shared server request cache. This does not make module-global services, mutable
+handler state, or publicly cached personalized HTML safe: the application must
+keep those request-scoped or otherwise isolate users.
+Data and non-Error rejection values must be serializable by
+Svelte's `hydratable`/devalue. Native errors transfer their name and message, not
+stack traces, subclasses, or custom properties. Do not return secrets or sensitive
+error messages: hydratable payloads are sent to the browser.
+
+Only the initial automatic request is hydratable. Hydration reuses its result
+without invoking the handler or `beforeSend`; `onSuccess`/`onError` run for the
+settled result in each environment, and `ready` waits for those callbacks. An
+initial request failure yields a signal with `status: 'error'`, as before, rather
+than rejecting the factory promise. Subsequent `execute`, `refresh`, and global
+refreshes use normal request, cancellation, callback, and ready-cycle behavior.
+`beforeSend` sees `initial: false` on a refresh after hydration.
+
+If `onSuccess` throws, the signal enters the error state and invokes `onError`,
+retaining the loaded response. If `onError` also throws, `ready` still settles;
+explicit `execute`/`refresh` reject with that callback error, while automatic
+initial loading consumes it to avoid an unhandled rejection. The signal's `error`
+retains the original request or success-callback failure. Hydratable signals join
+the browser global-refresh registry only when their component effect runs, so an
+initialization abandoned before mounting leaves no registry entry. Unmounting is
+not equivalent to calling `abort`: already-running handlers/callbacks may finish.
+
+`initialData` (or its synchronous factory) initializes `response` independently in
+each environment. It does not skip the automatic request or change an idle signal
+to success. With `server: true` and the default `immediate: true`, the factory still
+awaits initial loading; success replaces the fallback, while failure retains it.
+Only the request outcome is transferred, not `initialData`, so use matching fallback
+values on the server and browser to avoid hydration mismatches after a failure.
+
+`immediate: false` disables initial loading and hydration, including in server mode:
+`await createAsyncSignal(handler, { server: true, key: 'profile', immediate: false,
+initialData })` returns an idle signal whose `response` and resolved `ready` contain
+the initial value (or `undefined` if omitted). The key is still required. Later
+explicit execution is ordinary, non-hydratable work.
+
+Batch factories remain synchronous and deferred;
+`createAsyncSignalBatch` explicitly rejects `server: true` in its factory at both
+type-check and runtime. Use individually awaited server signals instead. Ordinary
+batches preserve locks, parallel/sequential execution, cancellation, and ready gates.
+
+Outside SvelteKit, include both `head` and `body` returned by `await render(...)` in
+the document: Svelte places the hydration payload in `head`. Configure a CSP nonce
+or hash through Svelte's render options if your application uses CSP.

package/dist/svelte/index.d.ts

@@ -2,3 +2,4 @@ export { createAsyncSignal, createAsyncSignalBatch, refreshAsyncSignal, refreshA
 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 { 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';
+export { useRedirect, type IRedirectSettings, type RedirectStatus } from './redirect/index.js';

package/dist/svelte/index.js

@@ -2,3 +2,4 @@ export { createAsyncSignal, createAsyncSignalBatch, refreshAsyncSignal, refreshA
 export { createActiveForm } from './active-form/ActiveForm.svelte.js';
 export { createEffect } from './effect/Effect.svelte.js';
 export { createQuery } from './query/Query.svelte.js';
+export { useRedirect } from './redirect/index.js';

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

@@ -19,5 +19,5 @@ export interface QueryController<T extends Record<string, unknown>> {
     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 declare const createQuery: <T extends Record<string, unknown>>(initialValue: T | (() => T), options?: CreateQueryOptions<T>) => QueryController<T>;
 export {};

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

@@ -1,5 +1,6 @@
-import { replaceState } from '$app/navigation';
+import { goto } from '$app/navigation';
 import { page } from '$app/state';
+import { untrack } from 'svelte';
 import { createEffect } from '../effect/Effect.svelte.js';
 import { cloneStateValue } from '../shared/cloneStateValue.js';
 import { fromSearchParams, toSearchParams } from './SearchParamsSync.js';
@@ -53,13 +54,16 @@ const createDeepDependency = (read) => {
     };
 };
 export const createQuery = (initialValue, options) => {
-    const baseInitial = cloneStateValue(initialValue);
+    // Capture defaults once; reset restores this snapshot rather than rerunning the initializer.
+    const baseInitial = untrack(() => cloneStateValue(typeof initialValue === 'function' ? initialValue() : initialValue));
     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;
+    const parsedInitial = syncEnabled
+        ? parseSearchParams(new URLSearchParams((page.shallow?.url ?? page.url).searchParams.toString()), cloneStateValue(baseInitial))
+        : undefined;
     let data = $state(parsedInitial ? { ...cloneStateValue(baseInitial), ...cloneStateValue(parsedInitial) } : cloneStateValue(baseInitial));
     const reset = () => {
         data = cloneStateValue(baseInitial);
@@ -92,13 +96,17 @@ export const createQuery = (initialValue, options) => {
                 if (nextParams.toString() === initialParams.toString())
                     return;
             }
-            const url = new URL(page.url);
+            const currentUrl = page.shallow?.url ?? page.url;
+            const url = new URL(currentUrl.href);
             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);
+            if (url.search !== currentUrl.search) {
+                void goto(url, { state: page.state, shallow: true, replace: true, reset: false }).catch((error) => {
+                    console.error('[createQuery] Failed to synchronize search parameters', error);
+                });
+            }
         }, [createDeepDependency(() => data)]);
     }
     return {