@jxsuite/parser 2.0.1 → 3.0.0

package/src/content-routes.ts

@@ -16,6 +16,8 @@
  * @docs framework/site/content-collections
  */
 
+import { isBoolean, isNumber, isString } from "@jxsuite/schema/guards";
+import type { ContentFieldValue, ContentLoaderEntry, JsonValue } from "@jxsuite/schema/types";
 import { readField } from "./content-rules.ts";
 
 // ─── slugs ──────────────────────────────────────────────────────────────────
@@ -56,7 +58,18 @@ export function slugifyPath(text: string): string {
 
 // ─── templates ──────────────────────────────────────────────────────────────
 
-const TRANSFORMS: Record<string, (value: string) => string> = {
+/**
+ * The transforms a placeholder may name, looked up by the name a template spells. The four built-in
+ * transforms are always present; any other name is checked with `in` before it is applied.
+ */
+interface RouteTransforms extends Readonly<Record<string, (value: string) => string>> {
+  readonly lower: (value: string) => string;
+  readonly raw: (value: string) => string;
+  readonly slug: (value: string) => string;
+  readonly upper: (value: string) => string;
+}
+
+const TRANSFORMS: RouteTransforms = {
   lower: (value) => value.toLowerCase(),
   raw: (value) => value,
   slug: slugifyPath,
@@ -85,8 +98,8 @@ export interface RouteSpec {
  * `project.json` fails the build on the first entry rather than producing routes with the
  * placeholder text in them.
  */
-export function parseRouteTemplate(source: unknown, where: string): RouteTemplate {
-  if (typeof source !== "string" || !source.startsWith("/")) {
+export function parseRouteTemplate(source: JsonValue, where: string): RouteTemplate {
+  if (!isString(source) || !source.startsWith("/")) {
     throw new TypeError(
       `${where}: a route template is a site-absolute path starting with "/", got ${JSON.stringify(source)}`,
     );
@@ -94,7 +107,7 @@ export function parseRouteTemplate(source: unknown, where: string): RouteTemplat
   const tokens: Token[] = [];
   let last = 0;
   for (const match of source.matchAll(/\{([^{}]*)\}/g)) {
-    const index = match.index ?? 0;
+    const { index } = match;
     if (index > last) {
       tokens.push({ literal: source.slice(last, index) });
     }
@@ -128,8 +141,8 @@ export function parseRouteTemplate(source: unknown, where: string): RouteTemplat
  * entry template would route the READMEs and leave every other document without a URL.
  */
 export function parseRouteConfig(
-  route: unknown,
-  indexRoute: unknown,
+  route: JsonValue | undefined,
+  indexRoute: JsonValue | undefined,
   typeName: string,
 ): RouteSpec | null {
   const where = `Content type "${typeName}"`;
@@ -152,7 +165,7 @@ export interface RouteSubject {
   /** The entry id (after `idField`). */
   id: string;
   /** Frontmatter / entry data. */
-  data: Record<string, unknown>;
+  data: ContentLoaderEntry["data"];
   /** The source file, relative to the source root, `/`-separated, with its extension. */
   path: string;
 }
@@ -178,11 +191,11 @@ export function directoryOf(path: string): string {
 }
 
 /** A field value as route text, or null when it cannot name a path segment. */
-function textOf(value: unknown): string | null {
-  if (typeof value === "string") {
+function textOf(value: ContentFieldValue | undefined): string | null {
+  if (isString(value)) {
     return value.trim() === "" ? null : value;
   }
-  if (typeof value === "number" || typeof value === "boolean") {
+  if (isNumber(value) || isBoolean(value)) {
     return String(value);
   }
   if (value instanceof Date && !Number.isNaN(value.getTime())) {

package/src/content-rules.ts

@@ -16,6 +16,9 @@
  * @docs framework/site/content-collections
  */
 
+import { isBoolean, isNumber, isString } from "@jxsuite/schema/guards";
+import type { ContentFieldValue, ContentLoaderEntry, JsonValue } from "@jxsuite/schema/types";
+
 // ─── exclude: globs relative to the source root ─────────────────────────────
 
 /**
@@ -225,7 +228,8 @@ export function compileExclude(patterns?: readonly string[]): ExcludeMatcher {
   const dirs: RegExp[] = [];
   let everything = false;
   for (const pattern of patterns) {
-    if (typeof pattern !== "string" || pattern.trim() === "") {
+    // The list is project.json data, so an entry is checked rather than trusted to be text.
+    if (!isString(pattern) || pattern.trim() === "") {
       throw new TypeError(
         `"exclude" entries must be non-empty strings, got ${JSON.stringify(pattern)}`,
       );
@@ -266,27 +270,33 @@ export function compileExclude(patterns?: readonly string[]): ExcludeMatcher {
 
 // ─── where: a declarative frontmatter filter ────────────────────────────────
 
+/** An entry's frontmatter as a filter reads it: field name → value, absent when it is not set. */
+type FieldData = ContentLoaderEntry["data"];
+
+/** A field value, or an operand, in the form a filter compares; `undefined` is a missing field. */
+type FieldValue = ContentFieldValue | undefined;
+
 /** Whether an entry's frontmatter passes a compiled `where`. */
 export interface WherePredicate {
-  (data: Record<string, unknown>): boolean;
+  (data: FieldData): boolean;
   /**
    * The first field whose condition `data` fails, for a message that says why an entry was left
    * out.
    */
-  why: (data: Record<string, unknown>) => string | undefined;
+  why: (data: FieldData) => string | undefined;
 }
 
 /** The query operators. Closed on purpose: see the module comment. */
 const OPERATORS = new Set(["$eq", "$ne", "$in", "$nin", "$exists", "$gt", "$gte", "$lt", "$lte"]);
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
+function isPlainObject(value: FieldValue | FieldData): value is FieldData {
   return (
     typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date)
   );
 }
 
 /** A frontmatter value in the form a filter compares: YAML dates become RFC 3339 text. */
-function comparable(value: unknown): unknown {
+function comparable(value: FieldValue): FieldValue {
   if (value instanceof Date) {
     if (Number.isNaN(value.getTime())) {
       return undefined;
@@ -297,7 +307,7 @@ function comparable(value: unknown): unknown {
   return value;
 }
 
-function deepEqual(a: unknown, b: unknown): boolean {
+function deepEqual(a: FieldValue, b: FieldValue): boolean {
   if (a === b) {
     return true;
   }
@@ -321,7 +331,7 @@ function deepEqual(a: unknown, b: unknown): boolean {
  * it, so `{"tags": "frappe"}` selects every entry tagged frappe without a second operator. An array
  * or object operand compares as a whole value.
  */
-function sameValue(actual: unknown, expected: unknown): boolean {
+function sameValue(actual: FieldValue, expected: JsonValue | undefined): boolean {
   const a = comparable(actual);
   if (Array.isArray(expected) || isPlainObject(expected)) {
     return deepEqual(a, expected);
@@ -333,7 +343,7 @@ function sameValue(actual: unknown, expected: unknown): boolean {
 }
 
 /** Read a frontmatter field: a literal key first, then a dotted path into nested data. */
-export function readField(data: Record<string, unknown>, key: string): unknown {
+export function readField(data: FieldData, key: string): FieldValue {
   // Own properties only: `constructor` and `toString` are not frontmatter, whatever `in` says.
   if (Object.hasOwn(data, key)) {
     return data[key];
@@ -341,31 +351,33 @@ export function readField(data: Record<string, unknown>, key: string): unknown {
   if (!key.includes(".")) {
     return undefined;
   }
-  let current: unknown = data;
-  for (const part of key.split(".")) {
-    if (!isPlainObject(current) || !Object.hasOwn(current, part)) {
-      return undefined;
-    }
-    current = current[part];
+  return readPath(data, key.split("."));
+}
+
+/** Follow a dotted path's parts through nested objects, own properties only like {@link readField}. */
+function readPath(holder: FieldValue | FieldData, [part, ...rest]: readonly string[]): FieldValue {
+  if (part === undefined || !isPlainObject(holder) || !Object.hasOwn(holder, part)) {
+    return undefined;
   }
-  return current;
+  const value = holder[part];
+  return rest.length === 0 ? value : readPath(value, rest);
 }
 
 /** Order two comparable values; undefined when they are not the same kind of thing. */
-function order(actual: unknown, operand: string | number): number | undefined {
+function order(actual: FieldValue, operand: string | number): number | undefined {
   const a = comparable(actual);
-  if (typeof a === "number" && typeof operand === "number") {
+  if (isNumber(a) && isNumber(operand)) {
     return a - operand;
   }
-  if (typeof a === "string" && typeof operand === "string") {
+  if (isString(a) && isString(operand)) {
     return a < operand ? -1 : a > operand ? 1 : 0;
   }
   return undefined;
 }
 
-type FieldTest = (actual: unknown) => boolean;
+type FieldTest = (actual: FieldValue) => boolean;
 
-function operatorTest(where: string, op: string, operand: unknown): FieldTest {
+function operatorTest(where: string, op: string, operand: JsonValue | undefined): FieldTest {
   switch (op) {
     case "$eq": {
       return (actual) => sameValue(actual, operand);
@@ -382,7 +394,7 @@ function operatorTest(where: string, op: string, operand: unknown): FieldTest {
       return op === "$in" ? hit : (actual) => !hit(actual);
     }
     case "$exists": {
-      if (typeof operand !== "boolean") {
+      if (!isBoolean(operand)) {
         throw new TypeError(
           `${where}.$exists: expected true or false, got ${JSON.stringify(operand)}`,
         );
@@ -391,7 +403,7 @@ function operatorTest(where: string, op: string, operand: unknown): FieldTest {
       return (actual) => (actual !== undefined && actual !== null) === operand;
     }
     default: {
-      if (typeof operand !== "string" && typeof operand !== "number") {
+      if (!isString(operand) && !isNumber(operand)) {
         throw new TypeError(
           `${where}.${op}: expected a string or number, got ${JSON.stringify(operand)}`,
         );
@@ -407,7 +419,7 @@ function operatorTest(where: string, op: string, operand: unknown): FieldTest {
 }
 
 /** A condition object is an operator set when every key is `$`-prefixed. */
-function operatorKeys(condition: Record<string, unknown>): string[] | null {
+function operatorKeys(condition: FieldData): string[] | null {
   const keys = Object.keys(condition);
   const dollars = keys.filter((key) => key.startsWith("$"));
   if (dollars.length === 0) {
@@ -416,7 +428,7 @@ function operatorKeys(condition: Record<string, unknown>): string[] | null {
   return dollars.length === keys.length ? keys : [];
 }
 
-function compileCondition(key: string, condition: unknown): FieldTest {
+function compileCondition(key: string, condition: JsonValue): FieldTest {
   const where = `where.${key}`;
   if (!isPlainObject(condition)) {
     return (actual) => sameValue(actual, condition);
@@ -446,10 +458,10 @@ function compileCondition(key: string, condition: unknown): FieldTest {
  * `$exists`, `$gt`, `$gte`, `$lt`, `$lte`; several in one object combine with AND too). There is no
  * OR and no evaluation of text: a project that needs "either" splits it into two content types.
  *
- * @param {unknown} where
+ * @param {JsonValue} [where]
  * @returns {WherePredicate}
  */
-export function compileWhere(where?: unknown): WherePredicate {
+export function compileWhere(where?: JsonValue): WherePredicate {
   if (where === undefined) {
     return Object.assign(() => true, { why: nothing });
   }
@@ -465,10 +477,9 @@ export function compileWhere(where?: unknown): WherePredicate {
     return { key, test: compileCondition(key, condition) };
   });
   return Object.assign(
-    (data: Record<string, unknown>) => tests.every(({ key, test }) => test(readField(data, key))),
+    (data: FieldData) => tests.every(({ key, test }) => test(readField(data, key))),
     {
-      why: (data: Record<string, unknown>) =>
-        tests.find(({ key, test }) => !test(readField(data, key)))?.key,
+      why: (data: FieldData) => tests.find(({ key, test }) => !test(readField(data, key)))?.key,
     },
   );
 }

package/src/content.ts

@@ -6,35 +6,64 @@
  * queryContentType, findEntry) used by both the classes and the server endpoint.
  */
 
+import { isNonNullObject, isRef, isString } from "@jxsuite/schema/guards";
 import { localeUrlPrefix, resolveI18n } from "@jxsuite/schema/locale";
-import type { ProjectConfig } from "@jxsuite/schema/types";
+import type {
+  ContentFieldValue,
+  JsonObject,
+  JsonValue,
+  ProjectConfig,
+} from "@jxsuite/schema/types";
+import { entriesOf } from "./content-data.ts";
+import type { ContentSectionData } from "./content-data.ts";
 import { parseComparable } from "./dates.ts";
 import type { ContentLoaderEntry } from "./types.ts";
 
+/** One filter rule, as `ContentCollection.class.json` declares an item of its `filter` parameter. */
+export interface FilterRule {
+  field: string;
+  op: string;
+  value?: ContentFieldValue;
+}
+
+/** One sort key, as `ContentCollection.class.json` declares an item of its `sort` parameter. */
+export interface SortRule {
+  field: string;
+  order?: string;
+}
+
+/** What {@link queryContentType} narrows a content type by. */
+export interface ContentQuery {
+  /** Explicit rules, or the `{ field: value }` shorthand that means `==` on every key. */
+  filter?: FilterRule[] | JsonObject;
+  sort?: SortRule | SortRule[];
+  limit?: number;
+}
+
+/**
+ * The loaded project the runtime hands a content class: the `content` section (the
+ * Content.projectData result) under its section key, and the project config.
+ */
+interface ContentProjectContext {
+  content?: ContentSectionData;
+  /** The project config, for the i18n routing rules a locale prefix comes from. */
+  config?: ProjectConfig | null;
+}
+
 interface CollectionConfig {
   contentType?: string;
-  filter?: unknown;
-  sort?: unknown;
-  limit?: number;
-  _project?: {
-    /** The loaded `content` section (Content.projectData result) under its section key. */
-    content?: Map<string, ContentLoaderEntry[]>;
-    [k: string]: unknown;
-  };
-  [k: string]: unknown;
+  filter?: FilterRule[] | JsonObject | null;
+  sort?: SortRule | SortRule[] | null;
+  limit?: number | null;
+  _project?: ContentProjectContext;
 }
 
 interface EntryConfig {
   contentType?: string;
-  id?: unknown;
+  /** An entry id, or a `{ $ref: "#/$params/<name>" }` binding to one of the route's path params. */
+  id?: JsonValue;
   field?: string;
-  _project?: {
-    /** The loaded `content` section (Content.projectData result) under its section key. */
-    content?: Map<string, ContentLoaderEntry[]>;
-    /** The project config, for the i18n routing rules a locale prefix comes from. */
-    config?: ProjectConfig | null;
-    [k: string]: unknown;
-  };
+  _project?: ContentProjectContext;
   _document?: {
     route?: {
       _pathParams?: Record<string, string>;
@@ -43,24 +72,27 @@ interface EntryConfig {
       /** The language this route serves, when the project declares any (§13.4). */
       locale?: string | null;
     };
-    [k: string]: unknown;
   };
-  [k: string]: unknown;
 }
 
 // ─── Query Functions ────────────────────────────────────────────────────────
 
+/** `Array.prototype.includes`, with a rule that names no value looking for `undefined`. */
+function includesValue(
+  items: readonly (ContentFieldValue | undefined)[],
+  value: ContentFieldValue | undefined,
+): boolean {
+  return items.includes(value);
+}
+
 /**
  * Evaluate a single filter rule against an entry.
  *
- * @param {{ field: string; op: string; value?: unknown }} rule
+ * @param {FilterRule} rule
  * @param {ContentLoaderEntry} entry
  * @returns {boolean}
  */
-export function evaluateFilterRule(
-  rule: { field: string; op: string; value?: unknown },
-  entry: ContentLoaderEntry,
-) {
+export function evaluateFilterRule(rule: FilterRule, entry: ContentLoaderEntry) {
   const actual = rule.field === "id" ? entry.id : entry.data[rule.field];
   switch (rule.op) {
     case "==": {
@@ -77,15 +109,15 @@ export function evaluateFilterRule(
     }
     case "contains": {
       if (Array.isArray(actual)) {
-        return actual.includes(rule.value);
+        return includesValue(actual, rule.value);
       }
-      return typeof actual === "string" && actual.includes(String(rule.value ?? ""));
+      return isString(actual) && actual.includes(String(rule.value ?? ""));
     }
     case "not contains": {
       if (Array.isArray(actual)) {
-        return !actual.includes(rule.value);
+        return !includesValue(actual, rule.value);
       }
-      return typeof actual === "string" && !actual.includes(String(rule.value ?? ""));
+      return isString(actual) && !actual.includes(String(rule.value ?? ""));
     }
     /*
      * `Number()` on both sides made every date comparison false, since NaN compares false against
@@ -118,29 +150,18 @@ export function evaluateFilterRule(
  * Query a loaded content type with filter, sort, and limit.
  *
  * @param {ContentLoaderEntry[]} entries - Full content type entries
- * @param {{
- *   filter?: Record<string, unknown> | Array<{ field: string; op: string; value?: unknown }>;
- *   sort?: { field: string; order?: string } | Array<{ field: string; order?: string }>;
- *   limit?: number;
- * }} [query]
+ * @param {ContentQuery} [query]
  * @returns {ContentLoaderEntry[]} Filtered, sorted, limited entries
  */
-export function queryContentType(
-  entries: ContentLoaderEntry[],
-  query: {
-    filter?: Record<string, unknown> | { field: string; op: string; value?: unknown }[];
-    sort?: { field: string; order?: string } | { field: string; order?: string }[];
-    limit?: number;
-  } = {},
-) {
+export function queryContentType(entries: ContentLoaderEntry[], query: ContentQuery = {}) {
   let result = [...entries];
 
   // Filter
   if (query.filter) {
-    let rules: { field: string; op: string; value?: unknown }[];
+    let rules: FilterRule[];
     if (Array.isArray(query.filter)) {
       rules = query.filter;
-    } else if (typeof query.filter === "object") {
+    } else if (isNonNullObject(query.filter)) {
       rules = Object.entries(query.filter).map(([field, value]) => ({
         field,
         op: "==",
@@ -157,8 +178,8 @@ export function queryContentType(
     const sortRules = Array.isArray(query.sort) ? query.sort : [query.sort];
     result.sort((a, b) => {
       for (const { field, order = "asc" } of sortRules) {
-        const aVal = field === "id" ? a.id : ((a.data[field] ?? "") as string | number);
-        const bVal = field === "id" ? b.id : ((b.data[field] ?? "") as string | number);
+        const aVal = field === "id" ? a.id : (a.data[field] ?? "");
+        const bVal = field === "id" ? b.id : (b.data[field] ?? "");
         if (aVal < bVal) {
           return order === "asc" ? -1 : 1;
         }
@@ -192,33 +213,46 @@ export function findEntry(entries: ContentLoaderEntry[], id: string) {
 // ─── Class Implementations ──────────────────────────────────────────────────
 
 export class ContentCollection {
+  /**
+   * Reads `_project.content` through `load` and `materialize`, so a host that loads sections on
+   * demand may hand it the section as it is, rather than completing it first (specs/extensions.md
+   * §8). A class without this flag gets the whole section, as it always has.
+   */
+  static projectOnDemand = true;
+
   config: CollectionConfig;
   /** @param {CollectionConfig} config */
   constructor(config: CollectionConfig) {
     this.config = config;
   }
 
-  resolve() {
+  async resolve() {
     const { contentType, filter, sort, limit, _project } = this.config;
-    const entries = _project?.content?.get(contentType ?? "");
+    const entries = await entriesOf(_project?.content, contentType ?? "");
     if (!entries) {
       return [];
     }
-    return queryContentType(entries, {
-      ...(filter != null && {
-        filter: filter as
-          | Record<string, unknown>
-          | { field: string; op: string; value?: unknown }[],
-      }),
-      ...(sort != null && {
-        sort: sort as { field: string; order?: string } | { field: string; order?: string }[],
-      }),
-      ...(limit != null && { limit }),
-    });
+    const query: ContentQuery = {};
+    if (filter != null) {
+      query.filter = filter;
+    }
+    if (sort != null) {
+      query.sort = sort;
+    }
+    if (limit != null) {
+      query.limit = limit;
+    }
+    const result = queryContentType(entries, query);
+    // Only what is returned needs a body; the query above read frontmatter alone.
+    await _project?.content?.materialize?.(result);
+    return result;
   }
 }
 
 export class ContentEntry {
+  /** As {@link ContentCollection.projectOnDemand}: reads the section through `load`. */
+  static projectOnDemand = true;
+
   config: EntryConfig;
   /** @param {EntryConfig} config */
   constructor(config: EntryConfig) {
@@ -232,7 +266,7 @@ export class ContentEntry {
   #pageRoute(): string | undefined {
     const { _project, _document } = this.config;
     let path = _document?.route?.urlPattern;
-    if (typeof path !== "string") {
+    if (!isString(path)) {
       return undefined;
     }
     const { i18n } = resolveI18n(_project?.config ?? {});
@@ -243,9 +277,16 @@ export class ContentEntry {
     return path.replace(/\/+$/, "") || "/";
   }
 
-  resolve() {
+  async resolve() {
+    const found = await this.#find();
+    await this.config._project?.content?.materialize?.([found]);
+    return found;
+  }
+
+  /** The entry this one names, found by frontmatter, route and id alone (its body may be pending). */
+  async #find(): Promise<ContentLoaderEntry | null> {
     const { contentType, id, field, _project, _document } = this.config;
-    const entries = _project?.content?.get(contentType ?? "");
+    const entries = await entriesOf(_project?.content, contentType ?? "");
     if (!entries) {
       return null;
     }
@@ -263,7 +304,7 @@ export class ContentEntry {
     const wanted = _document?.route?.locale;
     const localized = entries.some((e: ContentLoaderEntry) => e._meta?.locale !== undefined);
     const scoped =
-      localized && typeof wanted === "string"
+      localized && isString(wanted)
         ? entries.filter((e: ContentLoaderEntry) => e._meta?.locale === wanted)
         : entries;
 
@@ -280,12 +321,8 @@ export class ContentEntry {
     }
 
     let resolvedId = id;
-    if (
-      resolvedId &&
-      typeof resolvedId === "object" &&
-      (resolvedId as { $ref?: string }).$ref?.startsWith("#/$params/")
-    ) {
-      const paramName = (resolvedId as { $ref: string }).$ref.replace("#/$params/", "");
+    if (isRef(resolvedId) && resolvedId.$ref.startsWith("#/$params/")) {
+      const paramName = resolvedId.$ref.replace("#/$params/", "");
       resolvedId = _document?.route?._pathParams?.[paramName];
     }
     if (!resolvedId) {
@@ -295,6 +332,7 @@ export class ContentEntry {
     if (field && field !== "id") {
       return scoped.find((e: ContentLoaderEntry) => e.data[field] === resolvedId) ?? null;
     }
-    return findEntry(scoped, resolvedId as string);
+    // Entry ids are strings, so an id of any other type matches no entry.
+    return isString(resolvedId) ? findEntry(scoped, resolvedId) : null;
   }
 }

package/src/csv.ts

@@ -1,10 +1,10 @@
 /**
  * Csv — CSV content format for Jx
  *
- * RFC 4180-style CSV parsing with schema-driven type coercion, packaged as a Jx
- * format-extension class. `parse` and `rewrite` are pure and browser-safe; `discover`, `load`, and
- * instance `resolve` touch the filesystem (or fetch remote URLs) and dynamically
- * import node modules so the module itself stays importable in the browser.
+ * RFC 4180-style CSV parsing with schema-driven type coercion, packaged as a Jx format-extension
+ * class. `parse` and `rewrite` are pure and browser-safe; `discover`, `load`, and instance
+ * `resolve` touch the filesystem (or fetch remote URLs) and dynamically import node modules so the
+ * module itself stays importable in the browser.
  *
  * There is no `serialize`, and there will not be one: a collection is a data source entries are
  * loaded FROM, and re-emitting one would mean choosing a quoting style, a line ending and a column
@@ -15,6 +15,7 @@
  * @license MIT
  */
 
+import type { ValueEdit } from "@jxsuite/schema/format-registry";
 import type { ContentTypeSchema } from "@jxsuite/schema/types";
 import type { ContentLoaderEntry } from "./types.ts";
 
@@ -97,13 +98,11 @@ export function parseCSV(csv: string): Record<string, string>[] {
 
 // ─── Cell-level rewriting ────────────────────────────────────────────────────
 
-/** One authored value to replace, wherever a data cell holds exactly it. */
-export interface CsvEdit {
-  /** The cell value as `parse` produced it — unquoted and trimmed. */
-  from: string;
-  /** What to write in its place. */
-  to: string;
-}
+/**
+ * One authored value to replace, wherever a data cell holds exactly it. `from` is the cell value as
+ * `parse` produced it: unquoted and trimmed. Kept under its own name for importers of this module.
+ */
+export type { ValueEdit as CsvEdit } from "@jxsuite/schema/format-registry";
 
 /** One field of a CSV source: where its bytes are, and what {@link parseCSV} made of it. */
 interface CsvField {
@@ -226,7 +225,7 @@ function encodeField(raw: string, value: string): string {
  * @param edits — authored values to replace
  * @returns The source with exactly those cells rewritten
  */
-export function rewriteCSV(source: string, edits: readonly CsvEdit[]): string {
+export function rewriteCSV(source: string, edits: readonly ValueEdit[]): string {
   const replacements = new Map<string, string>();
   for (const edit of edits) {
     if (edit.from !== edit.to) {
@@ -273,7 +272,7 @@ export function coerceCSVRows(
   idField?: string,
 ): ContentLoaderEntry[] {
   return rows.map((row, i) => {
-    const data: Record<string, unknown> = { ...row };
+    const data: ContentLoaderEntry["data"] = { ...row };
     if (schema?.properties) {
       for (const [key, def] of Object.entries(schema.properties)) {
         if (!(key in data)) {
@@ -302,6 +301,11 @@ export function coerceCSVRows(
         }
       }
     }
+    /*
+     * SAFETY: each candidate is a cell copied from `row`, so a string, unless the schema typed that
+     * column as number, boolean or array and the loop above coerced it. An id column typed that way
+     * would put its coerced value here as the entry id (see the coercion rules in the doc comment).
+     */
     const id =
       (idField ? (data[idField] as string | undefined) : undefined) ??
       (data.id as string | undefined) ??
@@ -342,7 +346,7 @@ export class Csv {
    * changed without inventing an opinion about quoting, line endings or column order. See
    * {@link rewriteCSV}.
    */
-  static rewrite(source: string, edits: readonly CsvEdit[] = []): string {
+  static rewrite(source: string, edits: readonly ValueEdit[] = []): string {
     return rewriteCSV(source, edits);
   }