@svadmin/core 0.49.1 → 0.52.0

package/src/query-session.svelte.ts

@@ -0,0 +1,216 @@
+import { hashKey, useQueryClient, type QueryObserverPendingResult, type QueryObserverResult, type RefetchOptions } from '@tanstack/svelte-query';
+import { untrack } from 'svelte';
+import { Type } from '@sinclair/typebox';
+import type { AdminContextAccessor } from './context.svelte';
+import { captureAuthLiveScope, clearAuthQueries, handleAuthError } from './auth-hooks.svelte';
+import { decodeBaseRecord } from './record-decoder';
+import { HttpError } from './types';
+import type { QueryKey } from './query-keys';
+import { definedOptions } from './defined-options';
+import type { NotificationConfig } from './hook-utils.svelte';
+import { notifyWithProvider } from './notification.svelte';
+import { snapshotPlainData } from './plain-data';
+import { checkExact } from './schema-validation';
+
+const notificationSchema = Type.Object({
+  message: Type.String(), description: Type.Optional(Type.String()), key: Type.Optional(Type.String()),
+  type: Type.Optional(Type.Union([Type.Literal('success'), Type.Literal('error')])),
+}, { additionalProperties: false });
+
+export interface QuerySessionOptions {
+  queryKey: QueryKey;
+  resource: string;
+  successNotification: NotificationConfig;
+  errorNotification: NotificationConfig;
+  /** Extra observer lifetime constraints; must not include auth retirement during delegated logout. */
+  isTargetCurrent?: () => boolean;
+  /** Allow a shared query function to delegate work to another live observer. */
+  allowRetiredQueryFn?: boolean;
+}
+
+export function supersededQuerySession(): HttpError {
+  return new HttpError('Query session is no longer current', 409, undefined, { code: 'QUERY_SESSION_SUPERSEDED' });
+}
+
+/** Retain only protocol status and known local codes, never provider diagnostics. */
+export function querySessionError(error: unknown): HttpError {
+  let status = 502;
+  let code = 'QUERY_FAILED';
+  try {
+    if (typeof error === 'object' && error !== null) {
+      const statusValue: unknown = Object.getOwnPropertyDescriptor(error, 'statusCode')?.value;
+      const codeValue: unknown = Object.getOwnPropertyDescriptor(error, 'code')?.value;
+      if (typeof statusValue === 'number' && Number.isInteger(statusValue) && statusValue >= 400 && statusValue <= 599) status = statusValue;
+      if (codeValue === 'INVALID_PROVIDER_RESPONSE' || codeValue === 'INVALID_RESOURCE_INPUT' ||
+        codeValue === 'DATA_PROVIDER_REQUIRED' || codeValue === 'QUERY_SESSION_SUPERSEDED' ||
+        codeValue === 'INVALID_SELECT_OPTION' || codeValue === 'INVALID_COMMAND_INPUT' ||
+        codeValue === 'INVALID_COMMAND_RESPONSE' || codeValue === 'INVALID_COMMAND_CONTRACT' ||
+        codeValue === 'INVALID_COMMAND_METHOD' || codeValue === 'COMMAND_NOT_SUPPORTED' ||
+        codeValue === 'COMMAND_FAILED' || codeValue === 'INVALID_ACCESS_CONTROL_INPUT' ||
+        codeValue === 'INVALID_ACCESS_CONTROL_RESPONSE' || codeValue === 'INVALID_ACCESS_CONTROL_PROVIDER') code = codeValue;
+    }
+  } catch {
+    // Hostile reflection is not an authentication instruction.
+  }
+  return new HttpError('Resource query failed', status, undefined, { code });
+}
+
+interface QueryObservation {
+  isSuccess: boolean;
+  isError: boolean;
+  data: unknown;
+  error: unknown;
+  dataUpdatedAt: number;
+  errorUpdatedAt: number;
+}
+
+/** Shared ownership for ordinary, projected and paginated readers. */
+export function createQuerySession<O extends QuerySessionOptions>(context: AdminContextAccessor, getOptions: () => O) {
+  const client = useQueryClient();
+  let disposed = false;
+  const options = $derived.by(() => {
+    const input = getOptions();
+    const provider = context.authProvider;
+    const auth = captureAuthLiveScope(provider);
+    const descriptor = input.queryKey[0];
+    const queryKey: QueryKey = [{
+      ...descriptor, params: { ...decodeBaseRecord(descriptor.params), authSession: auth.cacheKey },
+    }];
+    return {
+      ...input, queryKey, auth, provider, target: hashKey(input.queryKey),
+      tenant: context.tenantCacheKey?.__svadminTenant,
+      router: context.routerProvider, notification: context.notificationProvider,
+    };
+  });
+  type Origin = typeof options;
+  const sessionCurrent = (origin: Origin) => origin.provider === context.authProvider && origin.auth.isCurrent();
+  const targetCurrent = (origin: Origin) => !disposed && origin.target === options.target &&
+    origin.provider === context.authProvider && origin.tenant === context.tenantCacheKey?.__svadminTenant &&
+    origin.router === context.routerProvider && (origin.isTargetCurrent === undefined || origin.isTargetCurrent() === true);
+  const current = (origin: Origin) => targetCurrent(origin) && sessionCurrent(origin);
+
+  function notify(origin: Origin, type: 'success' | 'error', value: unknown): void {
+    try {
+      const config = type === 'success' ? origin.successNotification : origin.errorNotification;
+      if (config === false || !current(origin)) return;
+      if (config !== undefined && typeof config !== 'function' && typeof config !== 'string') return;
+      const fallback = type === 'success' ? '' : 'Fetch failed: Resource query failed';
+      if (typeof config !== 'function' && !config && !fallback) return;
+      const candidate = snapshotPlainData(typeof config === 'function'
+        ? config(value, undefined, origin.resource) : { message: config || fallback });
+      if (!checkExact(notificationSchema, candidate) || !current(origin) || origin.notification !== context.notificationProvider) return;
+      notifyWithProvider({
+        type, message: candidate.message, ...definedOptions({ description: candidate.description, key: candidate.key }),
+      }, origin.notification);
+    } catch {
+      // Observer failures and malformed receipts cannot change query state.
+    }
+  }
+
+  function settleDetached(origin: Origin, result: { data?: unknown; error?: unknown; success: boolean }): void {
+    if (disposed) return;
+    const query = client.getQueryCache().find({ queryKey: origin.queryKey, exact: true });
+    if (!query || query.getObserversCount() > 0) return;
+    const now = Date.now();
+    if (result.success) {
+      query.setState({
+        data: result.data,
+        dataUpdatedAt: now,
+        dataUpdateCount: query.state.dataUpdateCount + 1,
+        error: null,
+        fetchFailureCount: 0,
+        fetchFailureReason: null,
+        fetchStatus: 'idle',
+        status: 'success',
+      });
+      return;
+    }
+    const error = querySessionError(result.error);
+    query.setState({
+      error,
+      errorUpdatedAt: now,
+      errorUpdateCount: query.state.errorUpdateCount + 1,
+      fetchFailureCount: query.state.fetchFailureCount + 1,
+      fetchFailureReason: error,
+      fetchStatus: 'idle',
+      status: 'error',
+    });
+  }
+
+  async function run<T>(origin: Origin, request: () => Promise<T>): Promise<T> {
+    const allowRetired = origin.allowRetiredQueryFn === true;
+    if ((!allowRetired && disposed) || !sessionCurrent(origin)) throw supersededQuerySession();
+    try {
+      const result = await request();
+      if ((!allowRetired && disposed) || !sessionCurrent(origin)) {
+        if (!disposed) settleDetached(origin, { success: false, error: supersededQuerySession() });
+        throw supersededQuerySession();
+      }
+      if (!current(origin)) settleDetached(origin, { success: true, data: result });
+      return result;
+    } catch (error) {
+      if ((!allowRetired && disposed) || !sessionCurrent(origin)) {
+        if (!disposed) settleDetached(origin, { success: false, error: supersededQuerySession() });
+        throw supersededQuerySession();
+      }
+      if (!current(origin)) settleDetached(origin, { success: false, error });
+      throw querySessionError(error);
+    }
+  }
+
+  function observe(getResult: (origin: Origin) => QueryObservation): void {
+    let lastSuccess: { key: string; at: number } | undefined;
+    let lastError: { key: string; at: number } | undefined;
+    $effect(() => {
+      const origin = options;
+      const result = getResult(origin);
+      const key = hashKey(origin.queryKey);
+      if (!current(origin)) return;
+      if (result.isSuccess && (lastSuccess?.key !== key || result.dataUpdatedAt > lastSuccess.at)) {
+        lastSuccess = { key, at: result.dataUpdatedAt };
+        untrack(() => notify(origin, 'success', result.data));
+      } else if (result.isError && (lastError?.key !== key || result.errorUpdatedAt > lastError.at)) {
+        lastError = { key, at: result.errorUpdatedAt };
+        untrack(() => {
+          void handleAuthError(querySessionError(result.error), context, () => targetCurrent(origin),
+            () => clearAuthQueries(client, origin.provider), origin.auth).catch(() => {});
+          notify(origin, 'error', querySessionError(result.error));
+        });
+      }
+    });
+  }
+  $effect(() => () => {
+    disposed = true;
+    queueMicrotask(() => {
+      const query = client.getQueryCache().find({ queryKey: options.queryKey, exact: true });
+      if (query?.getObserversCount() === 0) void query.cancel();
+    });
+  });
+  return { get options() { return options; }, client, current, sessionCurrent, run, observe };
+}
+
+export function pendingQueryResult<T, F extends (settings?: RefetchOptions) => Promise<unknown> = QueryObserverResult<T, unknown>['refetch']>(
+  refetch: F,
+): Omit<QueryObserverPendingResult<T, unknown>, 'refetch'> & { refetch: F } {
+  return {
+    data: undefined, dataUpdatedAt: 0, error: null, errorUpdatedAt: 0,
+    failureCount: 0, failureReason: null, errorUpdateCount: 0,
+    isError: false, isFetched: false, isFetchedAfterMount: false,
+    isFetching: false, isLoading: false, isPending: true, isLoadingError: false,
+    isInitialLoading: false, isPaused: false, isPlaceholderData: false,
+    isRefetchError: false, isRefetching: false, isStale: true, isSuccess: false,
+    isEnabled: false, status: 'pending', fetchStatus: 'idle', refetch,
+  };
+}
+
+/** Delegate reflection and property access to a fully discriminated, read-only result. */
+export function createQueryResultView<R extends object>(getResult: () => R): R {
+  return new Proxy(getResult(), {
+    get: (_target, key): unknown => Reflect.get(getResult(), key),
+    has: (_target, key) => Reflect.has(getResult(), key),
+    ownKeys: () => Reflect.ownKeys(getResult()),
+    getOwnPropertyDescriptor: (_target, key) => Reflect.has(getResult(), key)
+      ? { configurable: true, enumerable: true, get: () => Reflect.get(getResult(), key) } : undefined,
+    set: () => false, defineProperty: () => false, deleteProperty: () => false,
+  });
+}

package/src/query-snapshot.ts

@@ -0,0 +1,144 @@
+import { Type, type Static, type TSchema } from '@sinclair/typebox';
+import type { AdminContextAccessor } from './context.svelte';
+import type { DataProvider, GetListParams, GetOneParams, GetManyParams } from './types';
+import { HttpError } from './types';
+import { contractProvider, type ResourceContract } from './resource-contract';
+import { definedOptions } from './defined-options';
+import { attachAbortSignal, detachAbortSignal, snapshotPlainData } from './plain-data';
+import { checkExact } from './schema-validation';
+import { decodeBaseRecord, decodeListResult, decodeOneResult, decodeManyResult, rejectProviderResponse } from './record-decoder';
+
+const filters = Type.Recursive(self => Type.Union([
+  Type.Object({
+    field: Type.String(),
+    operator: Type.Union(([
+      'eq', 'ne', 'lt', 'gt', 'lte', 'gte', 'in', 'nin', 'contains', 'ncontains',
+      'startswith', 'endswith', 'null', 'nnull', 'between', 'nbetween',
+    ] as const).map(value => Type.Literal(value))),
+    value: Type.Unknown(),
+  }, { additionalProperties: false }),
+  Type.Object({
+    operator: Type.Union([Type.Literal('and'), Type.Literal('or')]),
+    value: Type.Array(self),
+  }, { additionalProperties: false }),
+]));
+const base = {
+  resource: Type.String({ minLength: 1 }),
+  meta: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+};
+const listSchema = Type.Object({
+  ...base,
+  pagination: Type.Optional(Type.Object({
+    current: Type.Optional(Type.Integer({ minimum: 1 })),
+    pageSize: Type.Optional(Type.Integer({ minimum: 1 })),
+    mode: Type.Optional(Type.Union([Type.Literal('server'), Type.Literal('client'), Type.Literal('off')])),
+  }, { additionalProperties: false })),
+  sorters: Type.Optional(Type.Array(Type.Object({
+    field: Type.String(), order: Type.Union([Type.Literal('asc'), Type.Literal('desc')]),
+  }, { additionalProperties: false }))),
+  filters: Type.Optional(Type.Array(filters)),
+}, { additionalProperties: false });
+const id = Type.Union([Type.String(), Type.Number()]);
+const oneSchema = Type.Object({ ...base, id }, { additionalProperties: false });
+const manySchema = Type.Object({ ...base, ids: Type.Array(id) }, { additionalProperties: false });
+
+function invalid(): never {
+  throw new HttpError('Invalid resource query', 422, undefined, { code: 'INVALID_RESOURCE_INPUT' });
+}
+
+function snapshotQueryParams<S extends TSchema>(schema: S, value: unknown): Static<S> {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(schema, candidate)) return candidate;
+  } catch {
+    // Query input errors must not disclose values or execute serialization hooks.
+  }
+  return invalid();
+}
+
+function snapshotParamsWithSignal<S extends TSchema>(schema: S, value: unknown): Static<S> {
+  const { signal, rest } = detachAbortSignal(value);
+  const params = snapshotQueryParams(schema, rest);
+  if (typeof params !== 'object' || params === null) return invalid();
+  return attachAbortSignal(params, signal);
+}
+
+export function snapshotListParams(value: unknown): GetListParams {
+  return snapshotParamsWithSignal(listSchema, value);
+}
+
+export function snapshotOneParams(value: unknown): GetOneParams {
+  return snapshotParamsWithSignal(oneSchema, value);
+}
+
+export function snapshotManyParams(value: unknown): GetManyParams {
+  return snapshotParamsWithSignal(manySchema, value);
+}
+
+const sourceIds = new WeakMap<DataProvider, string>();
+const runtime = `${Date.now()}:${Math.random().toString(36).slice(2)}`;
+let nextSource = 0;
+
+/** Capture a contract query's transport and metadata before any deferred query work. */
+export function captureQueryProvider(
+  context: AdminContextAccessor,
+  options: { resource: string; dataProviderName?: string; contract?: ResourceContract; meta?: Record<string, unknown>; fresh?: boolean },
+) {
+  const resource = context.resources.find(item => item.identifier === options.resource || item.name === options.resource);
+  const name = options.dataProviderName ?? resource?.provider?.dataProviderName ?? resource?.meta?.dataProviderName ?? 'default';
+  const raw = context.providers?.[name];
+  if (!raw) throw new HttpError('Data provider is unavailable', 400, undefined, { code: 'DATA_PROVIDER_REQUIRED' });
+  let source = sourceIds.get(raw);
+  if (source === undefined) {
+    source = `${runtime}:${++nextSource}`;
+    sourceIds.set(raw, source);
+  }
+  const explicit = snapshotListParams(definedOptions({ resource: options.resource, meta: options.meta }));
+  const metadata = context.getProviderMeta(options.resource, explicit.meta);
+  const params = snapshotListParams(definedOptions({ resource: options.resource, meta: metadata }));
+  if (options.contract) {
+    return { provider: contractProvider(raw, options.contract, { cache: options.fresh !== true }), source, meta: params.meta };
+  }
+  const provider: DataProvider = {
+    ...raw,
+    getApiUrl: () => raw.getApiUrl(),
+    create: input => raw.create(input),
+    update: input => raw.update(input),
+    deleteOne: input => raw.deleteOne(input),
+    getList: async input => {
+      const result = await raw.getList(input);
+      try {
+        return decodeListResult(snapshotPlainData(result), decodeBaseRecord);
+      } catch {
+        return rejectProviderResponse();
+      }
+    },
+    getOne: async input => {
+      const result = await raw.getOne(input);
+      try {
+        return decodeOneResult(snapshotPlainData(result), decodeBaseRecord);
+      } catch {
+        return rejectProviderResponse();
+      }
+    },
+    getMany: async input => {
+      if (!raw.getMany) {
+        const results = await Promise.all(input.ids.map(id => provider.getOne(snapshotOneParams({
+          resource: input.resource, id, ...definedOptions({ meta: input.meta }),
+        }))));
+        return { data: results.map(result => result.data) };
+      }
+      const result = await raw.getMany(input);
+      try {
+        return decodeManyResult(snapshotPlainData(result), decodeBaseRecord);
+      } catch {
+        return rejectProviderResponse();
+      }
+    },
+  };
+  return {
+    provider,
+    source,
+    meta: params.meta,
+  };
+}

package/src/reactive-projection.ts

@@ -0,0 +1,53 @@
+/** Project members without snapshotting reactive getters or changing the source object. */
+function project(source: object, replacement: object, omitted: readonly PropertyKey[]): object {
+  const hidden = new Set(omitted);
+  return new Proxy({}, {
+    get(_target, key): unknown {
+      if (Reflect.has(replacement, key)) return Reflect.get(replacement, key, replacement);
+      if (hidden.has(key)) return undefined;
+      return Reflect.get(source, key, source);
+    },
+    set(_target, key, value: unknown): boolean {
+      if (Reflect.has(replacement, key)) return Reflect.set(replacement, key, value, replacement);
+      return !hidden.has(key) && Reflect.set(source, key, value, source);
+    },
+    has(_target, key): boolean {
+      return Reflect.has(replacement, key) || !hidden.has(key) && Reflect.has(source, key);
+    },
+    ownKeys(): (string | symbol)[] {
+      return [...new Set([...Reflect.ownKeys(source).filter(key => !hidden.has(key)), ...Reflect.ownKeys(replacement)])];
+    },
+    getOwnPropertyDescriptor(_target, key): PropertyDescriptor | undefined {
+      const descriptor = Reflect.getOwnPropertyDescriptor(replacement, key)
+        ?? (hidden.has(key) ? undefined : Reflect.getOwnPropertyDescriptor(source, key));
+      return descriptor ? { ...descriptor, configurable: true } : undefined;
+    },
+  });
+}
+
+// Each retained member delegates to the source; replacement members delegate to their own object.
+export function replaceReactiveMembers<T extends object, R extends object>(source: T, replacement: R): Omit<T, keyof R> & R;
+export function replaceReactiveMembers(source: object, replacement: object): object {
+  return project(source, replacement, []);
+}
+
+type ReplaceUnion<T, R> = T extends object ? Omit<T, keyof R> & R : never;
+
+/** Preserve each result-state branch when projecting a discriminated runtime result. */
+export function replaceReactiveUnionMembers<T extends object, R extends object>(source: T, replacement: R): ReplaceUnion<T, R>;
+export function replaceReactiveUnionMembers(source: object, replacement: object): object {
+  return project(source, replacement, []);
+}
+
+/** Add only new members so source discriminants and their correlated values remain intact. */
+export function extendReactiveMembers<T extends object, R extends object>(
+  source: T, extension: R & Record<Extract<keyof R, keyof NoInfer<T>>, never>,
+): T & R;
+export function extendReactiveMembers(source: object, extension: object): object {
+  return project(source, extension, []);
+}
+
+export function omitReactiveMembers<T extends object, K extends keyof T>(source: T, omitted: readonly K[]): Omit<T, K>;
+export function omitReactiveMembers(source: object, omitted: readonly PropertyKey[]): object {
+  return project(source, {}, omitted);
+}

package/src/record-decoder.ts

@@ -0,0 +1,63 @@
+import { Type } from '@sinclair/typebox';
+import { createExactSchemaValidator } from './schema-validation';
+import { snapshotPlainData } from './plain-data';
+import { HttpError, type BaseRecord, type GetListResult, type GetOneResult, type GetManyResult, type CustomResult } from './types';
+
+export type RecordDecoder<T extends BaseRecord> = (value: unknown) => T;
+
+const record = Type.Record(Type.String(), Type.Unknown());
+const recordValidator = createExactSchemaValidator(record);
+const customValidator = createExactSchemaValidator(Type.Object({ data: Type.Unknown() }));
+const oneValidator = createExactSchemaValidator(Type.Object({ data: record }));
+const manyValidator = createExactSchemaValidator(Type.Object({ data: Type.Array(record) }));
+const listValidator = createExactSchemaValidator(Type.Object({
+  data: Type.Array(record),
+  total: Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }),
+}));
+
+function invalidResponse(writeMayHaveSucceeded = false): never {
+  throw new HttpError('Invalid provider response', 502, undefined, {
+    code: 'INVALID_PROVIDER_RESPONSE',
+    details: { phase: 'response', writeMayHaveSucceeded },
+  });
+}
+export { invalidResponse as rejectProviderResponse };
+
+export const decodeBaseRecord: RecordDecoder<BaseRecord> = value =>
+  recordValidator.Check(value) ? value : invalidResponse();
+
+function decodeRecord<T extends BaseRecord>(value: unknown, decode: RecordDecoder<T>, writeMayHaveSucceeded = false): T {
+  try {
+    return decode(value);
+  } catch {
+    return invalidResponse(writeMayHaveSucceeded);
+  }
+}
+
+function snapshotReceipt(value: unknown, writeMayHaveSucceeded = false): unknown {
+  try { return snapshotPlainData(value); }
+  catch { return invalidResponse(writeMayHaveSucceeded); }
+}
+
+export function decodeOneResult<T extends BaseRecord>(value: unknown, decode: RecordDecoder<T>, writeMayHaveSucceeded = false): GetOneResult<T> {
+  const snapshot = snapshotReceipt(value, writeMayHaveSucceeded);
+  if (!oneValidator.Check(snapshot)) return invalidResponse(writeMayHaveSucceeded);
+  return { data: decodeRecord(snapshot.data, decode, writeMayHaveSucceeded) };
+}
+
+export function decodeManyResult<T extends BaseRecord>(value: unknown, decode: RecordDecoder<T>, writeMayHaveSucceeded = false): GetManyResult<T> {
+  const snapshot = snapshotReceipt(value, writeMayHaveSucceeded);
+  if (!manyValidator.Check(snapshot)) return invalidResponse(writeMayHaveSucceeded);
+  return { data: snapshot.data.map(item => decodeRecord(item, decode, writeMayHaveSucceeded)) };
+}
+
+export function decodeListResult<T extends BaseRecord>(value: unknown, decode: RecordDecoder<T>): GetListResult<T> {
+  const snapshot = snapshotReceipt(value);
+  if (!listValidator.Check(snapshot)) return invalidResponse();
+  return { ...snapshot, data: snapshot.data.map(item => decodeRecord(item, decode)) };
+}
+
+export function decodeCustomResult(value: unknown, writeMayHaveSucceeded = false): CustomResult {
+  if (!customValidator.Check(value)) return invalidResponse(writeMayHaveSucceeded);
+  return { data: value.data };
+}

package/src/resource-binding.svelte.ts

@@ -0,0 +1,19 @@
+import { captureAdminContext } from './context.svelte';
+import { resolveResourceContract } from './resource-contract';
+import { definedReactiveOptions } from './defined-options';
+
+/** Bind a metadata-driven view to its declared runtime contract and provider route. */
+export function useResourceContract(resourceName: () => string) {
+  const context = captureAdminContext();
+  const definition = () => context.getResource(resourceName());
+  return definedReactiveOptions({
+    get resource() { return resolveResourceContract(definition()); },
+    get dataProviderName() {
+      const resource = definition();
+      const name = resource.provider?.dataProviderName ?? resource.meta?.dataProviderName ?? 'default';
+      context.getDataProvider(name);
+      return name;
+    },
+    get meta() { return context.getProviderMeta(resourceName()); },
+  });
+}