@svadmin/core 0.50.0 → 0.52.0

package/src/export-hooks.svelte.ts

@@ -0,0 +1,191 @@
+import { captureAdminContext } from './context.svelte';
+import { definedOptions } from './defined-options';
+import { HttpError } from './types';
+import { contractKey, parseContractRecord, type ResourceContract, type ContractSchemas, type ContractRecord } from './resource-contract';
+import type { ContractFilter, ContractSort } from './strict-hooks.svelte';
+import { captureQueryProvider, snapshotListParams } from './query-snapshot';
+import { decodeBaseRecord, decodeListResult } from './record-decoder';
+import { snapshotPlainData } from './plain-data';
+import { downloadData, type ExportFormat } from './export-format';
+
+export interface UseExportOptions<S extends ContractSchemas> {
+  resource: ResourceContract<S>;
+  mapData?: (item: NoInfer<ContractRecord<S>>) => Record<string, unknown>;
+  sorters?: ContractSort<NoInfer<ContractRecord<S>>>[];
+  filters?: ContractFilter<NoInfer<ContractRecord<S>>>[];
+  maxItemCount?: number;
+  pageSize?: number;
+  download?: boolean;
+  format?: ExportFormat;
+  meta?: Record<string, unknown>;
+  dataProviderName?: string;
+  onError?: (error: HttpError) => void | Promise<void>;
+}
+
+function cancelled(): HttpError {
+  return new HttpError('Export scope changed', 409, undefined, { code: 'EXPORT_CANCELLED' });
+}
+
+function invalidInput(): never {
+  throw new HttpError('Invalid export input', 422, undefined, { code: 'INVALID_RESOURCE_INPUT' });
+}
+
+function exportFailure(cause: unknown): HttpError {
+  let code: unknown;
+  try {
+    if (typeof cause === 'object' && cause !== null) code = Object.getOwnPropertyDescriptor(cause, 'code')?.value;
+  } catch {
+    // Revoked proxies and accessor-backed errors are not trusted diagnostic sources.
+  }
+  if (code === 'INVALID_RESOURCE_INPUT') {
+    return new HttpError('Invalid export input', 422, undefined, { code: 'INVALID_RESOURCE_INPUT' });
+  }
+  if (code === 'INVALID_PROVIDER_RESPONSE') {
+    return new HttpError('Invalid provider response', 502, undefined, { code: 'INVALID_PROVIDER_RESPONSE' });
+  }
+  return new HttpError('Export failed', 500, undefined, { code: 'EXPORT_FAILED' });
+}
+
+/** Export only records proven by the bound business schema, within one captured scope. */
+export function useExport<S extends ContractSchemas>(options: UseExportOptions<S>) {
+  const context = captureAdminContext();
+  contractKey(options.resource);
+  let isLoading = $state(false);
+  let error = $state<HttpError | null>(null);
+  let mounted = true;
+
+  function captureScope() {
+    const contract = options.resource;
+    const key = contractKey(contract);
+    const captured = captureQueryProvider(context, {
+      resource: contract.name, contract,
+      ...definedOptions({ dataProviderName: options.dataProviderName, meta: options.meta }),
+    });
+    return {
+      contract, ...captured,
+      key: JSON.stringify([key, captured.source, context.tenantCacheKey?.__svadminTenant, captured.meta]),
+    };
+  }
+  type Scope = ReturnType<typeof captureScope>;
+  let current: { token: object; scope: Scope; promise: Promise<ContractRecord<S>[]> } | undefined;
+
+  function isActive(token: object, scope: Scope): boolean {
+    if (!mounted || current?.token !== token) return false;
+    try { return captureScope().key === scope.key; }
+    catch { return false; }
+  }
+
+  let initialized = false;
+  let previousScope: string | undefined;
+  $effect(() => {
+    let nextScope: string | undefined;
+    try { nextScope = captureScope().key; }
+    catch { nextScope = undefined; }
+    if (initialized && previousScope !== nextScope) {
+      current = undefined;
+      isLoading = false;
+      error = null;
+    }
+    previousScope = nextScope;
+    initialized = true;
+  });
+  $effect(() => () => {
+    mounted = false;
+    current = undefined;
+  });
+
+  function report(failure: HttpError, handler: UseExportOptions<S>['onError']): void {
+    error = failure;
+    try {
+      void Promise.resolve(handler?.(failure)).catch(() => {
+        // Async notification failures must not become unhandled rejections.
+      });
+    }
+    catch {
+      // Consumer callback failures must not replace the sanitized export failure.
+    }
+  }
+
+  function triggerExport(): Promise<ContractRecord<S>[]> {
+    if (!mounted) return Promise.reject(cancelled());
+    let onError: UseExportOptions<S>['onError'];
+    try {
+      const scope = captureScope();
+      if (current?.scope.key === scope.key) return current.promise;
+      previousScope = scope.key;
+      initialized = true;
+      const batchSize = options.pageSize ?? 20;
+      const maxItems = options.maxItemCount ?? Infinity;
+      const format = options.format ?? 'csv';
+      const download = options.download ?? true;
+      const mapData = options.mapData;
+      onError = options.onError;
+      if (!Number.isSafeInteger(batchSize) || batchSize <= 0 ||
+          (maxItems !== Infinity && (!Number.isSafeInteger(maxItems) || maxItems < 0)) ||
+          !['csv', 'json', 'xlsx'].includes(format) || typeof download !== 'boolean' ||
+          (mapData !== undefined && typeof mapData !== 'function') ||
+          (onError !== undefined && typeof onError !== 'function')) invalidInput();
+      const handler = onError;
+      const params = snapshotListParams({
+        resource: scope.contract.name,
+        ...definedOptions({
+          pagination: { current: 1, pageSize: batchSize },
+          filters: options.filters, sorters: options.sorters, meta: scope.meta,
+        }),
+      });
+      const token = {};
+      const ensureActive = () => { if (!isActive(token, scope)) throw cancelled(); };
+      isLoading = true;
+      error = null;
+      // Install the invocation before transport code or user callbacks can re-enter it.
+      const promise = Promise.resolve().then(async () => {
+        try {
+          ensureActive();
+          const records: ContractRecord<S>[] = [];
+          let page = 1;
+          while (records.length < maxItems) {
+            const response = await scope.provider.getList(snapshotListParams({
+              ...params, pagination: { current: page, pageSize: batchSize },
+            }));
+            ensureActive();
+            const result = decodeListResult(response, value => parseContractRecord(scope.contract, value));
+            records.push(...result.data.slice(0, maxItems - records.length));
+            if (result.data.length < batchSize || records.length >= result.total) break;
+            page++;
+          }
+          ensureActive();
+          const mapped = mapData ? records.map(record => {
+            ensureActive();
+            // Mapping receives its own checked copy, never the records returned to the caller.
+            return decodeBaseRecord(snapshotPlainData(mapData(parseContractRecord(scope.contract, record))));
+          }) : records;
+          ensureActive();
+          if (download && mapped.length > 0) downloadData(mapped, scope.contract.name, format);
+          return records;
+        } catch (cause) {
+          if (!isActive(token, scope)) throw cancelled();
+          const failure = exportFailure(cause);
+          current = undefined;
+          isLoading = false;
+          report(failure, handler);
+          throw failure;
+        } finally {
+          if (current?.token === token) {
+            current = undefined;
+            isLoading = false;
+          }
+        }
+      });
+      current = { token, scope, promise };
+      return promise;
+    } catch (cause) {
+      current = undefined;
+      isLoading = false;
+      const failure = exportFailure(cause);
+      report(failure, typeof onError === 'function' ? onError : undefined);
+      return Promise.reject(failure);
+    }
+  }
+
+  return { triggerExport, get isLoading() { return isLoading; }, get error() { return error; } };
+}

package/src/feature-gate-contract.ts

@@ -0,0 +1,53 @@
+import { Type } from '@sinclair/typebox';
+import { checkExact } from './schema-validation';
+import { snapshotPlainData } from './plain-data';
+import { HttpError } from './types';
+import type { FeatureGateConfig, FeatureGateUser } from './permissions.svelte';
+
+const name = Type.String({ minLength: 1, pattern: '\\S' });
+const constraints = {
+  roles: Type.Optional(Type.Array(name)),
+  permissions: Type.Optional(Type.Array(name)),
+};
+const configuration = Type.Union([
+  Type.Object(constraints, { additionalProperties: false }),
+  Type.Object({
+    ...constraints,
+    minRole: name,
+    roleHierarchy: Type.Array(name, { minItems: 1, uniqueItems: true }),
+  }, { additionalProperties: false }),
+]);
+const user = Type.Object({
+  role: name,
+  permissions: Type.Array(name),
+}, { additionalProperties: false });
+
+export function snapshotFeatureGateConfig(value: unknown): FeatureGateConfig {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(configuration, candidate) &&
+        (!('minRole' in candidate) || candidate.roleHierarchy.includes(candidate.minRole))) {
+      if (candidate.roles) Object.freeze(candidate.roles);
+      if (candidate.permissions) Object.freeze(candidate.permissions);
+      if ('roleHierarchy' in candidate) Object.freeze(candidate.roleHierarchy);
+      return Object.freeze(candidate);
+    }
+  } catch {
+    // Configuration errors never retain caller data or reflection diagnostics.
+  }
+  throw new HttpError('Invalid feature gate configuration', 422, undefined, { code: 'INVALID_FEATURE_GATE_CONFIG' });
+}
+
+/** Invalid presentation hints deny visibility instead of throwing during rendering. */
+export function parseFeatureGateUser(value: unknown): FeatureGateUser | undefined {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(user, candidate)) {
+      Object.freeze(candidate.permissions);
+      return Object.freeze(candidate);
+    }
+  } catch {
+    // Never invoke user getters or custom permission-collection methods.
+  }
+  return undefined;
+}

package/src/hook-utils.svelte.ts

@@ -1,41 +1,25 @@
+import { definedOptions } from './defined-options';
 // Hook Utilities — shared reactive helpers for all hooks
 // Uses Svelte 5 runes ($state, $effect) for automatic lifecycle management
 
 import { useQueryClient } from '@tanstack/svelte-query';
-import type { LiveProvider, LiveEvent, LiveMode } from './live.svelte';
 import { captureAdminContext } from './context.svelte';
 import type { AdminContextAccessor } from './context.svelte';
-import { dataQueryMatches } from './query-keys';
+import { createCheckedLiveSubscription, type LiveSubscriptionParams } from './live-subscription.svelte';
+export type { LiveSubscriptionParams } from './live-subscription.svelte';
 import { notifyWithProvider } from './notification.svelte';
 import type { NotificationProvider } from './types';
+import { handleAuthError } from './auth-hooks.svelte';
+import { untrack } from 'svelte';
 
 // ─── Auth Error Delegate ────────────────────────────────────────
 // Delegate auth errors to authProvider.onError() — refine pattern
 
 export async function checkError(
   error: unknown,
-  adminContext: AdminContextAccessor = captureAdminContext(),
+  adminContext: AdminContextAccessor=captureAdminContext(),
 ): Promise<void> {
-  try {
-    const authProvider = adminContext.authProvider;
-    if (authProvider?.onError) {
-      const result = await authProvider.onError(error);
-      if (!result) return;
-      if (result.logout) {
-        await authProvider.logout?.();
-        await adminContext.navigate(result.redirectTo ?? '/login');
-      } else if (result.redirectTo) {
-        await adminContext.navigate(result.redirectTo);
-      }
-      return;
-    }
-    if (error && typeof error === 'object' && 'statusCode' in error) {
-      const status = (error as { statusCode: number }).statusCode;
-      if (status === 401) {
-        await adminContext.navigate('/login');
-      }
-    }
-  } catch { /* auth check failed silently */ }
+  await untrack(() => handleAuthError(error,adminContext));
 }
 
 // ─── Overtime Tracker ───────────────────────────────────────────
@@ -52,21 +36,21 @@ export interface OvertimeResult {
 
 export function createOvertimeTracker(
   isLoadingFn: () => boolean,
-  options: OvertimeOptions = {},
+  options: OvertimeOptions={},
 ): OvertimeResult {
-  const { interval = 1000, onInterval } = options;
-  let elapsedTime = $state(0);
+  const { interval=1000,onInterval }=options;
+  let elapsedTime=$state(0);
 
   $effect(() => {
-    if (isLoadingFn()) {
-      elapsedTime = 0;
-      const timer = setInterval(() => {
-        elapsedTime += interval;
+    if(isLoadingFn()) {
+      elapsedTime=0;
+      const timer=setInterval(() => {
+        elapsedTime+=interval;
         onInterval?.(elapsedTime);
-      }, interval);
+      },interval);
       return () => clearInterval(timer);
     } else {
-      elapsedTime = 0;
+      elapsedTime=0;
     }
   });
 
@@ -78,63 +62,23 @@ export function createOvertimeTracker(
 // ─── Live Subscription ──────────────────────────────────────────
 // Auto-subscribes to realtime events, invalidates queries on 'auto' mode
 
-export interface LiveSubscriptionParams {
-  resource: string;
-  liveProvider?: LiveProvider;
-  liveMode?: LiveMode;
-  onLiveEvent?: (event: LiveEvent) => void;
-  liveParams?: Record<string, unknown>;
-  enabled?: boolean;
-  dataProviderName?: string;
-}
-
 export function createLiveSubscription(paramsFn: () => LiveSubscriptionParams): void {
-  const queryClient = useQueryClient();
-  const adminContext = captureAdminContext();
-
-  $effect(() => {
-    const params = paramsFn();
-    const liveProvider = params.liveProvider;
-    const liveMode = params.liveMode ?? 'off';
-    const enabled = params.enabled ?? true;
-
-    if (!liveProvider || liveMode === 'off' || !enabled) return;
-
-    let unsubscribe: (() => void) | undefined;
-    try {
-      unsubscribe = liveProvider.subscribe({
-        resource: params.resource,
-        liveParams: params.liveParams,
-        callback: (event: LiveEvent) => {
-          params.onLiveEvent?.(event);
-          if (liveMode === 'auto') {
-            const matcher = adminContext.queryKeyMatcher(params.resource, params.dataProviderName);
-            queryClient.invalidateQueries({
-              predicate: (q) => dataQueryMatches(q.queryKey, { ...matcher, resource: params.resource }),
-            });
-          }
-        },
-      });
-    } catch (e) {
-      console.warn('[svadmin] LiveProvider.subscribe failed:', e);
-      return;
-    }
-    return unsubscribe;
-  });
+  const queryClient=useQueryClient();
+  createCheckedLiveSubscription(paramsFn,queryClient);
 }
 
 // ─── Notification Helpers ───────────────────────────────────────
 
-export type NotificationConfig =
-  | string
-  | false
-  | ((data?: unknown, values?: unknown, resource?: string) => {
-      message: string;
-      description?: string;
-      type?: 'success' | 'error';
-      key?: string;
-    })
-  | undefined;
+export type NotificationConfig=
+  |string
+  |false
+  |((data?: unknown,values?: unknown,resource?: string) => {
+    message: string;
+    description?: string;
+    type?: 'success'|'error';
+    key?: string;
+  })
+  |undefined;
 
 export interface SuccessNotificationRequest {
   config: NotificationConfig;
@@ -142,7 +86,7 @@ export interface SuccessNotificationRequest {
   data?: unknown;
   values?: unknown;
   resource?: string;
-  provider?: NotificationProvider | null;
+  provider?: NotificationProvider|null;
 }
 
 export interface ErrorNotificationRequest {
@@ -150,40 +94,44 @@ export interface ErrorNotificationRequest {
   defaultMessage: string;
   error?: unknown;
   resource?: string;
-  provider?: NotificationProvider | null;
+  provider?: NotificationProvider|null;
 }
 
 export function fireSuccessNotification(request: SuccessNotificationRequest): void {
-  const { config, defaultMessage, data, values, resource, provider } = request;
-  if (config === false) return;
-  if (!config && !defaultMessage) return;
-  if (typeof config === 'function') {
-    const result = config(data, values, resource);
+  const { config,defaultMessage,data,values,resource,provider }=request;
+  if(config===false) return;
+  if(!config&&!defaultMessage) return;
+  if(typeof config==='function') {
+    const result=config(data,values,resource);
     notifyWithProvider({
       type: 'success',
       message: result.message,
-      description: result.description,
-      key: result.key,
-    }, provider);
+      ...definedOptions({
+        description: result.description,
+        key: result.key,
+      }),
+    },provider);
     return;
   }
-  notifyWithProvider({ type: 'success', message: config || defaultMessage }, provider);
+  notifyWithProvider({ type: 'success',message: config||defaultMessage },provider);
 }
 
 export function fireErrorNotification(request: ErrorNotificationRequest): void {
-  const { config, defaultMessage, error, resource, provider } = request;
-  if (config === false) return;
-  if (!config && !defaultMessage) return;
-  if (typeof config === 'function') {
-    const result = config(error, undefined, resource);
+  const { config,defaultMessage,error,resource,provider }=request;
+  if(config===false) return;
+  if(!config&&!defaultMessage) return;
+  if(typeof config==='function') {
+    const result=config(error,undefined,resource);
     notifyWithProvider({
       type: 'error',
       message: result.message,
-      description: result.description,
-      key: result.key,
-    }, provider);
+      ...definedOptions({
+        description: result.description,
+        key: result.key,
+      }),
+    },provider);
     return;
   }
-  const errMsg = error instanceof Error ? error.message : String(error ?? '');
-  notifyWithProvider({ type: 'error', message: config || `${defaultMessage}${errMsg ? ': ' + errMsg : ''}` }, provider);
+  const errMsg=error instanceof Error? error.message:String(error??'');
+  notifyWithProvider({ type: 'error',message: config||`${defaultMessage}${errMsg? ': '+errMsg:''}` },provider);
 }