@svadmin/core 0.50.0 → 0.52.0

package/src/toast.svelte.ts

@@ -1,4 +1,5 @@
-export type ToastType = 'success' | 'error' | 'info' | 'warning' | 'undoable';
+import { definedOptions } from './defined-options';
+export type ToastType='success'|'error'|'info'|'warning'|'undoable';
 
 export interface ToastItem {
   id: number;
@@ -10,69 +11,69 @@ export interface ToastItem {
   onTimeout?: () => void;
 }
 
-let nextId = 0;
-const undoableTimers = new Map<number, ReturnType<typeof setTimeout>>();
+let nextId=0;
+const undoableTimers=new Map<number,ReturnType<typeof setTimeout>>();
 
-let queue = $state<ToastItem[]>([]);
+let queue=$state<ToastItem[]>([]);
 export function getToastQueue() { return queue; }
-export function consumeToastQueue() { queue = []; }
+export function consumeToastQueue() { queue=[]; }
 
-let promiseQueue = $state<{ id: number; promise: Promise<unknown>; opts: { loading: string; success: string; error: string } }[]>([]);
+let promiseQueue=$state<{ id: number; promise: Promise<unknown>; opts: { loading: string; success: string; error: string } }[]>([]);
 export function getPromiseQueue() { return promiseQueue; }
-export function consumePromiseQueue() { promiseQueue = []; }
+export function consumePromiseQueue() { promiseQueue=[]; }
 
-let toasts = $state<ToastItem[]>([]);
+let toasts=$state<ToastItem[]>([]);
 export function getToasts(): ToastItem[] { return toasts; }
 
 export function addToast(
-  type: ToastType, 
-  message: string, 
-  duration = 3000, 
-  options?: { key?: string, onUndo?: () => void, onTimeout?: () => void }
+  type: ToastType,
+  message: string,
+  duration=3000,
+  options?: { key?: string,onUndo?: () => void,onTimeout?: () => void }
 ): void {
-  if (options?.key) {
-    if (queue.some(q => q.key === options.key) || toasts.some(t => t.key === options.key)) return;
+  if(options?.key) {
+    if(queue.some(q => q.key===options.key)||toasts.some(t => t.key===options.key)) return;
   }
-  if (type !== 'undoable') {
-    queue.push({ id: nextId++, type, message, duration, key: options?.key });
+  if(type!=='undoable') {
+    queue.push({ id: nextId++,type,message,duration,...definedOptions({ key: options?.key }) });
     return;
   }
-  const id = nextId++;
-  toasts = [...toasts, { id, type, message, duration, ...options }];
-  const timer = setTimeout(() => {
+  const id=nextId++;
+  toasts=[...toasts,{ id,type,message,duration,...options }];
+  const timer=setTimeout(() => {
     undoableTimers.delete(id);
     options?.onTimeout?.();
     removeToast(id);
-  }, duration);
-  undoableTimers.set(id, timer);
+  },duration);
+  undoableTimers.set(id,timer);
 }
 
 export function removeToast(id: number): void {
-  const timer = undoableTimers.get(id);
-  if (timer) {
+  const timer=undoableTimers.get(id);
+  if(timer) {
     clearTimeout(timer);
     undoableTimers.delete(id);
   }
-  toasts = toasts.filter(t => t.id !== id);
+  toasts=toasts.filter(t => t.id!==id);
 }
 
 export function resetToast(): void {
-  for (const timer of undoableTimers.values()) clearTimeout(timer);
+  for(const timer of undoableTimers.values()) clearTimeout(timer);
   undoableTimers.clear();
-  queue = [];
-  promiseQueue = [];
-  toasts = [];
+  queue=[];
+  promiseQueue=[];
+  toasts=[];
 }
 
-export const toast = {
-  success: (msg: string, duration?: number, opts?: { key?: string }) => addToast('success', msg, duration, opts),
-  error: (msg: string, duration?: number, opts?: { key?: string }) => addToast('error', msg, duration ?? 5000, opts),
-  info: (msg: string, duration?: number, opts?: { key?: string }) => addToast('info', msg, duration, opts),
-  warning: (msg: string, duration?: number, opts?: { key?: string }) => addToast('warning', msg, duration ?? 4000, opts),
-  undoable: (msg: string, duration: number, onUndo: () => void, onTimeout: () => void) =>
-    addToast('undoable', msg, duration, { onUndo, onTimeout }),
-  promise: <T>(promise: Promise<T>, opts: { loading: string; success: string; error: string }) => {
-    promiseQueue.push({ id: nextId++, promise, opts });
+export const toast={
+  success: (msg: string,duration?: number,opts?: { key?: string }) => addToast('success',msg,duration,opts),
+  error: (msg: string,duration?: number,opts?: { key?: string }) => addToast('error',msg,duration??5000,opts),
+  info: (msg: string,duration?: number,opts?: { key?: string }) => addToast('info',msg,duration,opts),
+  warning: (msg: string,duration?: number,opts?: { key?: string }) => addToast('warning',msg,duration??4000,opts),
+  undoable: (msg: string,duration: number,onUndo: () => void,onTimeout: () => void) =>
+    addToast('undoable',msg,duration,{ onUndo,onTimeout }),
+  promise: <T>(promise: Promise<T>,opts: { loading: string; success: string; error: string }) => {
+    promiseQueue.push({ id: nextId++,promise,opts });
     return promise;
   },
 };

package/src/types.ts

@@ -1,6 +1,13 @@
 // Core type definitions — DataProvider + AuthProvider + Providers
 
 import type { Component } from 'svelte';
+import type { TaskRecord, SubmitTaskOptions, TaskError } from './task-contract';
+import type { Identity, CheckResult, AuthErrorResult } from './auth-query-contract';
+export type { Identity, CheckResult } from './auth-query-contract';
+import type { AuthActionResult } from './auth-mutation-contract';
+import type { ResourceContract } from './resource-contract';
+export type { AuthActionResult } from './auth-mutation-contract';
+export type { TaskRecord, SubmitTaskOptions, TaskDateValue, TaskMessageValue } from './task-contract';
 
 // ─── HttpError ─────────────────────────────────────────────────
 
@@ -15,8 +22,8 @@ export interface HttpErrorOptions {
 
 export class HttpError extends Error {
   statusCode: number;
-  errors?: ValidationErrors;
-  code?: string;
+  errors: ValidationErrors | undefined;
+  code: string | undefined;
   details?: unknown;
   body?: unknown;
   override cause?: unknown;
@@ -103,8 +110,6 @@ export interface LogicalFilter {
 }
 
 export interface GetListParams {
-  /** Query-owned cancellation signal. Never include it in a cache key or URL. */
-  signal?: AbortSignal;
   resource: string;
   pagination?: Pagination;
   sorters?: Sort[];
@@ -119,7 +124,6 @@ export interface GetListResult<TData extends BaseRecord = BaseRecord> {
 }
 
 export interface GetOneParams {
-  signal?: AbortSignal;
   resource: string;
   id: string | number;
   meta?: Record<string, unknown>;
@@ -130,7 +134,6 @@ export interface GetOneResult<TData extends BaseRecord = BaseRecord> {
 }
 
 export interface GetManyParams {
-  signal?: AbortSignal;
   resource: string;
   ids: (string | number)[];
   meta?: Record<string, unknown>;
@@ -205,7 +208,6 @@ export interface DeleteManyResult<TData extends BaseRecord = BaseRecord> {
 }
 
 export interface CustomParams<TVariables = unknown> {
-  signal?: AbortSignal;
   url: string;
   method: 'get' | 'post' | 'put' | 'patch' | 'delete';
   payload?: TVariables;
@@ -222,90 +224,35 @@ export interface CustomResult<TData = unknown> {
 
 export interface DataProvider {
   // Required methods
-  getList: <TData extends BaseRecord = BaseRecord>(params: GetListParams) => Promise<GetListResult<TData>>;
-  getOne: <TData extends BaseRecord = BaseRecord>(params: GetOneParams) => Promise<GetOneResult<TData>>;
-  create: <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: CreateParams<TVariables>) => Promise<CreateResult<TData>>;
-  update: <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: UpdateParams<TVariables>) => Promise<UpdateResult<TData>>;
-  deleteOne: <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: DeleteParams<TVariables>) => Promise<DeleteResult<TData>>;
+  getList: (params: GetListParams) => Promise<GetListResult>;
+  getOne: (params: GetOneParams) => Promise<GetOneResult>;
+  create: (params: CreateParams) => Promise<CreateResult>;
+  update: (params: UpdateParams) => Promise<UpdateResult>;
+  deleteOne: (params: DeleteParams) => Promise<DeleteResult>;
   getApiUrl: () => string;
 
   // Optional bulk methods
-  getMany?: <TData extends BaseRecord = BaseRecord>(params: GetManyParams) => Promise<GetManyResult<TData>>;
-  createMany?: <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: CreateManyParams<TVariables>) => Promise<CreateManyResult<TData>>;
-  updateMany?: <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: UpdateManyParams<TVariables>) => Promise<UpdateManyResult<TData>>;
-  deleteMany?: <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: DeleteManyParams<TVariables>) => Promise<DeleteManyResult<TData>>;
+  getMany?: (params: GetManyParams) => Promise<GetManyResult>;
+  createMany?: (params: CreateManyParams) => Promise<CreateManyResult>;
+  updateMany?: (params: UpdateManyParams) => Promise<UpdateManyResult>;
+  deleteMany?: (params: DeleteManyParams) => Promise<DeleteManyResult>;
 
   // Optional custom method
-  custom?: <TData = unknown, TVariables = unknown>(params: CustomParams<TVariables>) => Promise<CustomResult<TData>>;
+  custom?: (params: CustomParams) => Promise<CustomResult>;
 }
 
 // ─── TaskProvider ─────────────────────────────────────────────
 
-export type TaskDateValue = string | Date | null;
-export type TaskMessageValue = string | null;
-
-export interface TaskRecord extends BaseRecord {
-  id: string;
-  name?: string;
-  title?: string;
-  status?: string;
-  progress?: number;
-  priority?: number;
-  queueName?: string;
-  queue_name?: string;
-  message?: TaskMessageValue;
-  payload?: unknown;
-  /**
-   * Task output payload. `result` is the canonical camelCase field used by
-   * svadmin UI helpers; `result_data` is accepted for Supabase/Postgres-style
-   * task mirrors. Consumers should prefer `result`, then fall back to
-   * `result_data`, matching `resolveTaskResult`.
-   */
-  result?: unknown;
-  result_data?: unknown;
-  /**
-   * Task lifecycle timestamps. Supabase/Postgres mirrors often expose nullable
-   * columns for lifecycle phases that have not happened yet, and svadmin UI
-   * helpers intentionally skip nullish values with `??` fallback ordering.
-   */
-  createdAt?: TaskDateValue;
-  created_at?: TaskDateValue;
-  updatedAt?: TaskDateValue;
-  updated_at?: TaskDateValue;
-  startedAt?: TaskDateValue;
-  started_at?: TaskDateValue;
-  finishedAt?: TaskDateValue;
-  finished_at?: TaskDateValue;
-  cancelledAt?: TaskDateValue;
-  cancelled_at?: TaskDateValue;
-  /**
-   * Task failure payload/message. `error` carries structured error details
-   * when available; `errorMessage` and `error_message` are string fallbacks for
-   * camelCase and snake_case providers. Consumers should prefer `error`, then
-   * `errorMessage`, then `error_message`, matching `resolveTaskError`.
-   */
-  error?: unknown;
-  errorMessage?: TaskMessageValue;
-  error_message?: TaskMessageValue;
-}
-
-export interface SubmitTaskOptions {
-  body?: Record<string, unknown>;
-  idempotencyKey?: string;
-  headers?: Record<string, string>;
-  meta?: Record<string, unknown>;
-}
-
 export interface TaskSubscription {
   unsubscribe(): void;
 }
 
 export interface TaskHandle<TTask extends TaskRecord = TaskRecord> {
-  id?: string;
+  id: string;
   wait(): Promise<TTask>;
-  subscribe?(callback: (task: TTask) => void): TaskSubscription | (() => void) | undefined;
-  cancel?(): Promise<unknown>;
-  retry?(): Promise<unknown>;
+  subscribe?(callback: (task: TTask) => void, onError?: (error: TaskError) => void): TaskSubscription | (() => void);
+  cancel?(): Promise<TTask>;
+  retry?(): Promise<TTask>;
 }
 
 export interface TaskListResult<TTask extends TaskRecord = TaskRecord> {
@@ -318,34 +265,13 @@ export interface TaskProvider<TTask extends TaskRecord = TaskRecord> {
   get(taskId: string): Promise<TTask>;
   list?(params?: Record<string, unknown>): Promise<TaskListResult<TTask>>;
   listDlq?(params?: Record<string, unknown>): Promise<TaskListResult<TTask>>;
-  cancel?(taskId: string): Promise<unknown>;
-  retry?(taskId: string): Promise<unknown>;
-  subscribe?(taskId: string, callback: (task: TTask) => void): TaskSubscription | (() => void) | undefined;
+  cancel?(taskId: string): Promise<TTask>;
+  retry?(taskId: string): Promise<TTask>;
+  subscribe?(taskId: string, callback: (task: TTask) => void, onError?: (error: TaskError) => void): TaskSubscription | (() => void);
 }
 
 // ─── AuthProvider ─────────────────────────────────────────────
 
-export interface Identity {
-  id?: string;
-  name?: string;
-  email?: string;
-  avatar?: string;
-  [key: string]: unknown;
-}
-
-export interface AuthActionResult {
-  success: boolean;
-  redirectTo?: string;
-  error?: { message: string; name?: string };
-}
-
-export interface CheckResult {
-  authenticated: boolean;
-  redirectTo?: string;
-  error?: { message: string; name?: string };
-  logout?: boolean;
-}
-
 export interface Role {
   id: string;
   name: string;
@@ -379,7 +305,7 @@ export interface AuthProvider {
   updateRolePermissions?: (roleId: string, permissions: Record<string, string[]>) => Promise<AuthActionResult>;
   /** Get recent audit logs */
   getAuditLogs?: (params?: { page?: number; pageSize?: number }) => Promise<{ data: AuditLog[]; total: number }>;
-  onError?: (error: unknown) => Promise<{ redirectTo?: string; logout?: boolean }>;
+  onError?: (error: unknown) => Promise<AuthErrorResult>;
 }
 
 export interface AuditLog {
@@ -406,21 +332,21 @@ export type MutationMode = 'pessimistic' | 'optimistic' | 'undoable';
 
 // ─── ResourceDefinition ───────────────────────────────────────
 
-/** 声明资源使用的传输协议；具体 URL/序列化行为由对应 provider 实现。 */
+/** Declares a resource transport protocol; the corresponding provider owns URL and serialization behavior. */
 export interface ResourceTransportConfig {
   readonly type: string;
   readonly endpoint?: string;
   readonly options?: Readonly<Record<string, unknown>>;
 }
 
-/** 声明资源使用的后端 adapter，不在 Core 内绑定具体运行时实现。 */
+/** Declares a resource backend adapter without binding Core to a concrete runtime implementation. */
 export interface ResourceAdapterConfig {
   readonly name: string;
   readonly version?: string;
   readonly options?: Readonly<Record<string, unknown>>;
 }
 
-/** 每资源的 provider 选择与声明性 transport/adapter 元数据。 */
+/** Per-resource provider selection and declarative transport/adapter metadata. */
 export interface ResourceProviderConfig {
   readonly dataProviderName?: string;
   readonly transport?: string | ResourceTransportConfig;
@@ -430,6 +356,8 @@ export interface ResourceProviderConfig {
 
 export interface ResourceDefinition {
   name: string;
+  /** Runtime contract required by schema-bound metadata-driven data components. */
+  contract?: ResourceContract;
   /** Unique identifier — use when multiple resources share the same `name` but target different DataProviders */
   identifier?: string;
   label: string;
@@ -447,9 +375,9 @@ export interface ResourceDefinition {
   menuOrder?: number;
   /** Navigation group name — resources with the same group are displayed in a collapsible section */
   group?: string;
-  /** DataProvider 选择及声明性 transport/adapter 元数据。 */
+  /** DataProvider selection and declarative transport/adapter metadata. */
   provider?: ResourceProviderConfig;
-  /** @deprecated 新代码优先使用 `provider.dataProviderName` 选择 DataProvider。 */
+  /** @deprecated New code should select the DataProvider through `provider.dataProviderName`. */
   meta?: Record<string, unknown> & { dataProviderName?: string; parent?: string };
 }
 
@@ -518,7 +446,8 @@ export interface FieldDefinition {
 
 /**
  * Extend this interface via declaration merging to register resource types.
- * When registered, all hooks automatically infer data types from resource names.
+ * Query and mutation hooks infer data from explicit resource names.
+ * Extend ResourceInputMap as well to infer mutation payloads.
  *
  * @example
  * ```ts
@@ -531,12 +460,24 @@ export interface FieldDefinition {
  *
  * // Now hooks auto-infer:
  * const list = useList({ resource: 'users' })
- * // list.data → { id: string; name: string; email: string }[]
+ * // list.data?.data -> { id: string; name: string; email: string }[] | undefined
  * ```
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface ResourceTypeMap {}
 
+/** Extend alongside ResourceTypeMap to register create/update/delete payloads. */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface ResourceInputMap {}
+
+export type ResourceInputOperation = 'create' | 'update' | 'delete';
+
+/** Unregistered inputs retain the legacy dynamic payload contract. */
+export type InferResourceInput<R extends string, O extends ResourceInputOperation> =
+  R extends keyof ResourceInputMap
+    ? O extends keyof ResourceInputMap[R] ? ResourceInputMap[R][O] : never
+    : O extends 'delete' ? Record<string, unknown> | undefined : Record<string, unknown>;
+
 /** When ResourceTypeMap is empty → string; otherwise → registered keys */
 export type KnownResources = keyof ResourceTypeMap extends never
   ? string
@@ -546,3 +487,9 @@ export type KnownResources = keyof ResourceTypeMap extends never
 export type InferData<R extends string> = R extends keyof ResourceTypeMap
   ? ResourceTypeMap[R]
   : Record<string, unknown>
+
+// Map interface models without adding an index signature; distribute over unions.
+type RecordShape<T> = T extends object ? { [K in keyof T]: T[K] } : never;
+
+/** @internal Normalized record shape for resource-aware hook signatures. */
+export type ResourceRecord<R extends string> = RecordShape<InferData<R>>;

package/src/unsafe.ts

@@ -0,0 +1,7 @@
+/**
+ * Unchecked transport and metadata-driven UI APIs.
+ * Application CRUD should import contract-bound hooks from @svadmin/core.
+ */
+export * from './hooks.svelte';
+export { TableState } from './table-state.svelte';
+export type { TableStateOptions } from './table-state.svelte';

package/src/update-contract.ts

@@ -0,0 +1,65 @@
+import { Type } from '@sinclair/typebox';
+import { snapshotPlainData } from './plain-data';
+import { checkExact } from './schema-validation';
+import { HttpError } from './types';
+import { definedOptions } from './defined-options';
+import { parseContractId, parseContractRecord, parseContractUpdateInput,
+  type ContractSchemas, type ContractUpdateInput, type ResourceContract } from './resource-contract';
+import { decodeOneResult, rejectProviderResponse } from './record-decoder';
+
+export interface ContractUpdateParams<S extends ContractSchemas> {
+  variables: ContractUpdateInput<S>;
+  meta?: Record<string, unknown>;
+  dataProviderName?: string;
+}
+
+const envelope = Type.Object({
+  variables: Type.Unknown(),
+  meta: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+  dataProviderName: Type.Optional(Type.String({ minLength: 1 })),
+}, { additionalProperties: false });
+
+export function snapshotUpdateParams(value: unknown) {
+  try {
+    const snapshot = snapshotPlainData(value);
+    if (checkExact(envelope, snapshot)) return snapshot;
+  } catch {
+    // Reject accessors and serialization hooks without disclosing input.
+  }
+  throw new HttpError('Invalid update input', 422, undefined, {
+    code: 'INVALID_RESOURCE_INPUT', details: { phase: 'input', writeMayHaveSucceeded: false },
+  });
+}
+
+export function validateUpdateIdentity(variables: unknown, id: string | number): void {
+  if (typeof variables !== 'object' || variables === null || Array.isArray(variables)) return;
+  const property = Object.getOwnPropertyDescriptor(variables, 'id');
+  if (!property) return;
+  const candidate: unknown = property.value;
+  if (candidate === id) return;
+  throw new HttpError('Updates cannot change the record ID', 422, undefined, {
+    code: 'INVALID_RESOURCE_INPUT', details: { phase: 'input', writeMayHaveSucceeded: false },
+  });
+}
+
+/** Private schemas validate the input before establishing its public type. */
+export function parseUpdateParams<S extends ContractSchemas>(
+  contract: ResourceContract<S>, id: string | number, value: unknown,
+): ContractUpdateParams<S>;
+export function parseUpdateParams(contract: ResourceContract, id: string | number, value: unknown): object {
+  const input = snapshotUpdateParams(value);
+  const identity = parseContractId(contract, id);
+  const variables = parseContractUpdateInput(contract, input.variables);
+  validateUpdateIdentity(variables, identity);
+  return { variables, ...definedOptions({ meta: input.meta, dataProviderName: input.dataProviderName }) };
+}
+
+export function decodeUpdateReceipt<S extends ContractSchemas>(
+  contract: ResourceContract<S>, id: string | number, response: unknown,
+) {
+  try {
+    const result = decodeOneResult(snapshotPlainData(response), value => parseContractRecord(contract, value), true);
+    if (parseContractId(contract, result.data.id) !== id) return rejectProviderResponse(true);
+    return result;
+  } catch { return rejectProviderResponse(true); }
+}