@chelone/core 0.10.0 → 0.11.0

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

@@ -2,10 +2,11 @@
  * Pure rules for a record diff. No react, no vue: both DiffViewer adapters
  * mark the same field the same way and print the same default text.
  */
+import type { LooseRecord } from "../resource/record.js";
 import type { SourceProp } from "../resource/source-path.js";
 export type DiffStatus = "unchanged" | "added" | "removed" | "changed";
-export interface RecordDiffRow {
-    source: string;
+export interface RecordDiffRow<R = LooseRecord> {
+    source: SourceProp<R>;
     status: DiffStatus;
     before: unknown;
     after: unknown;
@@ -16,6 +17,6 @@ export interface RecordDiffRow {
  * `null` and `undefined` both count as missing; an empty string is a value.
  * Neither record is changed.
  */
-export declare function diffRecords<R>(before: R, after: R, sources?: readonly SourceProp<R>[]): RecordDiffRow[];
+export declare function diffRecords<R>(before: R, after: R, sources?: readonly SourceProp<R>[]): RecordDiffRow<R>[];
 /** The text a viewer shows for a value when the app gives no renderer. */
 export declare function formatDiffValue(value: unknown): string;

package/dist/controller/record-diff.js

@@ -25,7 +25,8 @@ function statusOf(before, after) {
 */
 function diffRecords(before, after, sources) {
 	const beforeKeys = topLevelKeys(before);
-	return (sources ?? [...beforeKeys, ...topLevelKeys(after).filter((key) => !beforeKeys.includes(key))]).map((source) => {
+	const inferredKeys = [...beforeKeys, ...topLevelKeys(after).filter((key) => !beforeKeys.includes(key))];
+	return (sources ?? inferredKeys).map((source) => {
 		const was = getAtPath(before, source);
 		const now = getAtPath(after, source);
 		return {

package/dist/controller/reference-many-controller.d.ts

@@ -1,18 +1,20 @@
 import type { FilterPayload, SortPayload } from "../data/types.js";
 import type { Identifier } from "../resource/identifier.js";
+import type { LooseRecord } from "../resource/record.js";
 import type { RecordOf, ResourceMap } from "../resource/registry.js";
+import type { SourceKey } from "../resource/source-path.js";
 import { type ListController, type ListControllerContext } from "./list-controller.js";
-export interface ReferenceManyControllerOptions {
-    /** The field on the referenced-FROM resource that holds the foreign key. */
-    target: string;
+export interface ReferenceManyControllerOptions<TRecord = LooseRecord> {
+    /** The field on the referenced-FROM resource that holds the foreign key. A key of the referenced record. */
+    target: SourceKey<TRecord>;
     /** The value `target` must equal. Null or undefined fetches nothing. */
     id: Identifier | null | undefined;
     /** Permanent filter, merged OVER the user filter for every fetch. */
-    filter?: FilterPayload;
+    filter?: FilterPayload<TRecord>;
     /** Seed for the user filter when nothing is persisted. */
-    filterDefaultValues?: FilterPayload;
+    filterDefaultValues?: FilterPayload<TRecord>;
     /** Initial sort when nothing is persisted: one payload or several, applied in order. Default id ascending. */
-    sort?: SortPayload | SortPayload[];
+    sort?: SortPayload<TRecord> | SortPayload<TRecord>[];
     /** Default 25. */
     perPage?: number;
     /** Debounce delay for `setFilters(..., debounced=true)`. Default 500ms. */
@@ -42,4 +44,4 @@ export declare const DEFAULT_REFERENCE_PER_PAGE = 25;
  * params change, never from the result subscription; out-of-range page
  * resets go through the inner `setPage` and only on SETTLED results.
  */
-export declare function createReferenceManyController<TResources extends ResourceMap, TName extends keyof TResources & string>(ctx: ListControllerContext<TResources>, reference: TName, options: ReferenceManyControllerOptions): ReferenceManyController<RecordOf<TResources, TName>>;
+export declare function createReferenceManyController<TResources extends ResourceMap, TName extends keyof TResources & string>(ctx: ListControllerContext<TResources>, reference: TName, options: ReferenceManyControllerOptions<RecordOf<TResources, TName>>): ReferenceManyController<RecordOf<TResources, TName>>;

package/dist/controller/reference-one-controller.d.ts

@@ -1,17 +1,19 @@
 import type { FilterPayload, SortPayload } from "../data/types.js";
 import type { Identifier } from "../resource/identifier.js";
+import type { LooseRecord } from "../resource/record.js";
 import type { RecordOf, ResourceMap } from "../resource/registry.js";
+import type { SourceKey } from "../resource/source-path.js";
 import { type MicroStore } from "../store/micro-store.js";
 import type { ListControllerContext } from "./list-controller.js";
-export interface ReferenceOneControllerOptions {
-    /** The field on the referenced-FROM resource that holds the foreign key. */
-    target: string;
+export interface ReferenceOneControllerOptions<TRecord = LooseRecord> {
+    /** The field on the referenced-FROM resource that holds the foreign key. A key of the referenced record. */
+    target: SourceKey<TRecord>;
     /** The value `target` must equal. Null or undefined fetches nothing. */
     id: Identifier | null | undefined;
     /** Decides which row is first when several match. Omitted: the provider's order. */
-    sort?: SortPayload | SortPayload[];
+    sort?: SortPayload<TRecord> | SortPayload<TRecord>[];
     /** Narrows the lookup, e.g. to one kind of row. Default: no filter. */
-    filter?: FilterPayload;
+    filter?: FilterPayload<TRecord>;
     /** Gates the fetch. A disabled lookup with no cached data reads `isPending: true`. Default true. */
     enabled?: boolean;
 }
@@ -36,4 +38,4 @@ export interface ReferenceOneController<TRecord> extends MicroStore<ReferenceOne
  * Lifecycle (Task 4R): construction is inert; the observer is acquired on the
  * first subscriber and released on the last unsubscribe.
  */
-export declare function createReferenceOneController<TResources extends ResourceMap, TName extends keyof TResources & string>(ctx: ListControllerContext<TResources>, reference: TName, options: ReferenceOneControllerOptions): ReferenceOneController<RecordOf<TResources, TName>>;
+export declare function createReferenceOneController<TResources extends ResourceMap, TName extends keyof TResources & string>(ctx: ListControllerContext<TResources>, reference: TName, options: ReferenceOneControllerOptions<RecordOf<TResources, TName>>): ReferenceOneController<RecordOf<TResources, TName>>;

package/dist/controller/saved-queries.d.ts

@@ -1,22 +1,23 @@
-import type { FilterPayload, SortPayload } from "../data/types.js";
+import type { DisplayedFilters, FilterPayload, SortPayload } from "../data/types.js";
+import type { LooseRecord } from "../resource/record.js";
 import { type MicroStore } from "../store/micro-store.js";
 import type { ListControllerContext } from "./list-controller.js";
-export interface SavedQueryValue {
-    filter: FilterPayload;
-    displayedFilters: Record<string, boolean>;
-    sort: SortPayload[];
+export interface SavedQueryValue<TRecord = LooseRecord> {
+    filter: FilterPayload<TRecord>;
+    displayedFilters: DisplayedFilters<TRecord>;
+    sort: SortPayload<TRecord>[];
     perPage: number;
 }
-export interface SavedQuery {
+export interface SavedQuery<TRecord = LooseRecord> {
     label: string;
-    value: SavedQueryValue;
+    value: SavedQueryValue<TRecord>;
 }
-export interface SavedQueriesState {
-    queries: SavedQuery[];
+export interface SavedQueriesState<TRecord = LooseRecord> {
+    queries: SavedQuery<TRecord>[];
 }
-export interface SavedQueriesController extends MicroStore<SavedQueriesState> {
+export interface SavedQueriesController<TRecord = LooseRecord> extends MicroStore<SavedQueriesState<TRecord>> {
     /** Trims the label, ignores a blank one, replaces a same-label query in place, else appends. */
-    save(label: string, value: SavedQueryValue): void;
+    save(label: string, value: SavedQueryValue<TRecord>): void;
     remove(label: string): void;
 }
 export interface SavedQueriesControllerOptions {
@@ -29,9 +30,9 @@ export declare function savedQueriesKey(storeKey: string): string;
  * Reads whatever storage holds: non-arrays give `[]`, malformed entries are
  * dropped, labels are trimmed, and a repeated label keeps its first entry.
  */
-export declare function extractValidSavedQueries(raw: unknown): SavedQuery[];
+export declare function extractValidSavedQueries<TRecord = LooseRecord>(raw: unknown): SavedQuery<TRecord>[];
 /** Whether `current` list params are the saved query. `displayedFilters` is ignored. */
-export declare function isSavedQueryActive(query: SavedQueryValue, current: SavedQueryValue): boolean;
+export declare function isSavedQueryActive<TRecord = LooseRecord>(query: SavedQueryValue<TRecord>, current: SavedQueryValue<TRecord>): boolean;
 /**
  * Named filter/sort sets persisted in the KV store.
  *
@@ -40,4 +41,4 @@ export declare function isSavedQueryActive(query: SavedQueryValue, current: Save
  * a write still updates local state, and the next attach picks up whatever the
  * store holds.
  */
-export declare function createSavedQueriesController(ctx: Pick<ListControllerContext, "store">, resource: string, options?: SavedQueriesControllerOptions): SavedQueriesController;
+export declare function createSavedQueriesController<TRecord = LooseRecord>(ctx: Pick<ListControllerContext, "store">, resource: string, options?: SavedQueriesControllerOptions): SavedQueriesController<TRecord>;

package/dist/controller/saved-queries.js

@@ -6,6 +6,11 @@ function savedQueriesKey(storeKey) {
 	return `${storeKey}.savedQueries`;
 }
 var isSortPayload = (value) => isRecord(value) && typeof value.field === "string" && (value.order === "ASC" || value.order === "DESC");
+/**
+* Structural only: a field renamed since the query was saved leaves a stale
+* key, and no guard can check keys without the record. The predicate names the
+* record the caller asked for, so a guarded value is trusted to hold its keys.
+*/
 function isSavedQueryValue(value) {
 	return isRecord(value) && isRecord(value.filter) && isRecord(value.displayedFilters) && Object.values(value.displayedFilters).every((flag) => typeof flag === "boolean") && Array.isArray(value.sort) && value.sort.every(isSortPayload) && typeof value.perPage === "number" && Number.isInteger(value.perPage) && value.perPage > 0;
 }

package/dist/csv/import-controller.d.ts

@@ -1,3 +1,4 @@
+import type { LooseRecord } from "../resource/record.js";
 import { type MicroStore } from "../store/micro-store.js";
 import type { CsvImportOptions, CsvImportState, ParsedCsv } from "./types.js";
 /** How many rows either adapter's preview step lists. */
@@ -22,4 +23,4 @@ export interface CsvImportController {
     cancel(): void;
     reset(): void;
 }
-export declare function createCsvImportController(options: CsvImportOptions): CsvImportController;
+export declare function createCsvImportController<TRecord = LooseRecord>(options: CsvImportOptions<TRecord>): CsvImportController;

package/dist/csv/types.d.ts

@@ -1,5 +1,7 @@
 import type { StandardSchemaV1 } from "@tanstack/form-core";
 import type { DataProvider } from "../data/types.js";
+import type { LooseRecord } from "../resource/record.js";
+import type { SourceKey } from "../resource/source-path.js";
 /** One problem the parser found. `row` is the 1-based data row (the header row is not counted). */
 export interface CsvParseError {
     code: string;
@@ -81,16 +83,21 @@ export interface CsvImportState {
     report: CsvImportReport | null;
     error: Error | null;
 }
-export interface CsvImportOptions {
+/**
+ * `TRecord` is the schema's output, the record the import creates, so it may
+ * lack `id` and is not bounded by `ResourceRecord`. Without a schema it is
+ * `LooseRecord` and every field name is a plain string.
+ */
+export interface CsvImportOptions<TRecord = LooseRecord> {
     dataProvider: DataProvider;
     resource: string;
-    schema?: StandardSchemaV1;
+    schema?: StandardSchemaV1<unknown, TRecord>;
     /** Overrides the schema's keys. Without either, the CSV headers are the fields. */
-    fields?: string[];
+    fields?: SourceKey<TRecord>[];
     /** Overrides the schema's non-optional keys. */
-    requiredFields?: string[];
+    requiredFields?: SourceKey<TRecord>[];
     /** A starting field to header mapping. When non-empty it replaces the auto-match. */
-    mapping?: Record<string, string>;
+    mapping?: Partial<Record<SourceKey<TRecord>, string>>;
     transform?: CsvTransform;
     batchSize?: number;
     onComplete?: (report: CsvImportReport) => void;

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

@@ -1,18 +1,20 @@
 import type { QueryClient } from "@tanstack/query-core";
 import type { Identifier } from "../resource/identifier.js";
-import type { LooseRecord, ResourceRecord } from "../resource/record.js";
+import type { RecordOf, ResourceMap } from "../resource/registry.js";
+/** The fields a patch may set on a record of the named resource. */
+type Patch<TResources extends ResourceMap, TName extends keyof TResources> = Partial<RecordOf<TResources, TName>>;
 /**
  * Optimistically remove records: drop each `getOne` entry and filter the id(s)
  * out of every cached `getList`, `getManyReference` and `getInfiniteList` page
  * (decrementing `total` when known) and `getMany` entry.
  */
-export declare function removeRecordsFromCache<TRecord extends ResourceRecord = LooseRecord>(queryClient: QueryClient, resource: string, ids: Identifier[]): void;
+export declare function removeRecordsFromCache<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(queryClient: QueryClient, resource: TName, ids: Identifier[]): void;
 /**
  * Optimistically patch records: shallow-merge `data` into each matching
  * `getOne` entry and every matching row of every cached `getList`,
  * `getManyReference`, `getInfiniteList` page and `getMany` entry.
  */
-export declare function updateRecordsInCache<TRecord extends ResourceRecord = LooseRecord>(queryClient: QueryClient, resource: string, ids: Identifier[], data: Partial<NoInfer<TRecord>>): void;
+export declare function updateRecordsInCache<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(queryClient: QueryClient, resource: TName, ids: Identifier[], data: Patch<TResources, TName>): void;
 /**
  * Shallow-merge `data` into the matching rows of every cached `getList`,
  * `getManyReference` and `getInfiniteList` page, and return a `rollback` that
@@ -20,15 +22,16 @@ export declare function updateRecordsInCache<TRecord extends ResourceRecord = Lo
  * 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<TRecord extends ResourceRecord = LooseRecord>(queryClient: QueryClient, resource: string, idSet: Set<string>, data: Partial<NoInfer<TRecord>>): () => void;
+export declare function patchListEntries<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(queryClient: QueryClient, resource: TName, idSet: Set<string>, data: Patch<TResources, TName>): () => void;
 /**
  * Shallow-merge `data` into the matching records of every cached `getMany`
  * entry (what `ReferenceField` and `ReferenceArrayField` read through).
  */
-export declare function patchManyEntries<TRecord extends ResourceRecord = LooseRecord>(queryClient: QueryClient, resource: string, idSet: Set<string>, data: Partial<NoInfer<TRecord>>): void;
+export declare function patchManyEntries<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(queryClient: QueryClient, resource: TName, idSet: Set<string>, data: Patch<TResources, TName>): void;
 /**
  * Drop the matching records from every cached `getMany` entry (what
  * `ReferenceField` and `ReferenceArrayField` read through). An entry that
  * holds none of the ids keeps its cached object.
  */
 export declare function removeManyEntries(queryClient: QueryClient, resource: string, idSet: Set<string>): void;
+export {};

package/dist/data/remove-empty.d.ts

@@ -1,3 +1,4 @@
+import type { LooseRecord } from "../resource/record.js";
 import type { FilterPayload } from "./types.js";
 /** Strips `''`, `null` and `undefined` values. Always returns a FRESH object. */
-export declare function removeEmpty(filter: FilterPayload): FilterPayload;
+export declare function removeEmpty<TRecord = LooseRecord>(filter: FilterPayload<TRecord>): FilterPayload<TRecord>;

package/dist/data/remove-empty.js

@@ -1,11 +1,9 @@
 // src/data/remove-empty.ts
 /** Strips `''`, `null` and `undefined` values. Always returns a FRESH object. */
 function removeEmpty(filter) {
-	const result = {};
-	for (const [key, value] of Object.entries(filter)) {
-		if (value === "" || value === null || value === void 0) continue;
-		result[key] = value;
-	}
+	const result = { ...filter };
+	const pruned = result;
+	for (const [key, value] of Object.entries(pruned)) if (value === "" || value === null || value === void 0) delete pruned[key];
 	return result;
 }
 export { removeEmpty };

package/dist/data/types.d.ts

@@ -1,6 +1,7 @@
 import type { Identifier } from "../resource/identifier.js";
 import type { LooseRecord, ResourceRecord } from "../resource/record.js";
 import type { RecordOf, ResourceMap } from "../resource/registry.js";
+import type { AnyFilterSourceKey, AnySourcePath, RecordFilterKey, SourcePath } from "../resource/source-path.js";
 export interface PagePagination {
     page: number;
     perPage: number;
@@ -17,17 +18,118 @@ export interface PageInfo {
     hasNextPage?: boolean;
     hasPreviousPage?: boolean;
 }
-export interface SortPayload {
+/**
+ * The sort a list applies: one field of the record and a direction.
+ *
+ * `field` is a {@link SourcePath} of the record, so sorting on a column the
+ * record does not have stops compiling. A loose record (the default, and every
+ * app that registers nothing) takes {@link AnySourcePath} instead, the same
+ * loose arm a `source` prop has, so a `DataTable` column can write its own
+ * `SourceProp` into `setSort`.
+ *
+ * A data provider verb takes {@link LooseSortPayload}: a controller generic over
+ * `TResources` cannot prove its `SortPayload<RecordOf<TResources, TName>>`
+ * assigns to the registered union.
+ */
+export interface SortPayload<TRecord = LooseRecord> {
+    field: _SortFieldOf<TRecord>;
+    order: "ASC" | "DESC";
+}
+/**
+ * The field a sort takes: the registered union of source paths for a loose
+ * record, the record's own paths for a typed one.
+ *
+ * The conditional sits on the field, never between two payload shapes: a union
+ * of a resolved arm and a deferred one is what stops two identical
+ * `SortPayload<TRecord>`s assigning to each other inside a generic function.
+ * `LooseRecord extends TRecord` is {@link SourceKey}'s guard, not the
+ * `unknown extends` the path types use: an open type parameter resolves against
+ * its constraint, and `SourcePath<ResourceRecord>` is `"id"`.
+ */
+type _SortFieldOf<TRecord> = LooseRecord extends TRecord ? AnySourcePath : SourcePath<TRecord>;
+/**
+ * A sort with no record behind it: an open field name. {@link SortPayload}'s
+ * loose field is the registered union once an app registers resources, so the
+ * verbs of {@link DataProvider}, and the code that reads what a verb receives
+ * (`applySort`, `buildOrder`), name this instead.
+ */
+export interface LooseSortPayload {
     field: string;
     order: "ASC" | "DESC";
 }
-export type FilterPayload = {
+/**
+ * A filter object: {@link RecordFilterKey}s mapped to values — a record's source
+ * paths, those paths with an operator suffix, and `q`. Keys come from the
+ * resource registry the way a `source` prop does from {@link SourceProp}, so an
+ * app that registers its resources gets `titel_gte` rejected at the call site.
+ *
+ * Values stay `unknown`: an operator suffix makes a key's value type ambiguous
+ * (`title_gte` wants a string, `views_gte` a number), and the provider decides
+ * what a value means.
+ *
+ * A loose record (the default, and every app that registers nothing) is keyed by
+ * {@link AnyFilterSourceKey}, which is plain `string` until `Register` is
+ * augmented.
+ */
+export type FilterPayload<TRecord = LooseRecord> = {
+    [TKey in _FilterKeyOf<TRecord>]?: unknown;
+};
+/**
+ * The keys a filter takes: the registered union for a loose record, the
+ * record's own keys for a typed one.
+ *
+ * `FilterPayload` maps over that union as ONE key set rather than picking one
+ * of two object shapes with a conditional. A union of a resolved arm and a
+ * deferred one is what stops two identical `FilterPayload<TRecord>`s assigning
+ * to each other inside a generic function, and mapping over `string` is how an
+ * unregistered app keeps today's plain index-signature object.
+ */
+type _FilterKeyOf<TRecord> = LooseRecord extends TRecord ? AnyFilterSourceKey : RecordFilterKey<TRecord>;
+/**
+ * A filter with no record behind it: an open key map. {@link FilterPayload}'s
+ * loose key set is the registered union once an app registers resources, so
+ * code that walks a filter key by key — pruning one, stripping empties — names
+ * this instead.
+ */
+export type LooseFilterPayload = {
     [key: string]: unknown;
 };
+/**
+ * Which filter inputs the list shows: a filter key mapped to whether its input
+ * is open. `showFilter(name)` writes `{ [name]: true }` into the filter and
+ * `hideFilter(name)` removes that path from it, so the map is keyed by the same
+ * union {@link FilterPayload} is — a name that is no filter key of the record
+ * stops compiling.
+ *
+ * The values are optional: a map over a literal key union that demanded every
+ * key would force an app to list every filter it has in order to show one.
+ */
+export type DisplayedFilters<TRecord = LooseRecord> = {
+    [TKey in _FilterKeyOf<TRecord>]?: boolean;
+};
+/**
+ * The displayed filters with no record behind it: an open key map.
+ * {@link DisplayedFilters}'s loose key set is the registered union once an app
+ * registers resources, so code that walks the map key by key — a filter form
+ * reading `displayedFilters[source]`, an adapter's list context — names this
+ * instead.
+ *
+ * The value carries `undefined` because {@link DisplayedFilters} does: a map
+ * over a literal key union with optional values has no `string` index
+ * signature of plain `boolean` to hand over, so an erased map that demanded one
+ * would reject every typed controller.
+ */
+export type LooseDisplayedFilters = {
+    [key: string]: boolean | undefined;
+};
 export interface GetListParams {
     pagination?: Pagination;
-    /** Single sort key, or multi-sort: keys applied in order (first is primary). */
-    sort?: SortPayload | SortPayload[];
+    /**
+     * Single sort key, or multi-sort: keys applied in order (first is primary).
+     * Loose, like {@link GetListParams.filter}: a verb is not generic over the
+     * record, and a controller's typed sort assigns to it with no cast.
+     */
+    sort?: LooseSortPayload | LooseSortPayload[];
     filter?: FilterPayload;
     meta?: unknown;
 }
@@ -88,8 +190,8 @@ export interface GetManyReferenceParams {
     target: string;
     id: Identifier;
     pagination?: Pagination;
-    /** Single sort key, or multi-sort: keys applied in order (first is primary). */
-    sort?: SortPayload | SortPayload[];
+    /** Single sort key, or multi-sort: keys applied in order (first is primary). Loose, as in {@link GetListParams}. */
+    sort?: LooseSortPayload | LooseSortPayload[];
     filter?: FilterPayload;
     meta?: unknown;
 }
@@ -125,3 +227,4 @@ export interface DataProvider<TResources extends ResourceMap = ResourceMap> {
     updateMany<TName extends keyof TResources & string>(resource: TName, params: UpdateManyParams<RecordOf<TResources, TName>>): Promise<UpdateManyResult>;
     deleteMany<TName extends keyof TResources & string>(resource: TName, params: DeleteManyParams): Promise<DeleteManyResult>;
 }
+export {};

package/dist/data/undoable.d.ts

@@ -1,6 +1,7 @@
 import { type QueryClient, type QueryKey } from "@tanstack/query-core";
 import type { Identifier } from "../resource/identifier.js";
-import type { LooseRecord, ResourceRecord } from "../resource/record.js";
+import type { ResourceRecord } from "../resource/record.js";
+import type { RecordOf, ResourceMap } from "../resource/registry.js";
 import type { DeleteParams, UpdateManyParams, UpdateParams } from "./types.js";
 /**
  * A snapshot of the query cache taken BEFORE an optimistic apply: an array of
@@ -102,7 +103,7 @@ export interface UndoableCacheOptions {
     };
 }
 /** Patch `ids` in the `resource` caches now; the notification reads "updated". */
-export declare function undoableUpdateOptions<TRecord extends ResourceRecord = LooseRecord>(queryClient: QueryClient, resource: string, ids: Identifier[], data: Partial<NoInfer<TRecord>>): UndoableCacheOptions;
+export declare function undoableUpdateOptions<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(queryClient: QueryClient, resource: TName, ids: Identifier[], data: Partial<RecordOf<TResources, TName>>): UndoableCacheOptions;
 /** Remove `ids` from the `resource` caches now; the notification reads "deleted". */
 export declare function undoableDeleteOptions(queryClient: QueryClient, resource: string, ids: Identifier[]): UndoableCacheOptions;
 /** The record an undoable update shows at once: the previous one with the patch on top. */

package/dist/form/choices-controller.d.ts

@@ -19,12 +19,12 @@ export type ChoiceRecord = Record<string, unknown>;
  *   (deduped by `lookupKey`), so a currently-selected value that is not on the
  *   page still renders as a labelled choice.
  */
-export interface ChoicesControllerState<TRecord> {
+export interface ChoicesControllerState<TRecord, TName extends string = string> {
     page: number;
     perPage: number;
-    sort: SortPayload;
+    sort: SortPayload<TRecord>;
     /** The dynamic (user) filter — permanent filter is merged in on fetch. */
-    filter: FilterPayload;
+    filter: FilterPayload<TRecord>;
     /** All choices: page + missing selected prepended (deduped by lookupKey). */
     allChoices: TRecord[];
     /** The fetched page only. */
@@ -40,19 +40,19 @@ export interface ChoicesControllerState<TRecord> {
     isFetching: boolean;
     error: Error | null;
     /** The referenced resource name. */
-    resource: string;
+    resource: TName;
     /** The FK field on the referencing side (metadata for consumers). */
     source: string | undefined;
     /** Always `true` — distinguishes a reference-backed context from an inline-choices one. */
     isFromReference: true;
 }
-export interface ChoicesController<TRecord> extends MicroStore<ChoicesControllerState<TRecord>> {
+export interface ChoicesController<TRecord, TName extends string = string> extends MicroStore<ChoicesControllerState<TRecord, TName>> {
     setPage(page: number): void;
     setPerPage(perPage: number): void;
     /** Replaces the sort and resets the page to 1. */
-    setSort(sort: SortPayload): void;
+    setSort(sort: SortPayload<TRecord>): void;
     /** Sets the dynamic filter (`removeEmpty` applied). `debounce` delays by `debounceMs`. */
-    setFilters(filter: FilterPayload, debounce?: boolean): void;
+    setFilters(filter: FilterPayload<TRecord>, debounce?: boolean): void;
     /** Feeds the selected-record resolution. Scalar or array; `null`/`[]` clears. */
     setValue(value: unknown): void;
     refetch(): void;
@@ -71,12 +71,12 @@ export interface ChoicesControllerOptions<TResources extends ResourceMap = Resou
      */
     lookupKey?: SourceKey<RecordOf<TResources, TName>>;
     /** Permanent filter — merged OVER the dynamic filter for every choices fetch. */
-    filter?: FilterPayload;
+    filter?: FilterPayload<RecordOf<TResources, TName>>;
     page?: number;
     perPage?: number;
-    sort?: SortPayload;
+    sort?: SortPayload<RecordOf<TResources, TName>>;
     /** Gate the CHOICES query on the current filter values. Selected always resolves. */
-    enableGetChoices?: (filterValues: FilterPayload) => boolean;
+    enableGetChoices?: (filterValues: FilterPayload<RecordOf<TResources, TName>>) => boolean;
     /** Debounce delay for `setFilters(..., true)`. Default 500ms. */
     debounceMs?: number;
     /** The FK source field on the referencing side (metadata only). */
@@ -99,7 +99,7 @@ export interface ChoicesControllerOptions<TResources extends ResourceMap = Resou
  * actions (`setPage`/`setSort`/`setFilters`/`setValue`), never from the
  * observer result subscription — the subscription only maps results into state.
  */
-export declare function createChoicesController<TResources extends ResourceMap, TName extends keyof TResources & string>(ctx: ChoicesControllerContext<TResources>, options: ChoicesControllerOptions<TResources, TName>): ChoicesController<RecordOf<TResources, TName>>;
+export declare function createChoicesController<TResources extends ResourceMap, TName extends keyof TResources & string>(ctx: ChoicesControllerContext<TResources>, options: ChoicesControllerOptions<TResources, TName>): ChoicesController<RecordOf<TResources, TName>, TName>;
 /** The three choice views of a state, erased to `ChoiceRecord[]`. */
 export interface ChoiceLists {
     allChoices: ChoiceRecord[];
@@ -112,4 +112,11 @@ export interface ChoiceLists {
  * `ChoiceRecord`, so neither adapter writes the cast. The arrays are the
  * state's own, not copies.
  */
-export declare function choiceListsOf<TRecord>(state: ChoicesControllerState<TRecord>): ChoiceLists;
+export declare function choiceListsOf<TRecord, TName extends string>(state: ChoicesControllerState<TRecord, TName>): ChoiceLists;
+/**
+ * The controller's sort, filter and actions as an adapter's erased
+ * `ChoicesContextValue` carries them: over `ChoiceRecord`, not the referenced
+ * record. The lists go through {@link choiceListsOf}. It is the same object, so
+ * every action still reaches the controller.
+ */
+export declare function eraseChoicesController<TRecord, TName extends string>(controller: ChoicesController<TRecord, TName>): ChoicesController<ChoiceRecord>;

package/dist/form/choices-controller.js

@@ -6,10 +6,13 @@ import { createMicroStore } from "../store/micro-store.js";
 import { QueryObserver, keepPreviousData } from "@tanstack/query-core";
 // src/form/choices-controller.ts
 var DEFAULT_PAGE = 1;
-var DEFAULT_SORT = {
-	field: "id",
-	order: "DESC"
-};
+/** The sort of a controller given none: `id`, which every record has. */
+function defaultSort() {
+	return {
+		field: "id",
+		order: "DESC"
+	};
+}
 /** perPage for the non-id selected getList — generous, real values sets are small. */
 var SELECTED_LIST_PER_PAGE = 1e3;
 /** Normalizes a value into a non-empty identifier list, or `[]` when there is nothing to resolve. */
@@ -36,12 +39,12 @@ function createChoicesController(ctx, options) {
 	const reference = options.reference;
 	const lookupKey = options.lookupKey ?? "id";
 	const isIdLookup = lookupKey === "id";
-	const permanentFilter = options.filter ?? {};
+	const permanentFilter = options.filter === void 0 ? {} : options.filter;
 	const debounceMs = options.debounceMs ?? 500;
 	const store = createMicroStore({
 		page: options.page ?? DEFAULT_PAGE,
 		perPage: options.perPage ?? 25,
-		sort: { ...options.sort ?? DEFAULT_SORT },
+		sort: { ...options.sort ?? defaultSort() },
 		filter: {},
 		allChoices: [],
 		availableChoices: [],
@@ -318,4 +321,13 @@ function choiceListsOf(state) {
 		selectedChoices
 	};
 }
-export { choiceListsOf, createChoicesController };
+/**
+* The controller's sort, filter and actions as an adapter's erased
+* `ChoicesContextValue` carries them: over `ChoiceRecord`, not the referenced
+* record. The lists go through {@link choiceListsOf}. It is the same object, so
+* every action still reaches the controller.
+*/
+function eraseChoicesController(controller) {
+	return controller;
+}
+export { choiceListsOf, createChoicesController, eraseChoicesController };

package/dist/form/filter-form-values.d.ts

@@ -1,4 +1,5 @@
 import type { FilterPayload } from "../data/types.js";
+import type { LooseRecord } from "../resource/record.js";
 /**
  * Rebuild form values from the incoming filter so EVERY current form key is
  * present with a defined value (an empty string when the filter lacks it).
@@ -8,7 +9,7 @@ import type { FilterPayload } from "../data/types.js";
  * reset must carry a value for every mounted input. This never produces
  * `undefined`/`null` for a present form key.
  */
-export declare function getFilterFormValues(formValues: Record<string, unknown>, filter: Record<string, unknown>): Record<string, unknown>;
+export declare function getFilterFormValues<TRecord = LooseRecord>(formValues: Record<string, unknown>, filter: FilterPayload<TRecord>): Record<string, unknown>;
 /**
  * The form shape the external-reflect must cover: every key that is either a
  * current form value, a REGISTERED field (form-core tracks these in `fieldMeta`
@@ -16,10 +17,10 @@ export declare function getFilterFormValues(formValues: Record<string, unknown>,
  * carried through; registered-but-unset / filter-only keys seed to `undefined`
  * so {@link getFilterFormValues} resolves them from the filter (fallback `''`).
  */
-export declare function filterFormReflectShape(values: Record<string, unknown>, fieldMeta: Record<string, unknown>, filter: Record<string, unknown>): Record<string, unknown>;
+export declare function filterFormReflectShape<TRecord = LooseRecord>(values: Record<string, unknown>, fieldMeta: Record<string, unknown>, filter: FilterPayload<TRecord>): Record<string, unknown>;
 /**
  * Merge form values OVER the existing filter, one level deep, with arrays
  * REPLACED (never element-merged) — matching ra's mergeObjNotArray. The result
  * is a fresh object (no mutation of the inputs).
  */
-export declare function mergeFilterValues(filter: Record<string, unknown>, values: Record<string, unknown>): FilterPayload;
+export declare function mergeFilterValues<TRecord = LooseRecord>(filter: FilterPayload<TRecord>, values: FilterPayload<TRecord>): FilterPayload<TRecord>;

package/dist/form/filter-form-values.js

@@ -56,14 +56,16 @@ function filterFormReflectShape(values, fieldMeta, filter) {
 */
 function mergeFilterValues(filter, values) {
 	const merged = { ...filter };
-	for (const key of Object.keys(values)) {
-		const next = values[key];
-		const prev = merged[key];
-		if (isFilterBranch(next) && isFilterBranch(prev)) merged[key] = {
+	const incoming = values;
+	const target = merged;
+	for (const key of Object.keys(incoming)) {
+		const next = incoming[key];
+		const prev = target[key];
+		if (isFilterBranch(next) && isFilterBranch(prev)) target[key] = {
 			...prev,
 			...next
 		};
-		else merged[key] = next;
+		else target[key] = next;
 	}
 	return merged;
 }