@chelone/core 0.5.0 → 0.7.0

package/dist/controller/list-params.js

@@ -1,103 +1,112 @@
+import { isRecord } from "../guards.js";
+// src/controller/list-params.ts
 function isSortOrder(value) {
-  return value === "ASC" || value === "DESC";
+	return value === "ASC" || value === "DESC";
 }
+/**
+* Serialize URL-shaped list params into a query string (with a leading `?`,
+* or `''` when no field is set). Only defined fields are emitted; `filter` and
+* `displayedFilters` are JSON-encoded (an empty object serializes as `{}`).
+*/
 function serializeListParams(params) {
-  const search = new URLSearchParams();
-  if (params.filter !== void 0) {
-    search.set("filter", JSON.stringify(params.filter));
-  }
-  if (params.displayedFilters !== void 0) {
-    search.set("displayedFilters", JSON.stringify(params.displayedFilters));
-  }
-  if (params.sort !== void 0) {
-    search.set("sort", params.sort);
-  }
-  if (params.order !== void 0) {
-    search.set("order", params.order);
-  }
-  if (params.page !== void 0) {
-    search.set("page", String(params.page));
-  }
-  if (params.perPage !== void 0) {
-    search.set("perPage", String(params.perPage));
-  }
-  const encoded = search.toString();
-  return encoded ? `?${encoded}` : "";
+	const search = new URLSearchParams();
+	if (params.filter !== void 0) search.set("filter", JSON.stringify(params.filter));
+	if (params.displayedFilters !== void 0) search.set("displayedFilters", JSON.stringify(params.displayedFilters));
+	if (params.sort !== void 0) search.set("sort", params.sort);
+	if (params.order !== void 0) search.set("order", params.order);
+	if (params.page !== void 0) search.set("page", String(params.page));
+	if (params.perPage !== void 0) search.set("perPage", String(params.perPage));
+	const encoded = search.toString();
+	return encoded ? `?${encoded}` : "";
 }
+/**
+* Parse a JSON-encoded object param; returns `undefined` on absence, bad JSON,
+* or JSON that is not a plain object (`null`, an array, a primitive).
+*/
 function parseJsonObjectParam(raw) {
-  if (raw === null) return void 0;
-  try {
-    const parsed = JSON.parse(raw);
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
-      return void 0;
-    return parsed;
-  } catch {
-    return void 0;
-  }
+	if (raw === null) return void 0;
+	try {
+		const parsed = JSON.parse(raw);
+		if (!isRecord(parsed)) return void 0;
+		return parsed;
+	} catch {
+		return;
+	}
 }
+/** Parse a positive integer param; returns `undefined` on absence, non-numeric input, or a value below 1. */
 function parsePositiveIntParam(raw) {
-  if (raw === null) return void 0;
-  const parsed = Number.parseInt(raw, 10);
-  return parsed >= 1 ? parsed : void 0;
+	if (raw === null) return void 0;
+	const parsed = Number.parseInt(raw, 10);
+	return parsed >= 1 ? parsed : void 0;
 }
+/**
+* Parse a query string (with or without a leading `?`) into URL-shaped list
+* params. Malformed values are ignored, never trusted or thrown: bad JSON, or
+* JSON that is not an object, on `filter`/`displayedFilters`; a non-numeric
+* `page`/`perPage`, or one below 1; and an `order` outside `ASC`/`DESC` are
+* simply omitted. `order` is upper-cased first.
+*/
 function parseListParams(search) {
-  const params = new URLSearchParams(
-    search.startsWith("?") ? search.slice(1) : search
-  );
-  const result = {};
-  const filter = parseJsonObjectParam(params.get("filter"));
-  if (filter !== void 0) result.filter = filter;
-  const displayedFilters = parseJsonObjectParam(
-    params.get("displayedFilters")
-  );
-  if (displayedFilters !== void 0)
-    result.displayedFilters = displayedFilters;
-  const sort = params.get("sort");
-  if (sort !== null) result.sort = sort;
-  const rawOrder = params.get("order");
-  if (rawOrder !== null) {
-    const order = rawOrder.toUpperCase();
-    if (isSortOrder(order)) result.order = order;
-  }
-  const page = parsePositiveIntParam(params.get("page"));
-  if (page !== void 0) result.page = page;
-  const perPage = parsePositiveIntParam(params.get("perPage"));
-  if (perPage !== void 0) result.perPage = perPage;
-  return result;
+	const params = new URLSearchParams(search.startsWith("?") ? search.slice(1) : search);
+	const result = {};
+	const filter = parseJsonObjectParam(params.get("filter"));
+	if (filter !== void 0) result.filter = filter;
+	const displayedFilters = parseJsonObjectParam(params.get("displayedFilters"));
+	if (displayedFilters !== void 0) result.displayedFilters = displayedFilters;
+	const sort = params.get("sort");
+	if (sort !== null) result.sort = sort;
+	const rawOrder = params.get("order");
+	if (rawOrder !== null) {
+		const order = rawOrder.toUpperCase();
+		if (isSortOrder(order)) result.order = order;
+	}
+	const page = parsePositiveIntParam(params.get("page"));
+	if (page !== void 0) result.page = page;
+	const perPage = parsePositiveIntParam(params.get("perPage"));
+	if (perPage !== void 0) result.perPage = perPage;
+	return result;
 }
+/**
+* Whether the user has set any non-default list param — a filter with keys, an
+* explicit sort/order, a page other than 1, or a perPage. Used by adapters to
+* decide whether to seed the URL/store from these params or fall back to option
+* defaults. Mirrors react-admin's `hasCustomParams` semantics (an empty filter
+* and `page === 1` are not "custom"), without its filter-must-be-present guard.
+*/
 function hasCustomParams(params) {
-  return params.filter !== void 0 && Object.keys(params.filter).length > 0 || params.sort !== void 0 || params.order !== void 0 || params.page !== void 0 && params.page !== 1 || params.perPage !== void 0;
+	return params.filter !== void 0 && Object.keys(params.filter).length > 0 || params.sort !== void 0 || params.order !== void 0 || params.page !== void 0 && params.page !== 1 || params.perPage !== void 0;
 }
+/** The query string for a list's state; the primary sort becomes `sort`/`order`. */
 function serializeListState(state) {
-  const primary = state.sort[0];
-  return serializeListParams({
-    filter: state.filter,
-    displayedFilters: state.displayedFilters,
-    sort: primary?.field,
-    order: primary?.order,
-    page: state.page,
-    perPage: state.perPage
-  });
+	const primary = state.sort[0];
+	return serializeListParams({
+		filter: state.filter,
+		displayedFilters: state.displayedFilters,
+		sort: primary?.field,
+		order: primary?.order,
+		page: state.page,
+		perPage: state.perPage
+	});
 }
+/**
+* The params a URL query string sets, as one `setParams` patch, or `null` when
+* it sets none of {@link hasCustomParams}, so a clean URL keeps the option and
+* store defaults. Shown filter inputs without a filter clear the filter.
+*/
 function listPatchFromSearch(search) {
-  const query = parseListParams(search);
-  if (!hasCustomParams(query)) return null;
-  const patch = {};
-  if (query.filter !== void 0 || query.displayedFilters !== void 0) {
-    patch.filter = query.filter ?? {};
-    patch.displayedFilters = query.displayedFilters;
-  }
-  if (query.sort !== void 0) {
-    patch.sort = { field: query.sort, order: query.order ?? "ASC" };
-  }
-  if (query.perPage !== void 0) patch.perPage = query.perPage;
-  if (query.page !== void 0) patch.page = query.page;
-  return patch;
+	const query = parseListParams(search);
+	if (!hasCustomParams(query)) return null;
+	const patch = {};
+	if (query.filter !== void 0 || query.displayedFilters !== void 0) {
+		patch.filter = query.filter ?? {};
+		patch.displayedFilters = query.displayedFilters;
+	}
+	if (query.sort !== void 0) patch.sort = {
+		field: query.sort,
+		order: query.order ?? "ASC"
+	};
+	if (query.perPage !== void 0) patch.perPage = query.perPage;
+	if (query.page !== void 0) patch.page = query.page;
+	return patch;
 }
-export {
-  hasCustomParams,
-  listPatchFromSearch,
-  parseListParams,
-  serializeListParams,
-  serializeListState
-};
+export { hasCustomParams, listPatchFromSearch, parseListParams, serializeListParams, serializeListState };

package/dist/controller/pivot-grid.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure rule for pivoting a flat record list into a row by column table. No
+ * react, no vue: both PivotGrid adapters build the same table from the same
+ * records and print numbers the same way.
+ */
+import type { SourcePath } from "../resource/source-path.js";
+export type PivotAggregator = "count" | "sum" | "avg" | "min" | "max";
+export interface PivotOptions<R> {
+    rowSource: SourcePath<R>;
+    columnSource: SourcePath<R>;
+    /** Read by every aggregator but `count`. */
+    valueSource?: SourcePath<R>;
+    /** Defaults to `count`. */
+    aggregator?: PivotAggregator;
+}
+export interface PivotTable {
+    rowKeys: string[];
+    columnKeys: string[];
+    /** `cells[row][column]` follows the order of `rowKeys` and `columnKeys`. */
+    cells: (number | null)[][];
+    rowTotals: (number | null)[];
+    columnTotals: (number | null)[];
+    grandTotal: number | null;
+}
+/**
+ * A row or column key is `String(value)`, and a null, undefined or empty value
+ * is the key `""`. Keys sort numerically (`10` after `9`) with `""` last.
+ * `count` counts records and ignores `valueSource`. The other aggregators use
+ * finite numbers and numeric strings, and skip anything else. A cell with no
+ * records is `null`, and so is a cell with no usable value, unless it counts.
+ * A total aggregates the raw values of its row, column or table, never the
+ * cell results, so an average total is not a sum of averages.
+ */
+export declare function buildPivotTable<R>(records: readonly R[], options: PivotOptions<R>): PivotTable;
+/** Integers print bare and fractions round to two digits. */
+export declare function formatPivotValue(value: number, locale?: string): string;

package/dist/controller/pivot-grid.js

@@ -0,0 +1,99 @@
+import { getAtPath } from "../resource/get-at-path.js";
+// src/controller/pivot-grid.ts
+/**
+* Pure rule for pivoting a flat record list into a row by column table. No
+* react, no vue: both PivotGrid adapters build the same table from the same
+* records and print numbers the same way.
+*/
+var collator = new Intl.Collator(void 0, { numeric: true });
+var NUMERIC_KEY = /^-?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i;
+var compareKeys = (a, b) => {
+	if (a === b) return 0;
+	if (a === "") return 1;
+	if (b === "") return -1;
+	if (NUMERIC_KEY.test(a) && NUMERIC_KEY.test(b)) {
+		const difference = Number(a) - Number(b);
+		if (difference !== 0 && !Number.isNaN(difference)) return difference;
+	}
+	return collator.compare(a, b) || (a < b ? -1 : 1);
+};
+var toKey = (value) => value == null || value === "" ? "" : String(value);
+var toNumber = (value) => {
+	if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+	if (typeof value === "string" && value !== "") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : void 0;
+	}
+};
+var aggregate = (group, aggregator) => {
+	if (group.count === 0) return null;
+	if (aggregator === "count") return group.count;
+	const { values } = group;
+	if (values.length === 0) return null;
+	switch (aggregator) {
+		case "sum": return values.reduce((total, value) => total + value, 0);
+		case "avg": return values.reduce((total, value) => total + value, 0) / values.length;
+		case "min": return values.reduce((a, b) => b < a ? b : a);
+		case "max": return values.reduce((a, b) => b > a ? b : a);
+	}
+};
+var newGroup = () => ({
+	count: 0,
+	values: []
+});
+var getOrCreate = (map, key, create) => {
+	const existing = map.get(key);
+	if (existing !== void 0) return existing;
+	const created = create();
+	map.set(key, created);
+	return created;
+};
+var add = (group, value) => {
+	group.count += 1;
+	if (value !== void 0) group.values.push(value);
+};
+/**
+* A row or column key is `String(value)`, and a null, undefined or empty value
+* is the key `""`. Keys sort numerically (`10` after `9`) with `""` last.
+* `count` counts records and ignores `valueSource`. The other aggregators use
+* finite numbers and numeric strings, and skip anything else. A cell with no
+* records is `null`, and so is a cell with no usable value, unless it counts.
+* A total aggregates the raw values of its row, column or table, never the
+* cell results, so an average total is not a sum of averages.
+*/
+function buildPivotTable(records, options) {
+	const { rowSource, columnSource, valueSource, aggregator = "count" } = options;
+	const readsValue = aggregator !== "count" && valueSource !== void 0;
+	const cellGroups = /* @__PURE__ */ new Map();
+	const rowGroups = /* @__PURE__ */ new Map();
+	const columnGroups = /* @__PURE__ */ new Map();
+	const tableGroup = newGroup();
+	for (const record of records) {
+		const row = toKey(getAtPath(record, rowSource));
+		const column = toKey(getAtPath(record, columnSource));
+		const value = readsValue ? toNumber(getAtPath(record, valueSource)) : void 0;
+		const cell = getOrCreate(getOrCreate(cellGroups, row, () => /* @__PURE__ */ new Map()), column, newGroup);
+		const rowGroup = getOrCreate(rowGroups, row, newGroup);
+		const columnGroup = getOrCreate(columnGroups, column, newGroup);
+		add(cell, value);
+		add(rowGroup, value);
+		add(columnGroup, value);
+		add(tableGroup, value);
+	}
+	const rowKeys = [...rowGroups.keys()].sort(compareKeys);
+	const columnKeys = [...columnGroups.keys()].sort(compareKeys);
+	const empty = newGroup();
+	return {
+		rowKeys,
+		columnKeys,
+		cells: rowKeys.map((row) => columnKeys.map((column) => aggregate(cellGroups.get(row)?.get(column) ?? empty, aggregator))),
+		rowTotals: rowKeys.map((row) => aggregate(rowGroups.get(row), aggregator)),
+		columnTotals: columnKeys.map((column) => aggregate(columnGroups.get(column), aggregator)),
+		grandTotal: aggregate(tableGroup, aggregator)
+	};
+}
+/** Integers print bare and fractions round to two digits. */
+function formatPivotValue(value, locale) {
+	return new Intl.NumberFormat(locale, { maximumFractionDigits: 2 }).format(value);
+}
+export { buildPivotTable, formatPivotValue };

package/dist/controller/prev-next.d.ts

@@ -4,7 +4,7 @@
  * and the cached page, then asks these functions what to fetch and who the
  * neighbours are.
  */
-import type { FilterPayload, GetListParams, GetListResult, SortPayload } from "../data/types.js";
+import type { FilterPayload, GetListParams, GetListResult, InfiniteListParams, SortPayload } from "../data/types.js";
 import type { Identifier } from "../resource/identifier.js";
 /** The list's persisted params, read from the `<resource>.listParams` store key. */
 export interface PrevNextStoredParams {
@@ -31,7 +31,7 @@ export interface PrevNextOptions {
 }
 export interface PrevNextParams {
     /** The page the list itself showed: the key its query cached it under. */
-    cached: GetListParams;
+    cached: InfiniteListParams;
     /** The first `limit` rows, for when the cached page cannot serve. */
     fetch: GetListParams;
 }

package/dist/controller/prev-next.js

@@ -1,62 +1,82 @@
-const DEFAULT_PREV_NEXT_LIMIT = 1e3;
-const DEFAULT_PER_PAGE = 10;
-const DEFAULT_SORT = { field: "id", order: "ASC" };
+// src/controller/prev-next.ts
+var DEFAULT_PREV_NEXT_LIMIT = 1e3;
+var DEFAULT_PER_PAGE = 10;
+var DEFAULT_SORT = {
+	field: "id",
+	order: "ASC"
+};
+/**
+* A list keys its query with a single sort object when there is exactly one
+* sort key, so the cached page is found only under that shape.
+*/
 function toListSort(sort) {
-  if (Array.isArray(sort)) {
-    return sort.length === 1 ? { ...sort[0] } : sort;
-  }
-  return sort ?? { ...DEFAULT_SORT };
+	if (Array.isArray(sort)) {
+		const [only] = sort;
+		return sort.length === 1 && only ? { ...only } : sort;
+	}
+	return sort ?? { ...DEFAULT_SORT };
 }
 function getPrevNextParams(stored, options = {}) {
-  const persisted = options.storeKey === false ? void 0 : stored;
-  const page = persisted?.page ?? 1;
-  const perPage = persisted?.perPage ?? DEFAULT_PER_PAGE;
-  const sort = toListSort(
-    persisted?.sort && (!Array.isArray(persisted.sort) || persisted.sort.length) ? persisted.sort : options.sort
-  );
-  const filter = {
-    ...persisted?.filter ?? options.filterDefaultValues,
-    ...options.filter
-  };
-  return {
-    cached: { pagination: { page, perPage }, sort, filter },
-    fetch: {
-      pagination: {
-        page: 1,
-        perPage: options.limit ?? DEFAULT_PREV_NEXT_LIMIT
-      },
-      sort,
-      filter,
-      meta: options.meta
-    }
-  };
+	const persisted = options.storeKey === false ? void 0 : stored;
+	const page = persisted?.page ?? 1;
+	const perPage = persisted?.perPage ?? DEFAULT_PER_PAGE;
+	const sort = toListSort(persisted?.sort && (!Array.isArray(persisted.sort) || persisted.sort.length) ? persisted.sort : options.sort);
+	const filter = {
+		...persisted?.filter ?? options.filterDefaultValues,
+		...options.filter
+	};
+	return {
+		cached: {
+			pagination: {
+				page,
+				perPage
+			},
+			sort,
+			filter
+		},
+		fetch: {
+			pagination: {
+				page: 1,
+				perPage: options.limit ?? 1e3
+			},
+			sort,
+			filter,
+			meta: options.meta
+		}
+	};
 }
+/**
+* Whether the page a list cached holds both neighbours of `id`. The first row
+* of a later page has its previous record on the page before, and the last row
+* of an earlier page has its next one on the page after.
+*/
 function canUseCachedPage(id, cached, page, perPage) {
-  if (!cached) return false;
-  const index = cached.data.findIndex((record) => record.id === id);
-  if (index === -1) return false;
-  if (index === 0 && page > 1) return false;
-  if (index === cached.data.length - 1) {
-    const hasMore = cached.total != null ? page * perPage < cached.total : cached.pageInfo?.hasNextPage ?? false;
-    if (hasMore) return false;
-  }
-  return true;
+	if (!cached) return false;
+	const index = cached.data.findIndex((record) => record.id === id);
+	if (index === -1) return false;
+	if (index === 0 && page > 1) return false;
+	if (index === cached.data.length - 1) {
+		if (cached.total != null ? page * perPage < cached.total : cached.pageInfo?.hasNextPage ?? false) return false;
+	}
+	return true;
 }
+/**
+* The neighbours of `id` among `records`. `offset` is the number of rows that
+* precede `records` in the whole list, so `index` is a position in that list.
+*/
 function resolvePrevNext(id, records, total, offset) {
-  const position = records.findIndex((record) => record.id === id);
-  if (position === -1) {
-    return { prevId: null, nextId: null, index: void 0, total };
-  }
-  return {
-    prevId: records[position - 1]?.id ?? null,
-    nextId: records[position + 1]?.id ?? null,
-    index: position + offset,
-    total
-  };
+	const position = records.findIndex((record) => record.id === id);
+	if (position === -1) return {
+		prevId: null,
+		nextId: null,
+		index: void 0,
+		total
+	};
+	return {
+		prevId: records[position - 1]?.id ?? null,
+		nextId: records[position + 1]?.id ?? null,
+		index: position + offset,
+		total
+	};
 }
-export {
-  DEFAULT_PREV_NEXT_LIMIT,
-  canUseCachedPage,
-  getPrevNextParams,
-  resolvePrevNext
-};
+export { DEFAULT_PREV_NEXT_LIMIT, canUseCachedPage, getPrevNextParams, resolvePrevNext };

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

@@ -2,6 +2,7 @@ import { type MutationMode } from "../data/mutation-options.js";
 import { type DataContext } from "../data/query-options.js";
 import type { NotificationStore } from "../notification/notification-store.js";
 import type { Identifier } from "../resource/identifier.js";
+import type { ResourceRecord } from "../resource/record.js";
 import type { RecordOf, ResourceMap } from "../resource/registry.js";
 import { type MicroStore } from "../store/micro-store.js";
 import type { CheloneStore } from "../store/store.js";
@@ -9,7 +10,7 @@ export interface ShowControllerState<TRecord> {
     record: TRecord | undefined;
     isPending: boolean;
     isFetching: boolean;
-    error: unknown;
+    error: Error | null;
 }
 export interface EditControllerState<TRecord> extends ShowControllerState<TRecord> {
     saving: boolean;
@@ -19,7 +20,7 @@ export type RedirectTarget = "list" | "edit" | "show" | "create";
  * Controllers NEVER touch a router or window — navigation intent surfaces as
  * this callback and the adapter (or app) decides what to do with it.
  */
-export type RedirectRequest = (target: RedirectTarget, resource: string, id?: Identifier, data?: unknown) => void;
+export type RedirectRequest = (target: RedirectTarget, resource: string, id?: Identifier, data?: ResourceRecord) => void;
 export interface RecordControllerContext<TResources extends ResourceMap = ResourceMap> extends DataContext<TResources> {
     notifications?: NotificationStore;
     translate?: (key: string) => string;
@@ -39,17 +40,24 @@ export type SaveTransform<TRecord> = (data: Partial<TRecord>, extra?: {
     previousData?: TRecord;
 }) => Partial<TRecord> | Promise<Partial<TRecord>>;
 export interface SaveOptions<TRecord> {
-    /** Call-time transform — takes priority over the controller-level one. */
-    transform?: SaveTransform<TRecord>;
+    /**
+     * Call-time transform — takes priority over the controller-level one.
+     * Declared as a method (like `onSaved` and `onSuccess`) so `SaveOptions<Post>`
+     * stays assignable to `SaveOptions<ResourceRecord>`: a view publishes its
+     * `save` into a context typed for the default record.
+     */
+    transform?(data: Partial<TRecord>, extra?: {
+        previousData?: TRecord;
+    }): Partial<TRecord> | Promise<Partial<TRecord>>;
     /**
      * OBSERVES the saved record WITHOUT replacing the default success handling
      * (runs before `onSuccess`/defaults). The P5 composed form controllers
      * reconcile form state with server truth through this — the save contract
      * itself resolves `FieldErrors | undefined`, never the record.
      */
-    onSaved?: (record: TRecord) => void | Promise<void>;
+    onSaved?(record: TRecord): void | Promise<void>;
     /** REPLACES the default success handling (notify + redirect request). */
-    onSuccess?: (record: TRecord) => void | Promise<void>;
+    onSuccess?(record: TRecord): void | Promise<void>;
     /** REPLACES the default error handling (the http_error notify). */
     onError?: (error: unknown) => void | Promise<void>;
     meta?: unknown;