@svadmin/core 0.50.0 → 0.53.0

package/src/select-query.svelte.ts

@@ -0,0 +1,191 @@
+import { untrack } from 'svelte';
+import { createSessionQuery } from './session-query.svelte';
+import { captureAuthLiveScope } from './auth-hooks.svelte';
+import { definedOptions } from './defined-options';
+import { captureContractContext, type ContractOptions } from './contract-context.svelte';
+import { getAdminOptions } from './options.svelte';
+import { captureQueryProvider, snapshotListParams, snapshotManyParams } from './query-snapshot';
+import { decodeListResult, decodeManyResult, rejectProviderResponse, type RecordDecoder } from './record-decoder';
+import { createOvertimeTracker } from './hook-utils.svelte';
+import type { NotificationConfig, OvertimeOptions } from './hook-utils.svelte';
+import { createSelectProjection, mergeSelectOptions, type SelectOption } from './select-options';
+import { HttpError, type BaseRecord, type KnownResources, type Pagination, type Sort, type Filter } from './types';
+
+export interface UseSelectOptions<TData extends BaseRecord = BaseRecord> extends ContractOptions {
+  resource: KnownResources;
+  /** @internal Distinguishes consumers that use different projection semantics. */
+  projectionKey?: string;
+  optionLabel?: string | ((item: TData) => string);
+  optionValue?: string | ((item: TData) => string | number);
+  sorters?: Sort[];
+  filters?: Filter[];
+  defaultValue?: (string | number)[];
+  fetchSize?: number;
+  pagination?: Pagination;
+  debounce?: number;
+  queryOptions?: { staleTime?: number; enabled?: boolean };
+  defaultValueQueryOptions?: { staleTime?: number; enabled?: boolean };
+  meta?: Record<string, unknown>;
+  dataProviderName?: string;
+  onSearch?: (value: string) => Filter[];
+  successNotification?: NotificationConfig;
+  errorNotification?: NotificationConfig;
+  overtimeOptions?: OvertimeOptions;
+}
+
+export function createSelectQuery<TData extends BaseRecord>(
+  options: UseSelectOptions<TData>, getDecoder: () => RecordDecoder<TData>,
+) {
+  const context = captureContractContext(options);
+  const adminOptions = getAdminOptions();
+  let disposed = false;
+  const scope = $derived.by(() => {
+    const resource = options.resource;
+    const contract = options.contract;
+    const captured = captureQueryProvider(context, {
+      resource, ...definedOptions({
+        dataProviderName: options.dataProviderName, contract, meta: options.meta,
+      }),
+    });
+    const params = snapshotListParams({
+      resource, ...definedOptions({
+        pagination: { ...options.pagination, current: options.pagination?.current ?? 1,
+          pageSize: options.fetchSize ?? options.pagination?.pageSize ?? 999 },
+        filters: options.filters, sorters: options.sorters, meta: captured.meta,
+      }),
+    });
+    const authProvider = context.authProvider;
+    return {
+      captured,
+      params,
+      decode: getDecoder(),
+      keys: context.queryKeys(resource, options.dataProviderName),
+      optionLabel: options.optionLabel,
+      optionValue: options.optionValue,
+      projectionKey: options.projectionKey ?? [
+        typeof options.optionLabel === 'string' ? options.optionLabel : 'callback',
+        typeof options.optionValue === 'string' ? options.optionValue : 'callback',
+      ].join(':'),
+      onSearch: options.onSearch,
+      checkIds: contract !== undefined,
+      authProvider,
+      auth: captureAuthLiveScope(authProvider),
+    };
+  });
+  const sessionCurrent = (origin: typeof scope) => !disposed &&
+    origin.authProvider === context.authProvider && origin.auth.isCurrent();
+  let search = $state.raw<{ scope: typeof scope; value: string } | undefined>();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const request = $derived.by(() => {
+    const current = scope;
+    const text = search?.scope === current && sessionCurrent(current) ? search.value : '';
+    try {
+      // Validate callback output before spreading it or giving it to the provider.
+      const extra = snapshotListParams({
+        resource: current.params.resource,
+        filters: text && current.onSearch ? untrack(() => current.onSearch?.(text)) : [],
+      });
+      return { params: snapshotListParams({
+        ...current.params, filters: [...(current.params.filters ?? []), ...(extra.filters ?? [])],
+      }), text, error: undefined };
+    } catch {
+      return { params: current.params, text,
+        error: new HttpError('Invalid select search', 422, undefined, { code: 'INVALID_RESOURCE_INPUT' }) };
+    }
+  });
+  const query = createSessionQuery<
+    { data: TData[]; total: number },
+    { data: TData[]; total: number; options: SelectOption[] }
+  >(context, () => {
+    const origin = scope;
+    const { captured, decode, keys } = origin;
+    const { params, text, error } = request;
+    const label = origin.optionLabel ?? 'title';
+    const value = origin.optionValue ?? 'id';
+    const decodeResult = (input: unknown) => {
+      const result = decodeListResult(input, decode);
+      if (origin.checkIds && new Set(result.data.map(record => record['id'])).size !== result.data.length) return rejectProviderResponse();
+      return result;
+    };
+    return {
+      resource: params.resource, successNotification: options.successNotification, errorNotification: options.errorNotification,
+      decode: createSelectProjection(decodeResult, label, value, decode, () => sessionCurrent(origin)),
+      queryKey: keys.data.select(params.resource, {
+        ...params, source: captured.source, search: text, invalid: !!error, projection: origin.projectionKey,
+      }),
+      queryFn: async () => {
+        if (error) throw error;
+        return decodeResult(await captured.provider.getList(snapshotListParams(params)));
+      },
+      enabled: options.queryOptions?.enabled ?? true,
+      ...definedOptions({ staleTime: options.queryOptions?.staleTime ?? adminOptions.reactQuery?.staleTime }),
+    };
+  });
+  const defaultValueQuery = createSessionQuery<
+    { data: TData[] }, { data: TData[]; options: SelectOption[] }
+  >(context, () => {
+    const origin = scope;
+    const { captured, decode, keys, params: base } = origin;
+    const params = snapshotManyParams({
+      resource: base.resource, ids: options.defaultValue ?? [], ...definedOptions({ meta: base.meta }),
+    });
+    const label = origin.optionLabel ?? 'title';
+    const value = origin.optionValue ?? 'id';
+    const expected = new Set<unknown>(params.ids);
+    const decodeResult = (input: unknown) => {
+      const result = decodeManyResult(input, decode);
+      if (origin.checkIds && (expected.size !== params.ids.length || result.data.length !== expected.size ||
+        new Set(result.data.map(record => record['id'])).size !== result.data.length ||
+        result.data.some(record => !expected.has(record['id'])))) return rejectProviderResponse();
+      return result;
+    };
+    return {
+      resource: params.resource, successNotification: false, errorNotification: options.errorNotification,
+      decode: createSelectProjection(decodeResult, label, value, decode, () => sessionCurrent(origin)),
+      queryKey: keys.data.selectDefaults(params.resource, { ...params, source: captured.source, projection: origin.projectionKey }),
+      queryFn: async () => {
+        if (!params.ids.length) return { data: [] };
+        const getMany = captured.provider.getMany;
+        if (!getMany) throw new Error('Captured query provider must support getMany');
+        return decodeResult(await getMany.call(captured.provider, snapshotManyParams(params)));
+      },
+      enabled: (options.queryOptions?.enabled ?? true) &&
+        (options.defaultValueQueryOptions?.enabled ?? true) && params.ids.length > 0,
+      staleTime: options.defaultValueQueryOptions?.staleTime ?? Infinity,
+    };
+  });
+  const overtime = createOvertimeTracker(
+    () => query.isLoading || defaultValueQuery.isLoading, options.overtimeOptions ?? adminOptions.overtime,
+  );
+
+  function onSearchChange(value: string) {
+    if (typeof value !== 'string') throw new TypeError('Select search must be a string');
+    const delay = options.debounce ?? 300;
+    if (!Number.isFinite(delay) || delay < 0) throw new TypeError('Select debounce must be a finite nonnegative number');
+    clearTimeout(timer);
+    const current = scope;
+    if (!sessionCurrent(current)) return;
+    if (!value || delay === 0) {
+      search = { scope: current, value };
+      return;
+    }
+    timer = setTimeout(() => {
+      if (scope === current && sessionCurrent(current)) search = { scope: current, value };
+    }, delay);
+  }
+  $effect(() => {
+    void scope;
+    return () => clearTimeout(timer);
+  });
+  $effect(() => () => { disposed = true; });
+
+  return {
+    query, defaultValueQuery, onSearchChange,
+    get options() { return mergeSelectOptions(query.data?.options ?? [], defaultValueQuery.data?.options ?? []); },
+    get overtime() { return overtime; },
+    get isLoading() { return query.isLoading || defaultValueQuery.isLoading; },
+    get isFetching() { return query.isFetching || defaultValueQuery.isFetching; },
+    get isError() { return query.isError || defaultValueQuery.isError; },
+    async refetch() { await Promise.all([query.refetch(), defaultValueQuery.refetch()]); },
+  };
+}

package/src/session-query.svelte.ts

@@ -0,0 +1,103 @@
+import { createQuery, hashKey, type QueryObserverResult, type RefetchOptions } from '@tanstack/svelte-query';
+import { tick, untrack } from 'svelte';
+import type { AdminContextAccessor } from './context.svelte';
+import { definedOptions } from './defined-options';
+import {
+  createQuerySession, createQueryResultView, pendingQueryResult, supersededQuerySession,
+  type QuerySessionOptions,
+} from './query-session.svelte';
+
+interface SessionQueryOptions<TQuery, T> extends QuerySessionOptions {
+  queryFn: (signal?: AbortSignal) => Promise<TQuery>;
+  decode: (value: unknown, dataUpdateCount: number) => T;
+  enabled: boolean;
+  staleTime?: number;
+  gcTime?: number;
+  refetchOnWindowFocus?: boolean;
+  refetchInterval?: number | false;
+  refetchIntervalInBackground?: boolean;
+}
+
+// 只有显式提供错误归一化器的内部领域查询才承诺 Error；普通查询保留 unknown 契约。
+export function createSessionQuery<TQuery, T = TQuery>(
+  context: AdminContextAccessor,
+  getOptions: () => SessionQueryOptions<TQuery, T> & { normalizeError: (error: unknown) => Error },
+): QueryObserverResult<T, Error>;
+export function createSessionQuery<TQuery, T = TQuery>(
+  context: AdminContextAccessor,
+  getOptions: () => SessionQueryOptions<TQuery, T>,
+): QueryObserverResult<T, unknown>;
+/** Ordinary reads keep their public result shape while cache and effects own an auth revision. */
+export function createSessionQuery<TQuery, T = TQuery>(
+  context: AdminContextAccessor,
+  getOptions: () => SessionQueryOptions<TQuery, T>,
+): QueryObserverResult<T, Error> {
+  const session = createQuerySession(context, getOptions);
+  const inFlight = new Map<string, { origin: typeof session.options; request: Promise<TQuery> }>();
+  type Origin = typeof session.options;
+  const query = createQuery<TQuery, Error>(() => {
+    const origin = session.options;
+    return {
+      queryKey: origin.queryKey,
+      queryFn: (queryContext) => {
+        const key = hashKey(origin.queryKey);
+        const existing = inFlight.get(key);
+        if (existing && session.current(existing.origin)) return existing.request;
+        if (existing) inFlight.delete(key);
+        const request = session.run(origin, () => origin.queryFn(queryContext?.signal));
+        inFlight.set(key, { origin, request });
+        void request.then(() => {
+          if (inFlight.get(key)?.request === request) inFlight.delete(key);
+        }, () => {
+          if (inFlight.get(key)?.request === request) inFlight.delete(key);
+        });
+        return request;
+      },
+      enabled: origin.enabled && origin.auth.available,
+      ...definedOptions({
+        staleTime: origin.staleTime, gcTime: origin.gcTime, refetchOnWindowFocus: origin.refetchOnWindowFocus,
+        refetchInterval: origin.refetchInterval, refetchIntervalInBackground: origin.refetchIntervalInBackground,
+      }),
+    };
+  });
+
+  function project(origin: Origin, result: QueryObserverResult<TQuery, Error>): QueryObserverResult<T, Error> {
+    const refetch = async (settings?: RefetchOptions): Promise<QueryObserverResult<T, Error>> => {
+      if (!session.current(origin)) return pendingQueryResult(refetch);
+      await tick();
+      if (!session.current(origin)) return pendingQueryResult(refetch);
+      try {
+        return project(origin, await query.refetch(settings));
+      } catch (error) {
+        throw session.current(origin) ? session.errorFor(origin, error) : supersededQuerySession();
+      }
+    };
+    if (!session.current(origin)) return pendingQueryResult(refetch);
+    // 新查询键尚未入缓存时也要订阅结果，否则请求完成后视图不会重新计算。
+    const observedData = result.data;
+    const observedError = result.error;
+    const state = session.client.getQueryState(origin.queryKey);
+    // The observer may still expose its previous key until Svelte flushes its effects.
+    if (!state || state.data !== observedData || state.error !== observedError) return pendingQueryResult(refetch);
+    const failureReason = result.failureReason === null ? null : session.errorFor(origin, result.failureReason);
+    try {
+      if (result.isSuccess || result.isRefetchError) {
+        const data = untrack(() => origin.decode(result.data, state.dataUpdateCount));
+        if (!session.current(origin)) return pendingQueryResult(refetch);
+        if (result.isSuccess) return { ...result, data, failureReason, refetch };
+        return { ...result, data, error: session.errorFor(origin, result.error), failureReason, refetch };
+      }
+      if (result.isError) return { ...result, error: session.errorFor(origin, result.error), failureReason, refetch };
+      return { ...result, failureReason, refetch };
+    } catch (error) {
+      if (!session.current(origin)) return pendingQueryResult(refetch);
+      return {
+        ...pendingQueryResult(refetch), data: undefined, error: session.errorFor(origin, error), status: 'error',
+        isError: true, isPending: false, isLoading: false, isLoadingError: true,
+        isRefetchError: false, isSuccess: false, isPlaceholderData: false,
+      };
+    }
+  }
+  session.observe(origin => project(origin, query));
+  return createQueryResultView(() => project(session.options, query));
+}

package/src/strict-command-hooks.svelte.ts

@@ -0,0 +1,333 @@
+import type { TObject, TSchema } from '@sinclair/typebox';
+import { hashKey, useQueryClient } from '@tanstack/svelte-query';
+import { captureAdminContext, type AdminContextAccessor } from './context.svelte';
+import { commandDefinition, prepareCommand, parseCommandInput, parseCommandResponse,
+  type CommandContract, type CommandInput, type CommandOutput } from './command-contract';
+import { captureAuthLiveScope, clearAuthQueries, handleAuthError } from './auth-hooks.svelte';
+import { createSessionQuery } from './session-query.svelte';
+import { createQueryResultView, supersededQuerySession } from './query-session.svelte';
+import { definedOptions } from './defined-options';
+import { keys } from './query-keys';
+import { HttpError, type DataProvider } from './types';
+
+type Result<O extends TSchema> = { data: CommandOutput<O> };
+interface CommandOptions<I extends TObject, O extends TSchema> {
+  command: CommandContract<I, O>;
+  dataProviderName?: string;
+}
+interface Callbacks<I extends TObject, O extends TSchema> {
+  onSuccess?: (data: Result<O>, input: CommandInput<I>) => void | Promise<void>;
+  onError?: (error: HttpError, input: CommandInput<I> | undefined) => void | Promise<void>;
+  onSettled?: (data: Result<O> | undefined, error: HttpError | null, input: CommandInput<I> | undefined) => void | Promise<void>;
+}
+type CommandState<I extends TObject, O extends TSchema> =
+  | { readonly status: 'idle'; readonly isIdle: true; readonly isPending: false; readonly isSuccess: false; readonly isError: false;
+      readonly data: undefined; readonly error: null; readonly variables: undefined }
+  | { readonly status: 'pending'; readonly isIdle: false; readonly isPending: true; readonly isSuccess: false; readonly isError: false;
+      readonly data: undefined; readonly error: null; readonly variables: CommandInput<I> }
+  | { readonly status: 'success'; readonly isIdle: false; readonly isPending: false; readonly isSuccess: true; readonly isError: false;
+      readonly data: Result<O>; readonly error: null; readonly variables: CommandInput<I> }
+  | { readonly status: 'error'; readonly isIdle: false; readonly isPending: false; readonly isSuccess: false; readonly isError: true;
+      readonly data: undefined; readonly error: HttpError; readonly variables: CommandInput<I> | undefined };
+
+const sources = new WeakMap<DataProvider, string>();
+const runtime = `${Date.now()}:${Math.random().toString(36).slice(2)}`;
+let nextSource = 0;
+function captureProvider(context: AdminContextAccessor, override: string | undefined) {
+  const name = override ?? 'default';
+  if (typeof name !== 'string' || !name.length) {
+    throw new HttpError('Invalid command provider', 422, undefined, { code: 'INVALID_COMMAND_INPUT' });
+  }
+  const provider = context.providers?.[name];
+  if (!provider) throw new HttpError('Data provider unavailable', 400, undefined, { code: 'DATA_PROVIDER_REQUIRED' });
+  let source = sources.get(provider);
+  if (source === undefined) {
+    source = `command:${runtime}:${++nextSource}`;
+    sources.set(provider, source);
+  }
+  return { provider, name, source };
+}
+function requireMethod(command: CommandContract, read: boolean) {
+  const definition = commandDefinition(command);
+  if ((definition.method === 'get') !== read) {
+    throw new HttpError(read ? 'Queries require a GET command' : 'Mutations require a write command', 400, undefined, {
+      code: 'INVALID_COMMAND_METHOD',
+    });
+  }
+  return definition;
+}
+function observe(callback: () => unknown): void {
+  try { void Promise.resolve(callback()).catch(() => {}); }
+  catch { /* Observers do not own the command outcome. */ }
+}
+function failure(cause: unknown, dispatched = false): HttpError {
+  let status = 502;
+  let code = 'COMMAND_FAILED';
+  try {
+    if (typeof cause === 'object' && cause !== null) {
+      const value: unknown = Object.getOwnPropertyDescriptor(cause, 'statusCode')?.value;
+      const label: unknown = Object.getOwnPropertyDescriptor(cause, 'code')?.value;
+      if (typeof value === 'number' && Number.isInteger(value) && value >= 400 && value <= 599) status = value;
+      if (label === 'INVALID_COMMAND_INPUT' || label === 'INVALID_COMMAND_RESPONSE' ||
+          label === 'INVALID_COMMAND_CONTRACT' || label === 'INVALID_COMMAND_METHOD' ||
+          label === 'COMMAND_NOT_SUPPORTED' || label === 'DATA_PROVIDER_REQUIRED') code = label;
+    }
+  } catch { /* Reflection errors remain private. */ }
+  return new HttpError('Command failed', status, undefined, { code, details: { writeMayHaveSucceeded: dispatched } });
+}
+function cancelled(dispatched: boolean): HttpError {
+  return new HttpError('Command scope changed', 409, undefined, {
+    code: 'COMMAND_CANCELLED', details: { writeMayHaveSucceeded: dispatched },
+  });
+}
+
+export function useCustom<I extends TObject, O extends TSchema>(options: CommandOptions<I, O> & {
+  input: NoInfer<CommandInput<I>>;
+  queryOptions?: { enabled?: boolean; staleTime?: number };
+}) {
+  const context = captureAdminContext();
+  const query = createSessionQuery<Result<O>>(context, () => {
+    const command = options.command;
+    const definition = requireMethod(command, true);
+    const override = options.dataProviderName;
+    const captured = captureProvider(context, override);
+    const tenant = context.tenantCacheKey?.__svadminTenant;
+    const prepared = prepareCommand(captured.provider, command, options.input);
+    const signature = hashKey([prepared.input]);
+    const { enabled = true, staleTime } = options.queryOptions ?? {};
+    if (typeof enabled !== 'boolean' || (staleTime !== undefined &&
+        (typeof staleTime !== 'number' || Number.isNaN(staleTime) || staleTime < 0))) {
+      throw new HttpError('Invalid command query settings', 422, undefined, { code: 'INVALID_COMMAND_INPUT' });
+    }
+    return {
+      resource: command.name, successNotification: false, errorNotification: false,
+      queryKey: keys(definedOptions({
+        provider: captured.name, contract: definition.key, tenant,
+      })).custom.call(definition.key, definition.key, definition.method, { input: prepared.input, source: captured.source }),
+      queryFn: () => {
+        if (command !== options.command || override !== options.dataProviderName ||
+            tenant !== context.tenantCacheKey?.__svadminTenant ||
+            captured.provider !== captureProvider(context, override).provider ||
+            signature !== hashKey([parseCommandInput(command, options.input)])) throw supersededQuerySession();
+        return prepared.execute();
+      },
+      decode: value => parseCommandResponse(command, value),
+      enabled, ...definedOptions({ staleTime }),
+    };
+  });
+  return { query };
+}
+
+/** Command writes own their state and observers; native mutation defaults are not a dispatch boundary. */
+export function useCustomMutation<I extends TObject, O extends TSchema>(options: CommandOptions<I, O>) {
+  requireMethod(options.command, false);
+  const context = captureAdminContext();
+  const client = useQueryClient();
+  let mounted = true;
+  function origin() {
+    const auth = context.authProvider;
+    const authScope = captureAuthLiveScope(auth);
+    const router = context.routerProvider;
+    const tenant = context.tenantCacheKey?.__svadminTenant;
+    const command = options.command;
+    const override = options.dataProviderName;
+    return {
+      command, definition: requireMethod(command, false), override,
+      auth, authScope, router, tenant, ...captureProvider(context, override),
+    };
+  }
+  function capture(owner: ReturnType<typeof origin>, input: CommandInput<I>) {
+    const prepared = prepareCommand(owner.provider, owner.command, input);
+    return { ...owner, prepared, signature: hashKey([owner.definition.key, owner.source,
+      owner.tenant, owner.authScope.cacheKey, prepared.input]) };
+  }
+  type Origin = ReturnType<typeof origin>;
+  type Scope = ReturnType<typeof capture>;
+  type Invocation = { scope: Scope; token: object; dispatched: boolean; promise: Promise<Result<O>> };
+  let state = $state.raw<CommandState<I, O>>(idle());
+  let latest = $state.raw<Scope | undefined>();
+  let failedOrigin = $state.raw<Origin | undefined>();
+  let latestToken: object | undefined;
+  let active: Invocation | undefined;
+  let controlEpoch = 0;
+  function idle(): CommandState<I, O> {
+    return { status: 'idle', isIdle: true, isPending: false, isSuccess: false, isError: false,
+      data: undefined, error: null, variables: undefined };
+  }
+  function originCurrent(owner: Origin): boolean {
+    try {
+      return mounted && owner.command === options.command && owner.override === options.dataProviderName &&
+        owner.auth === context.authProvider && owner.router === context.routerProvider &&
+        owner.tenant === context.tenantCacheKey?.__svadminTenant;
+    } catch { return false; }
+  }
+  function targetCurrent(scope: Origin): boolean {
+    try {
+      return originCurrent(scope) && captureProvider(context, scope.override).provider === scope.provider;
+    } catch { return false; }
+  }
+  const current = (scope: Scope, token: object) =>
+    targetCurrent(scope) && scope.authScope.isCurrent() && latestToken === token;
+  function copyError(error: HttpError, dispatched: boolean): HttpError {
+    return error.code === 'COMMAND_CANCELLED' ? cancelled(dispatched) : failure(error, dispatched);
+  }
+  function callbacks(value: Callbacks<I, O>): Callbacks<I, O> {
+    if (typeof value !== 'object' || value === null) {
+      throw new HttpError('Invalid command callbacks', 422, undefined, { code: 'INVALID_COMMAND_INPUT' });
+    }
+    function read(name: keyof Callbacks<I, O>) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, name);
+      if (!descriptor) return undefined;
+      const callback: unknown = descriptor.value;
+      if (!('value' in descriptor) || (callback !== undefined && typeof callback !== 'function')) {
+        throw new HttpError('Invalid command callbacks', 422, undefined, { code: 'INVALID_COMMAND_INPUT' });
+      }
+      return typeof callback === 'function' ? async (...args: unknown[]): Promise<void> => {
+        const result: unknown = Reflect.apply(callback, undefined, args);
+        await result;
+      } : undefined;
+    }
+    return definedOptions({ onSuccess: read('onSuccess'), onError: read('onError'), onSettled: read('onSettled') });
+  }
+  function ensure(invocation: Invocation): void {
+    if (!current(invocation.scope, invocation.token)) throw cancelled(invocation.dispatched);
+  }
+  async function run(invocation: Invocation): Promise<Result<O>> {
+    const { scope, token } = invocation;
+    ensure(invocation);
+    let result: Result<O>;
+    try {
+      invocation.dispatched = true;
+      result = await scope.prepared.execute();
+    } catch (cause) {
+      ensure(invocation);
+      const error = failure(cause, invocation.dispatched);
+      state = { status: 'error', isIdle: false, isPending: false, isSuccess: false, isError: true,
+        data: undefined, error, variables: scope.prepared.input };
+      observe(() => handleAuthError(copyError(error, invocation.dispatched), context,
+        () => targetCurrent(scope) && latestToken === token,
+        () => clearAuthQueries(client, scope.auth), scope.authScope));
+      throw error;
+    }
+    ensure(invocation);
+    state = { status: 'success', isIdle: false, isPending: false, isSuccess: true, isError: false,
+      data: result, error: null, variables: scope.prepared.input };
+    return result;
+  }
+  function deliver(invocation: Invocation, observers: Callbacks<I, O>): Promise<Result<O>> {
+    const { scope } = invocation;
+    return invocation.promise.then(result => {
+      ensure(invocation);
+      observe(() => observers.onSuccess?.(parseCommandResponse(scope.command, result), scope.prepared.input));
+      ensure(invocation);
+      observe(() => observers.onSettled?.(parseCommandResponse(scope.command, result), null, scope.prepared.input));
+      ensure(invocation);
+      return parseCommandResponse(scope.command, result);
+    }, (cause: unknown) => {
+      ensure(invocation);
+      const error = failure(cause, invocation.dispatched);
+      observe(() => observers.onError?.(copyError(error, invocation.dispatched), scope.prepared.input));
+      ensure(invocation);
+      observe(() => observers.onSettled?.(undefined, copyError(error, invocation.dispatched), scope.prepared.input));
+      ensure(invocation);
+      throw error;
+    });
+  }
+  function mutateAsync(input: NoInfer<CommandInput<I>>, value: Callbacks<I, O> = {}): Promise<Result<O>> {
+    const epoch = controlEpoch;
+    let owner: Origin;
+    try { owner = origin(); }
+    catch (cause) { return Promise.reject(epoch === controlEpoch ? failure(cause) : cancelled(false)); }
+    const available = () => epoch === controlEpoch && targetCurrent(owner) && owner.authScope.isCurrent();
+    if (!available()) return Promise.reject(cancelled(false));
+    let scope: Scope;
+    let observers: Callbacks<I, O> = {};
+    try {
+      observers = callbacks(value);
+      scope = capture(owner, input);
+    } catch (cause) {
+      if (!available()) return Promise.reject(cancelled(false));
+      const error = failure(cause);
+      const preserved = active && current(active.scope, active.token);
+      const token = preserved ? latestToken : {};
+      if (!preserved) {
+        controlEpoch++;
+        active = undefined;
+        latest = undefined;
+        failedOrigin = owner;
+        latestToken = token;
+        state = { status: 'error', isIdle: false, isPending: false, isSuccess: false, isError: true,
+          data: undefined, error, variables: undefined };
+      }
+      return Promise.resolve().then(() => {
+        const ensure = () => {
+          if (!targetCurrent(owner) || !owner.authScope.isCurrent() || latestToken !== token) throw cancelled(false);
+        };
+        ensure();
+        observe(() => observers.onError?.(copyError(error, false), undefined));
+        ensure();
+        observe(() => observers.onSettled?.(undefined, copyError(error, false), undefined));
+        ensure();
+        throw copyError(error, false);
+      });
+    }
+    if (!available()) return Promise.reject(cancelled(false));
+    if (active && current(active.scope, active.token)) {
+      if (active.scope.signature === scope.signature) return deliver(active, observers);
+      return Promise.reject(new HttpError('A command is already running', 409, undefined, { code: 'COMMAND_BUSY' }));
+    }
+    const token = {};
+    controlEpoch++;
+    latestToken = token;
+    latest = scope;
+    failedOrigin = undefined;
+    state = { status: 'pending', isIdle: false, isPending: true, isSuccess: false, isError: false,
+      data: undefined, error: null, variables: scope.prepared.input };
+    const invocation: Invocation = { scope, token, dispatched: false, promise: Promise.resolve().then(() => run(invocation)) };
+    invocation.promise = invocation.promise.finally(() => { if (active === invocation) active = undefined; });
+    active = invocation;
+    return deliver(invocation, observers);
+  }
+  function reset(): void {
+    controlEpoch++;
+    active = undefined;
+    latest = undefined;
+    failedOrigin = undefined;
+    latestToken = undefined;
+    state = idle();
+  }
+  $effect.pre(() => {
+    const scope = latest ?? failedOrigin;
+    if (scope && (!targetCurrent(scope) || !scope.authScope.isCurrent())) {
+      controlEpoch++;
+      // Auth retirement must not cancel the checked delegate's own logout intent.
+      if (!targetCurrent(scope)) latestToken = undefined;
+      latest = undefined;
+      failedOrigin = undefined;
+      active = undefined;
+      state = idle();
+    }
+  });
+  $effect(() => () => { mounted = false; reset(); });
+  function projection(): CommandState<I, O> {
+    const scope = latest;
+    const owner = scope ?? failedOrigin;
+    if (!mounted || (owner && (!targetCurrent(owner) || !owner.authScope.isCurrent()))) return idle();
+    if (state.isIdle) return state;
+    const variables = scope ? parseCommandInput(scope.command, state.variables) : undefined;
+    if (state.isError) return { ...state, error: failure(state.error, scope !== undefined), variables };
+    if (!scope || variables === undefined) return idle();
+    if (state.isSuccess) return { ...state, data: parseCommandResponse(scope.command, state.data), variables };
+    return { ...state, variables };
+  }
+  const controls = {
+    mutateAsync, reset,
+    mutate(input: NoInfer<CommandInput<I>>, observers?: Callbacks<I, O>): void {
+      void mutateAsync(input, observers).catch(() => {});
+    },
+  };
+  const mutation = createQueryResultView((): CommandState<I, O> & Readonly<typeof controls> => ({
+    ...projection(), ...controls,
+  }));
+  return { mutation };
+}