@svadmin/core 0.0.3 → 0.3.0

package/src/live.ts

@@ -1,10 +1,10 @@
-// LiveProvider — Real-time subscription interface + useLive hook
+// LiveProvider — Real-time subscription interface + hooks
 
 import { useQueryClient } from '@tanstack/svelte-query';
 
-export interface LiveProvider {
-  subscribe(params: { resource: string; callback: (event: LiveEvent) => void }): () => void;
-}
+// ─── Types ──────────────────────────────────────────────────────
+
+export type LiveMode = 'auto' | 'manual' | 'off';
 
 export interface LiveEvent {
   type: 'INSERT' | 'UPDATE' | 'DELETE';
@@ -12,17 +12,69 @@ export interface LiveEvent {
   payload: Record<string, unknown>;
 }
 
-// Hook to auto-invalidate queries on real-time changes
-export function useLive(liveProvider: LiveProvider, resource: string): void {
+export interface LiveProvider {
+  subscribe(params: { resource: string; callback: (event: LiveEvent) => void }): () => void;
+  unsubscribe?(params: { resource: string }): void;
+  publish?(event: LiveEvent): void;
+}
+
+// ─── useLive — auto-invalidate queries on real-time events ──────
+
+export function useLive(
+  liveProvider: LiveProvider,
+  resource: string,
+  options?: { liveMode?: LiveMode; onLiveEvent?: (event: LiveEvent) => void }
+): void {
   const queryClient = useQueryClient();
+  const liveMode = options?.liveMode ?? 'auto';
+
+  if (liveMode === 'off') return;
 
   $effect(() => {
     const unsubscribe = liveProvider.subscribe({
       resource,
-      callback: () => {
-        queryClient.invalidateQueries({ queryKey: [resource] });
+      callback: (event) => {
+        options?.onLiveEvent?.(event);
+        if (liveMode === 'auto') {
+          queryClient.invalidateQueries({ queryKey: [resource] });
+        }
       },
     });
     return unsubscribe;
   });
 }
+
+// ─── useSubscription — manual channel subscription ──────────────
+
+interface UseSubscriptionOptions {
+  resource: string;
+  liveProvider: LiveProvider;
+  onLiveEvent: (event: LiveEvent) => void;
+  enabled?: boolean;
+}
+
+export function useSubscription(options: UseSubscriptionOptions): void {
+  const { resource, liveProvider, onLiveEvent, enabled = true } = options;
+
+  if (!enabled) return;
+
+  $effect(() => {
+    const unsubscribe = liveProvider.subscribe({
+      resource,
+      callback: onLiveEvent,
+    });
+    return unsubscribe;
+  });
+}
+
+// ─── usePublish — publish custom events ─────────────────────────
+
+export function usePublish(liveProvider: LiveProvider) {
+  return (event: LiveEvent) => {
+    if (liveProvider.publish) {
+      liveProvider.publish(event);
+    } else {
+      console.warn('[svadmin] LiveProvider.publish() not implemented');
+    }
+  };
+}

package/src/mutation-hooks.svelte.ts

@@ -0,0 +1,301 @@
+import { createMutation, useQueryClient } from '@tanstack/svelte-query';
+import { getAdminOptions } from './options';
+import { getDataProviderForResource } from './context';
+import { useParsed } from './useParsed';
+import { audit } from './audit';
+import { UndoError } from './types';
+import type { BaseRecord, HttpError, CreateParams, UpdateParams, DeleteParams, KnownResources } from './types';
+import { createOvertimeTracker, fireSuccessNotification, fireErrorNotification } from './hook-utils.svelte';
+import type { NotificationConfig, OvertimeOptions } from './hook-utils.svelte';
+import { toast } from './toast.svelte';
+
+// ─── useCreate ─────────────────────────────────────────────────
+
+export interface UseCreateOptions {
+  resource?: KnownResources;
+  mutationOptions?: Record<string, unknown>;
+  overtimeOptions?: OvertimeOptions;
+}
+
+export interface UseCreateMutateParams<TVariables> {
+  resource?: KnownResources;
+  variables: TVariables;
+  successNotification?: NotificationConfig;
+  errorNotification?: NotificationConfig;
+  invalidates?: string[] | false;
+  meta?: Record<string, unknown>;
+  dataProviderName?: string;
+}
+
+export function useCreate<TData extends BaseRecord = BaseRecord, TError = HttpError, TVariables = Record<string, unknown>>(options: UseCreateOptions = {}) {
+  const parsed = useParsed();
+  const defaultResource = options.resource ?? parsed.resource ?? '';
+  const adminOptions = getAdminOptions();
+  const queryClient = useQueryClient();
+
+  let isMutating = $state(false);
+  const overtime = createOvertimeTracker(() => isMutating, options.overtimeOptions ?? adminOptions.overtime);
+
+  const mutation = createMutation<
+    { data: TData },
+    TError,
+    UseCreateMutateParams<TVariables>
+  >(() => ({
+    mutationFn: async (params) => {
+      isMutating = true;
+      const resName = params.resource ?? defaultResource;
+      const provider = getDataProviderForResource(resName, params.dataProviderName);
+      try {
+        return await provider.create<TData, TVariables>({
+          resource: resName,
+          variables: params.variables,
+          meta: params.meta,
+        });
+      } finally {
+        isMutating = false;
+      }
+    },
+    onSuccess: (data, params) => {
+      const resName = params.resource ?? defaultResource;
+      if (params.invalidates !== false) {
+        queryClient.invalidateQueries({ queryKey: [resName] });
+      }
+      fireSuccessNotification(params.successNotification, 'Created successfully', data.data, params.variables, resName);
+      audit({ action: 'create', resource: resName, recordId: String(data.data.id) });
+    },
+    onError: (error, params) => {
+      fireErrorNotification(params.errorNotification, 'Create failed', error);
+    },
+  }));
+
+  return { mutation, get overtime() { return overtime; } };
+}
+
+// ─── useUpdate ─────────────────────────────────────────────────
+
+export interface UseUpdateOptions {
+  resource?: KnownResources;
+  id?: string | number;
+  mutationMode?: 'pessimistic' | 'optimistic' | 'undoable';
+  undoableTimeout?: number;
+  mutationOptions?: Record<string, unknown>;
+  overtimeOptions?: OvertimeOptions;
+}
+
+export interface UseUpdateMutateParams<TVariables> {
+  resource?: KnownResources;
+  id?: string | number;
+  variables: TVariables;
+  successNotification?: NotificationConfig;
+  errorNotification?: NotificationConfig;
+  invalidates?: string[] | false;
+  meta?: Record<string, unknown>;
+  dataProviderName?: string;
+  onCancel?: () => void;
+  optimisticUpdateMap?: {
+    detail?: (previous: unknown, variables: TVariables, id?: string | number) => unknown;
+    list?: (previous: unknown, variables: TVariables, id?: string | number) => unknown;
+  };
+}
+
+export function useUpdate<TData extends BaseRecord = BaseRecord, TError = HttpError, TVariables = Record<string, unknown>>(options: UseUpdateOptions = {}) {
+  const parsed = useParsed();
+  const defaultResource = options.resource ?? parsed.resource ?? '';
+  const defaultId = options.id ?? parsed.id;
+  const adminOptions = getAdminOptions();
+  const queryClient = useQueryClient();
+  const mutationMode = options.mutationMode ?? adminOptions.mutationMode ?? 'pessimistic';
+  const undoableTimeout = options.undoableTimeout ?? adminOptions.undoableTimeout ?? 5000;
+
+  let isMutating = $state(false);
+  const overtime = createOvertimeTracker(() => isMutating, options.overtimeOptions ?? adminOptions.overtime);
+
+  const mutation = createMutation<
+    { data: TData },
+    TError,
+    UseUpdateMutateParams<TVariables>
+  >(() => ({
+    mutationFn: async (params) => {
+      isMutating = true;
+      const resName = params.resource ?? defaultResource;
+      const targetId = params.id ?? defaultId;
+      if (targetId == null) throw new Error('useUpdate requires an id');
+
+      if (mutationMode === 'undoable') {
+        await new Promise<void>((resolve, reject) => {
+          toast.undoable('Action can be undone', undoableTimeout, () => {
+            params.onCancel?.();
+            reject(new UndoError());
+          }, resolve);
+        });
+      }
+
+      const provider = getDataProviderForResource(resName, params.dataProviderName);
+      try {
+        return await provider.update<TData, TVariables>({
+          resource: resName,
+          id: targetId,
+          variables: params.variables,
+          meta: params.meta,
+        });
+      } finally {
+        isMutating = false;
+      }
+    },
+    onMutate: async (params) => {
+      if (mutationMode === 'pessimistic') return undefined;
+      const resName = params.resource ?? defaultResource;
+      const targetId = params.id ?? defaultId;
+      
+      await queryClient.cancelQueries({ queryKey: [resName] });
+      const previousDetail = queryClient.getQueryData([resName, 'one', targetId]);
+      const previousList = queryClient.getQueriesData({ queryKey: [resName, 'list'] });
+      
+      const updater = params.optimisticUpdateMap;
+      if (updater?.detail) {
+        queryClient.setQueryData([resName, 'one', targetId], (old: unknown) => updater.detail!(old, params.variables, targetId));
+      } else {
+        queryClient.setQueryData([resName, 'one', targetId], (old: Record<string, unknown> | undefined) => old ? { ...old, ...params.variables } : old);
+      }
+      
+      if (updater?.list) {
+        queryClient.setQueriesData({ queryKey: [resName, 'list'] }, (old: unknown) => updater.list!(old, params.variables, targetId));
+      } else {
+        queryClient.setQueriesData({ queryKey: [resName, 'list'] }, (old: unknown) => {
+          if (!old || typeof old !== 'object' || !('data' in old)) return old;
+          const o = old as { data: Record<string, unknown>[] };
+          return { ...o, data: o.data.map((item) => String(item.id) === String(targetId) ? { ...item, ...params.variables } : item) };
+        });
+      }
+
+      return { previousDetail, previousList };
+    },
+    onSuccess: (data, params) => {
+      const resName = params.resource ?? defaultResource;
+      const targetId = params.id ?? defaultId;
+      if (params.invalidates !== false) {
+        queryClient.invalidateQueries({ queryKey: [resName] });
+      }
+      fireSuccessNotification(params.successNotification, 'Updated successfully', data.data, params.variables, resName);
+      audit({ action: 'update', resource: resName, recordId: String(targetId) });
+    },
+    onError: (error, params, context: unknown) => {
+      const resName = params.resource ?? defaultResource;
+      const targetId = params.id ?? defaultId;
+      const ctx = context as { previousDetail?: unknown; previousList?: [unknown, unknown][] } | undefined;
+      if (ctx?.previousDetail) queryClient.setQueryData([resName, 'one', targetId], ctx.previousDetail);
+      if (ctx?.previousList) {
+        ctx.previousList.forEach(([qk, data]) => queryClient.setQueryData(qk as string[], data));
+      }
+      if (error instanceof UndoError) return;
+      fireErrorNotification(params.errorNotification, 'Update failed', error);
+    },
+  }));
+
+  return { mutation, get overtime() { return overtime; } };
+}
+
+// ─── useDelete ─────────────────────────────────────────────────
+
+export interface UseDeleteOptions {
+  resource?: KnownResources;
+  id?: string | number;
+  mutationMode?: 'pessimistic' | 'optimistic' | 'undoable';
+  undoableTimeout?: number;
+  mutationOptions?: Record<string, unknown>;
+  overtimeOptions?: OvertimeOptions;
+}
+
+export interface UseDeleteMutateParams<TVariables> {
+  resource?: KnownResources;
+  id?: string | number;
+  variables?: TVariables;
+  successNotification?: NotificationConfig;
+  errorNotification?: NotificationConfig;
+  invalidates?: string[] | false;
+  meta?: Record<string, unknown>;
+  dataProviderName?: string;
+  onCancel?: () => void;
+}
+
+export function useDelete<TData extends BaseRecord = BaseRecord, TError = HttpError, TVariables = Record<string, unknown>>(options: UseDeleteOptions = {}) {
+  const parsed = useParsed();
+  const defaultResource = options.resource ?? parsed.resource ?? '';
+  const defaultId = options.id ?? parsed.id;
+  const adminOptions = getAdminOptions();
+  const queryClient = useQueryClient();
+  const mutationMode = options.mutationMode ?? adminOptions.mutationMode ?? 'pessimistic';
+  const undoableTimeout = options.undoableTimeout ?? adminOptions.undoableTimeout ?? 5000;
+
+  let isMutating = $state(false);
+  const overtime = createOvertimeTracker(() => isMutating, options.overtimeOptions ?? adminOptions.overtime);
+
+  const mutation = createMutation<
+    { data: TData },
+    TError,
+    UseDeleteMutateParams<TVariables>
+  >(() => ({
+    mutationFn: async (params) => {
+      isMutating = true;
+      const resName = params.resource ?? defaultResource;
+      const targetId = params.id ?? defaultId;
+      if (targetId == null) throw new Error('useDelete requires an id');
+
+      if (mutationMode === 'undoable') {
+        await new Promise<void>((resolve, reject) => {
+          toast.undoable('Action can be undone', undoableTimeout, () => {
+            params.onCancel?.();
+            reject(new UndoError());
+          }, resolve);
+        });
+      }
+
+      const provider = getDataProviderForResource(resName, params.dataProviderName);
+      try {
+        return await provider.deleteOne<TData, TVariables>({
+          resource: resName,
+          id: targetId,
+          variables: params.variables,
+          meta: params.meta,
+        });
+      } finally {
+        isMutating = false;
+      }
+    },
+    onMutate: async (params) => {
+      if (mutationMode === 'pessimistic') return undefined;
+      const resName = params.resource ?? defaultResource;
+      const targetId = params.id ?? defaultId;
+      
+      await queryClient.cancelQueries({ queryKey: [resName] });
+      const previousList = queryClient.getQueriesData({ queryKey: [resName, 'list'] });
+      
+      queryClient.setQueriesData({ queryKey: [resName, 'list'] }, (old: unknown) => {
+        if (!old || typeof old !== 'object' || !('data' in old)) return old;
+        const o = old as { data: Record<string, unknown>[] };
+        return { ...o, data: o.data.filter((item) => String(item.id) !== String(targetId)) };
+      });
+
+      return { previousList };
+    },
+    onSuccess: (data, params) => {
+      const resName = params.resource ?? defaultResource;
+      const targetId = params.id ?? defaultId;
+      if (params.invalidates !== false) {
+        queryClient.invalidateQueries({ queryKey: [resName] });
+      }
+      fireSuccessNotification(params.successNotification, 'Deleted successfully', data.data, params.variables, resName);
+      audit({ action: 'delete', resource: resName, recordId: String(targetId) });
+    },
+    onError: (error, params, context: unknown) => {
+      const ctx = context as { previousList?: [unknown, unknown][] } | undefined;
+      if (ctx?.previousList) {
+        ctx.previousList.forEach(([qk, data]) => queryClient.setQueryData(qk as string[], data));
+      }
+      if (error instanceof UndoError) return;
+      fireErrorNotification(params.errorNotification, 'Delete failed', error);
+    },
+  }));
+
+  return { mutation, get overtime() { return overtime; } };
+}

package/src/options.ts

@@ -0,0 +1,95 @@
+// Global admin options — centralized configuration
+// Provides defaults that individual hooks can override
+
+import { setContext, getContext } from 'svelte';
+import type { MutationMode } from './types';
+
+export type InvalidateScope = 'all' | 'resourceAll' | 'detail' | 'list' | false | string[];
+
+const OPTIONS_KEY = Symbol('admin-options');
+
+export interface TextTransformers {
+  humanize: (text: string) => string;
+  plural: (text: string) => string;
+  singular: (text: string) => string;
+}
+
+export interface OvertimeConfig {
+  enabled?: boolean;
+  interval?: number;
+  onInterval?: (elapsedInterval: number, context?: { resource?: string; action?: string; id?: string | number }) => void;
+}
+
+export interface AdminOptions {
+  mutationMode?: MutationMode;
+  warnWhenUnsavedChanges?: boolean;
+  syncWithLocation?: boolean;
+  liveMode?: 'auto' | 'manual' | 'off';
+  disableServerSideValidation?: boolean;
+  undoableTimeout?: number;
+  // v0.2.26 additions
+  textTransformers?: Partial<TextTransformers>;
+  redirect?: {
+    afterCreate?: 'list' | 'edit' | 'show' | false;
+    afterEdit?: 'list' | 'edit' | 'show' | false;
+    afterClone?: 'list' | 'edit' | 'show' | false;
+  };
+  reactQuery?: {
+    staleTime?: number;
+    cacheTime?: number;
+    refetchOnWindowFocus?: boolean;
+  };
+  title?: {
+    text?: string;
+    icon?: string;
+  };
+  overtime?: OvertimeConfig;
+  breadcrumb?: false | 'default';
+  disableRouteChangeHandler?: boolean;
+  onLiveEvent?: (event: unknown) => void;
+  menuItems?: (items: { name: string; route: string; label: string; icon?: string; parentName?: string; order?: number }[]) => { name: string; route: string; label: string; icon?: string; parentName?: string; order?: number }[];
+}
+
+const defaultTextTransformers: TextTransformers = {
+  humanize: (text: string) => text.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase()),
+  plural: (text: string) => text.endsWith('s') ? text : text + 's',
+  singular: (text: string) => text.endsWith('s') ? text.slice(0, -1) : text,
+};
+
+const defaultOptions: AdminOptions = {
+  mutationMode: 'pessimistic',
+  warnWhenUnsavedChanges: false,
+  syncWithLocation: false,
+  liveMode: 'auto',
+  disableServerSideValidation: false,
+  undoableTimeout: 5000,
+  textTransformers: defaultTextTransformers,
+  redirect: { afterCreate: 'list', afterEdit: 'list', afterClone: 'list' },
+  breadcrumb: 'default',
+  disableRouteChangeHandler: false,
+};
+
+export function setAdminOptions(options: AdminOptions): void {
+  const merged = {
+    ...defaultOptions,
+    ...options,
+    textTransformers: { ...defaultTextTransformers, ...options.textTransformers },
+  };
+  setContext(OPTIONS_KEY, merged);
+}
+
+export function getAdminOptions(): AdminOptions {
+  try {
+    const opts = getContext<AdminOptions>(OPTIONS_KEY);
+    return opts ?? defaultOptions;
+  } catch {
+    return defaultOptions;
+  }
+}
+
+/** Get the resolved text transformers (always returns full set) */
+export function getTextTransformers(): TextTransformers {
+  const opts = getAdminOptions();
+  return { ...defaultTextTransformers, ...opts.textTransformers };
+}
+

package/src/permissions.test.ts

@@ -0,0 +1,55 @@
+// Unit tests for permissions module
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { setAccessControl, canAccess, canAccessAsync } from './permissions';
+import type { Action } from './permissions';
+
+describe('permissions', () => {
+  beforeEach(() => {
+    // Reset to no access control (allow all)
+    setAccessControl((() => ({ can: true })) as Parameters<typeof setAccessControl>[0]);
+  });
+
+  test('canAccess returns { can: true } when no deny rules', () => {
+    const result = canAccess('posts', 'list' as Action);
+    expect(result.can).toBe(true);
+  });
+
+  test('canAccess respects deny rule', () => {
+    setAccessControl((_resource: string, action: Action) => {
+      if (action === 'delete') return { can: false, reason: 'Denied' };
+      return { can: true };
+    });
+    expect(canAccess('posts', 'delete')).toEqual({ can: false, reason: 'Denied' });
+    expect(canAccess('posts', 'list')).toEqual({ can: true });
+  });
+
+  test('canAccess returns { can: true } when async fn used sync', () => {
+    setAccessControl(async () => ({ can: false }));
+    // Should warn and default to { can: true }
+    const result = canAccess('posts', 'list');
+    expect(result.can).toBe(true);
+  });
+
+  test('canAccessAsync resolves with allowed status', async () => {
+    setAccessControl(async () => ({ can: true }));
+    const result = await canAccessAsync('posts', 'edit');
+    expect(result.can).toBe(true);
+  });
+
+  test('canAccessAsync resolves with denied status', async () => {
+    setAccessControl(async (_r: string, _a: Action) => ({ can: false, reason: 'No permission' }));
+    const result = await canAccessAsync('users', 'delete');
+    expect(result.can).toBe(false);
+    expect(result.reason).toBe('No permission');
+  });
+
+  test('resource-specific rules', () => {
+    setAccessControl((resource: string, action: Action) => {
+      if (resource === 'users' && action === 'delete') return { can: false, reason: 'Cannot delete users' };
+      return { can: true };
+    });
+    expect(canAccess('users', 'delete').can).toBe(false);
+    expect(canAccess('users', 'list').can).toBe(true);
+    expect(canAccess('posts', 'delete').can).toBe(true);
+  });
+});