@chelone/core 0.2.0 → 0.3.0

package/dist/controller/record-workflow.d.ts

@@ -7,21 +7,37 @@
  * can overwrite each other. The server has to enforce the count and who may
  * approve.
  */
+import type { SourceKey } from "../resource/source-path.js";
 type Id = string | number;
-export interface ApprovalOptions {
-    /** Record field holding the approver list. Default `"approvers"`. */
-    approverSource?: string;
+export interface ApprovalOptions<TRecord = Record<string, unknown>> {
+    /**
+     * Record field holding the approver list, a top-level key: it is read as
+     * `record[approverSource]` and written back whole. Default `"approvers"`.
+     */
+    approverSource?: SourceKey<TRecord>;
     /** Approvals needed. Floored, minimum 1; `NaN` reads as 2. Default 2. */
     required?: number;
     /** The current user. No identity means nobody can approve. */
     identityId?: Id | null;
-    /** Record field `buildApprovalUpdate` writes the status to. Default `"status"`. */
-    statusSource?: string;
+    /**
+     * Record field `buildApprovalUpdate` writes the status to, a top-level key.
+     * Default `"status"`.
+     */
+    statusSource?: SourceKey<TRecord>;
     /** Status written while approvals are short of `required`. Default `"pending"`. */
     pendingValue?: unknown;
     /** Status written once approvals reach `required`. Default `"approved"`. */
     approvedValue?: unknown;
 }
+/**
+ * What `buildApprovalUpdate` takes. `statusSource` is a write target, and a
+ * record often has no status field until its first approval, so it takes any
+ * string; `approverSource` is read, so it stays a key of the record.
+ */
+export type ApprovalUpdateOptions<TRecord = Record<string, unknown>> = Omit<ApprovalOptions<TRecord>, "statusSource"> & {
+    /** Record field the status is written to. Default `"status"`. */
+    statusSource?: string;
+};
 export interface ApprovalState {
     /** Distinct approver ids, as strings. */
     approvers: string[];
@@ -31,9 +47,9 @@ export interface ApprovalState {
     isComplete: boolean;
     canApprove: boolean;
 }
-export interface TransitionOptions {
-    /** Record field holding the status. Default `"status"`. */
-    source?: string;
+export interface TransitionOptions<TRecord = Record<string, unknown>> {
+    /** Record field holding the status, a top-level key. Default `"status"`. */
+    source?: SourceKey<TRecord>;
     /** Next states by current state. */
     transitions: Record<string, readonly string[]>;
     /** Predicates keyed `"<from>-><to>"`. A transition with no guard is allowed. */
@@ -43,12 +59,12 @@ export interface AllowedTransitions {
     current: string;
     allowed: string[];
 }
-export declare function getApprovalState(record: Record<string, unknown>, options?: ApprovalOptions): ApprovalState;
+export declare function getApprovalState<TRecord = Record<string, unknown>>(record: TRecord & object, options?: ApprovalOptions<TRecord>): ApprovalState;
 /**
  * The patch that records `identityId`'s approval, or `null` when they cannot
  * approve. Stored items stay as they were and the identity is appended in its
  * own type.
  */
-export declare function buildApprovalUpdate(record: Record<string, unknown>, options?: ApprovalOptions): Record<string, unknown> | null;
-export declare function getAllowedTransitions(record: Record<string, unknown>, options: TransitionOptions): AllowedTransitions;
+export declare function buildApprovalUpdate<TRecord = Record<string, unknown>>(record: TRecord & object, options?: ApprovalUpdateOptions<TRecord>): Record<string, unknown> | null;
+export declare function getAllowedTransitions<TRecord = Record<string, unknown>>(record: TRecord & object, options: TransitionOptions<TRecord>): AllowedTransitions;
 export {};

package/dist/controller/record-workflow.js

@@ -34,7 +34,11 @@ function buildApprovalUpdate(record, options = {}) {
     pendingValue = "pending",
     approvedValue = "approved"
   } = options;
-  const state = getApprovalState(record, options);
+  const state = getApprovalState(record, {
+    approverSource: options.approverSource,
+    required: options.required,
+    identityId
+  });
   if (!state.canApprove || identityId === void 0 || identityId === null) {
     return null;
   }

package/dist/data/cache-ops.d.ts

@@ -12,6 +12,14 @@ export declare function removeRecordsFromCache(queryClient: QueryClient, resourc
  * `getManyReference`, `getInfiniteList` page and `getMany` entry.
  */
 export declare function updateRecordsInCache(queryClient: QueryClient, resource: string, ids: Identifier[], data: Record<string, unknown>): void;
+/**
+ * Shallow-merge `data` into the matching rows of every cached `getList`,
+ * `getManyReference` and `getInfiniteList` page, and return a `rollback` that
+ * puts back only the patched keys of those rows into whatever each entry holds
+ * when it is called, so another update's patch to a different row survives.
+ * An entry that holds none of the ids keeps its cached object.
+ */
+export declare function patchListEntries(queryClient: QueryClient, resource: string, idSet: Set<string>, data: Record<string, unknown>): () => void;
 /**
  * Shallow-merge `data` into the matching records of every cached `getMany`
  * entry (what `ReferenceField` and `ReferenceArrayField` read through).

package/dist/data/cache-ops.js

@@ -95,6 +95,85 @@ function updateRecordsInCache(queryClient, resource, ids, data) {
   }
   patchManyEntries(queryClient, resource, idSet, data);
 }
+const ABSENT = /* @__PURE__ */ Symbol("absent");
+function priorsOf(page, idSet, data) {
+  const priors = /* @__PURE__ */ new Map();
+  for (const row of page.data) {
+    const id = String(row.id);
+    if (!idSet.has(id)) continue;
+    const prior = {};
+    for (const field of Object.keys(data)) {
+      prior[field] = field in row ? row[field] : ABSENT;
+    }
+    priors.set(id, prior);
+  }
+  return priors;
+}
+function withRestoredRows(page, priors) {
+  return {
+    ...page,
+    data: page.data.map((record) => {
+      const prior = priors.get(String(record.id));
+      if (!prior) return record;
+      const restored = { ...record };
+      for (const [field, value] of Object.entries(prior)) {
+        if (value === ABSENT) delete restored[field];
+        else restored[field] = value;
+      }
+      return restored;
+    })
+  };
+}
+function patchListEntries(queryClient, resource, idSet, data) {
+  const rollbacks = [];
+  for (const queryKey of singleResultListKeyPrefixes(resource)) {
+    for (const [key, value] of queryClient.getQueriesData({
+      queryKey
+    })) {
+      if (!value) continue;
+      const next = withPatchedRows(value, idSet, data);
+      if (!next) continue;
+      const priors = priorsOf(value, idSet, data);
+      queryClient.setQueryData(key, next);
+      rollbacks.push(() => {
+        const current = queryClient.getQueryData(key);
+        if (current) {
+          queryClient.setQueryData(
+            key,
+            withRestoredRows(current, priors)
+          );
+        }
+      });
+    }
+  }
+  const infinite = queryClient.getQueriesData({ queryKey: infiniteListKeyPrefix(resource) });
+  for (const [key, value] of infinite) {
+    if (!value) continue;
+    const pages = value.pages.map(
+      (page) => withPatchedRows(page, idSet, data) ?? page
+    );
+    if (pages.every((page, i) => page === value.pages[i])) continue;
+    const priorsByPage = value.pages.map((page) => priorsOf(page, idSet, data));
+    queryClient.setQueryData(key, {
+      ...value,
+      pages
+    });
+    rollbacks.push(() => {
+      const current = queryClient.getQueryData(key);
+      if (!current) return;
+      queryClient.setQueryData(key, {
+        ...current,
+        pages: current.pages.map((page, i) => {
+          const priors = priorsByPage[i];
+          return priors && priors.size > 0 ? withRestoredRows(page, priors) : page;
+        })
+      });
+    });
+  }
+  return () => {
+    for (const rollback of rollbacks) rollback();
+  };
+}
 function patchManyEntries(queryClient, resource, idSet, data) {
   const manys = queryClient.getQueriesData({
     queryKey: manyKeyPrefix(resource)
@@ -125,6 +204,7 @@ function removeManyEntries(queryClient, resource, idSet) {
   }
 }
 export {
+  patchListEntries,
   patchManyEntries,
   removeManyEntries,
   removeRecordsFromCache,

package/dist/data/mutation-options.d.ts

@@ -16,17 +16,20 @@ interface OptimisticContext {
     previous?: unknown;
     key?: readonly unknown[];
     manySnapshot?: ManySnapshot;
+    rollbackLists?: () => void;
 }
 export declare function createMutationOptions<TResources extends ResourceMap, TName extends keyof TResources & string>(ctx: DataContext<TResources>, resource: TName): {
     mutationFn: (params: CreateParams<RecordOf<TResources, TName>>) => Promise<RecordOf<TResources, TName>>;
     onSettled: () => Promise<void>;
 };
 export declare function updateMutationOptions<TResources extends ResourceMap, TName extends keyof TResources & string>(ctx: DataContext<TResources>, resource: TName, options?: MutationModeOptions): {
+    mutationKey: string[];
     mutationFn: (params: UpdateParams<RecordOf<TResources, TName>>) => Promise<RecordOf<TResources, TName>>;
     onMutate: (params: UpdateParams<RecordOf<TResources, TName>>) => Promise<{
         previous?: undefined;
         key?: undefined;
         manySnapshot?: undefined;
+        rollbackLists?: undefined;
     } | {
         previous: RecordOf<TResources, TName> | undefined;
         key: readonly [string, "getOne", {
@@ -37,9 +40,10 @@ export declare function updateMutationOptions<TResources extends ResourceMap, TN
             meta: {} | null;
         }];
         manySnapshot: ManySnapshot;
+        rollbackLists: () => void;
     }>;
     onError: (_error: unknown, _params: UpdateParams<RecordOf<TResources, TName>>, context: OptimisticContext | undefined) => void;
-    onSettled: () => Promise<void>;
+    onSettled: () => Promise<void> | undefined;
 };
 export declare function deleteMutationOptions<TResources extends ResourceMap, TName extends keyof TResources & string>(ctx: DataContext<TResources>, resource: TName, options?: MutationModeOptions): {
     mutationFn: (params: DeleteParams<RecordOf<TResources, TName>>) => Promise<RecordOf<TResources, TName>>;

package/dist/data/mutation-options.js

@@ -1,8 +1,22 @@
-import { removeManyEntries, patchManyEntries } from "./cache-ops.js";
+import { removeManyEntries, patchManyEntries, patchListEntries } from "./cache-ops.js";
 import { oneKey, resourceKey, manyKeyPrefix } from "./keys.js";
 function invalidateResource(ctx, resource) {
   return ctx.queryClient.invalidateQueries({ queryKey: resourceKey(resource) });
 }
+const unsettledUpdates = /* @__PURE__ */ new WeakMap();
+function countUpdate(queryClient, resource, by) {
+  const counts = unsettledUpdates.get(queryClient) ?? /* @__PURE__ */ new Map();
+  unsettledUpdates.set(queryClient, counts);
+  const next = (counts.get(resource) ?? 0) + by;
+  counts.set(resource, next);
+  return next;
+}
+function cancelListQueries(ctx, resource) {
+  return ctx.queryClient.cancelQueries({
+    queryKey: resourceKey(resource),
+    predicate: ({ queryKey }) => queryKey[1] === "getList" || queryKey[1] === "getManyReference" || queryKey[1] === "getInfiniteList"
+  });
+}
 async function snapshotManyEntries(ctx, resource) {
   await ctx.queryClient.cancelQueries({ queryKey: manyKeyPrefix(resource) });
   return ctx.queryClient.getQueriesData({ queryKey: manyKeyPrefix(resource) });
@@ -23,13 +37,16 @@ function createMutationOptions(ctx, resource) {
 }
 function updateMutationOptions(ctx, resource, options = {}) {
   const mode = options.mutationMode ?? "pessimistic";
+  const mutationKey = [resource, "update"];
   return {
+    mutationKey,
     mutationFn: async (params) => {
       const result = await ctx.dataProvider.update(resource, params);
       return result.data;
     },
     onMutate: async (params) => {
       if (mode !== "optimistic") return {};
+      countUpdate(ctx.queryClient, resource, 1);
       const key = oneKey(resource, { id: params.id });
       await ctx.queryClient.cancelQueries({ queryKey: key });
       const previous = ctx.queryClient.getQueryData(key);
@@ -47,15 +64,28 @@ function updateMutationOptions(ctx, resource, options = {}) {
         /* @__PURE__ */ new Set([String(params.id)]),
         structuredClone(params.data)
       );
-      return { previous, key, manySnapshot };
+      await cancelListQueries(ctx, resource);
+      const rollbackLists = patchListEntries(
+        ctx.queryClient,
+        resource,
+        /* @__PURE__ */ new Set([String(params.id)]),
+        structuredClone(params.data)
+      );
+      return { previous, key, manySnapshot, rollbackLists };
     },
     onError: (_error, _params, context) => {
       if (context?.key && context.previous !== void 0) {
         ctx.queryClient.setQueryData(context.key, context.previous);
       }
       restoreManyEntries(ctx, context?.manySnapshot);
+      context?.rollbackLists?.();
     },
-    onSettled: () => invalidateResource(ctx, resource)
+    onSettled: () => {
+      if (mode === "optimistic" && countUpdate(ctx.queryClient, resource, -1) > 0) {
+        return;
+      }
+      return invalidateResource(ctx, resource);
+    }
   };
 }
 function deleteMutationOptions(ctx, resource, options = {}) {

package/dist/form/array-binding.d.ts

@@ -1,3 +1,4 @@
+import type { LooseRecord } from "../resource/record.js";
 import type { CheloneFormApi } from "./form-controller.js";
 import { type FieldBinding, type FieldBindingOptions } from "./input-binding.js";
 /**
@@ -27,7 +28,7 @@ export interface ArrayRow {
     /** Moves THIS row to `to` — {@link ArrayBinding.reOrder} from the row's index. */
     reOrder(to: number): void;
 }
-export interface ArrayBindingOptions extends Omit<FieldBindingOptions, "format" | "parse"> {
+export interface ArrayBindingOptions<TRecord = LooseRecord> extends Omit<FieldBindingOptions<TRecord>, "format" | "parse"> {
     /**
      * Seed rows for a value hole (ra precedence: an existing record value,
      * including `[]`, always wins). Defaults to `[]` so positional ops always
@@ -51,7 +52,7 @@ export interface ArrayBindingOptions extends Omit<FieldBindingOptions, "format"
     itemDefaults?: Record<string, unknown>;
 }
 /** `update()` payload: everything but the identity-defining source. */
-export type ArrayBindingUpdateOptions = Omit<ArrayBindingOptions, "source">;
+export type ArrayBindingUpdateOptions = Omit<ArrayBindingOptions<LooseRecord>, "source">;
 /**
  * Vanilla array binding over a form-core array field — the useArrayInput
  * substrate (T8 wraps it in React contexts).
@@ -128,4 +129,4 @@ export interface ArrayBinding<TRecord> {
      */
     destroy(): void;
 }
-export declare function createArrayBinding<TRecord>(form: CheloneFormApi<TRecord>, options: ArrayBindingOptions): ArrayBinding<TRecord>;
+export declare function createArrayBinding<TRecord>(form: CheloneFormApi<TRecord>, options: ArrayBindingOptions<TRecord>): ArrayBinding<TRecord>;

package/dist/form/input-binding.d.ts

@@ -1,4 +1,6 @@
 import { type DeepKeys, type DeepValue, FieldApi, type FieldAsyncValidateOrFn, type FieldValidateOrFn, type StandardSchemaV1 } from "@tanstack/form-core";
+import type { LooseRecord } from "../resource/record.js";
+import type { SourcePath } from "../resource/source-path.js";
 import type { AsyncValidator, CheloneFormApi, SyncValidator } from "./form-controller.js";
 import { type Validator } from "./validators.js";
 /**
@@ -55,9 +57,9 @@ export interface FieldValidatorMeta {
     source: string;
     [key: string]: unknown;
 }
-export interface FieldBindingOptions {
+export interface FieldBindingOptions<TRecord = LooseRecord> {
     /** The FINAL field path (already source-scoped — see `source.ts`). */
-    source: string;
+    source: SourcePath<TRecord>;
     /**
      * Input-level default, ra precedence: seeds ONLY into a hole (untouched
      * field whose form value is `undefined`) — an existing record value,
@@ -81,7 +83,7 @@ export interface FieldBindingOptions {
     validatorMeta?: Record<string, unknown>;
 }
 /** `update()` payload: everything but the identity-defining source. */
-export type FieldBindingUpdateOptions = Omit<FieldBindingOptions, "source">;
+export type FieldBindingUpdateOptions = Omit<FieldBindingOptions<LooseRecord>, "source">;
 /**
  * Vanilla field binding over a single `@tanstack/form-core` FieldApi —
  * the useInput substrate (T4 wraps it in React contexts).
@@ -137,5 +139,5 @@ export interface FieldBinding<TRecord> {
      */
     destroy(): void;
 }
-export declare function createFieldBinding<TRecord>(form: CheloneFormApi<TRecord>, options: FieldBindingOptions): FieldBinding<TRecord>;
+export declare function createFieldBinding<TRecord>(form: CheloneFormApi<TRecord>, options: FieldBindingOptions<TRecord>): FieldBinding<TRecord>;
 export {};

package/dist/resource/get-at-path.d.ts

@@ -3,9 +3,9 @@
  * bracket indices (`a[0].b`) and numeric-dot indices (`a.0.b`) all resolve to
  * the same value, matching `lodash/get`'s relevant semantics.
  *
- * The core tree, calendar and client-list readers read through this, so a
- * `source` written one way reads the same record everywhere. The adapters'
- * `useFieldValue` reads the same grammar and moves onto this helper next.
+ * The core tree, calendar and client-list readers read through this, and so do
+ * both adapters' `useFieldValue` and `useGetRecordRepresentation`: a `source`
+ * written one way reads the same record everywhere, and one walker is left.
  */
 /**
  * Read the value at `source` off `record`. An empty `source` returns the record

package/dist/resource/get-at-path.js

@@ -1,20 +1,13 @@
 const PATH_SEGMENT = /\[([^\]]*)\]|[^.[\]]+/g;
-const toPathSegments = (source) => {
-  const segments = [];
-  for (const match of source.matchAll(PATH_SEGMENT)) {
-    segments.push(match[1] !== void 0 ? match[1] : match[0]);
-  }
-  return segments;
-};
 function getAtPath(record, source) {
   if (source === "") return record;
   if (record !== null && typeof record === "object" && Object.hasOwn(record, source)) {
     return record[source];
   }
   let current = record;
-  for (const key of toPathSegments(source)) {
+  for (const match of source.matchAll(PATH_SEGMENT)) {
     if (current === null || typeof current !== "object") return void 0;
-    current = current[key];
+    current = current[match[1] !== void 0 ? match[1] : match[0]];
   }
   return current;
 }

package/dist/resource/registry.d.ts

@@ -1,5 +1,6 @@
 import type { StandardSchemaV1 } from "@tanstack/form-core";
 import type { LooseRecord } from "./record.js";
+import type { SourceKey } from "./source-path.js";
 /** Per-resource configuration: an optional Standard Schema (Zod 3, Zod 4, Valibot, ...) and the references its fields hold. */
 export interface ResourceConfig<TSchema extends StandardSchemaV1 = StandardSchemaV1> {
     schema?: TSchema;
@@ -20,7 +21,20 @@ export type ResourceMap = {
  * `defineResources({ posts: { schema: postSchema } })` keeps `"posts"` literal
  * and `typeof postSchema` exact, enabling end-to-end inference.
  */
-export declare function defineResources<const T extends ResourceMap>(resources: T): T;
+export declare function defineResources<const T extends ResourceMap>(resources: T & Checked<T>): T;
+/**
+ * Narrows each resource's `references` to keys that are top-level fields of its
+ * record and values that are registered resource names. A mapped type over the
+ * keys actually written is what makes a misspelled key an error: an optional
+ * `{ [K in SourceKey]?: ... }` intersection lets inference widen `T` instead.
+ */
+type Checked<T extends ResourceMap> = {
+    [N in keyof T & string]: {
+        references?: {
+            [K in keyof NonNullable<T[N]["references"]>]: K extends SourceKey<RecordOf<T, N>> ? keyof T & string : never;
+        };
+    };
+};
 /**
  * The record type for a given resource name in a registry:
  * the schema's Standard Schema output type when a schema is present, else `LooseRecord`.
@@ -28,3 +42,4 @@ export declare function defineResources<const T extends ResourceMap>(resources:
 export type RecordOf<TResources extends ResourceMap, TName extends keyof TResources> = TResources[TName] extends {
     schema: infer S;
 } ? S extends StandardSchemaV1<unknown, infer Output> ? Output : LooseRecord : LooseRecord;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chelone/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",