@script-it/json-views-core 0.1.0-beta.1

package/dist/document-session.d.ts

@@ -0,0 +1,52 @@
+export interface JsonDocumentSource {
+    content: string;
+    revision?: string;
+}
+export interface JsonDocumentSnapshot extends JsonDocumentSource {
+    documentId: string;
+    acknowledgedContent: string;
+    dirty: boolean;
+    saving: boolean;
+    error?: Error;
+}
+export interface JsonDocumentCommitContext {
+    documentId: string;
+    baseContent: string;
+    baseRevision?: string;
+}
+export type JsonDocumentSave = (content: string, context: JsonDocumentCommitContext) => Promise<void | JsonDocumentSource>;
+export type DocumentContentValidator = (content: string) => void;
+export declare class JsonDocumentConflictError extends Error {
+    constructor();
+}
+/** One document's draft, acknowledged source and in-flight persistence operation. */
+export declare class JsonDocumentSession {
+    private snapshot;
+    private observed;
+    private readonly listeners;
+    private readonly acknowledgements;
+    private generation;
+    private pending;
+    private conflicted;
+    private readonly validateContent;
+    constructor(source: JsonDocumentSource & {
+        id: string;
+        validateContent?: DocumentContentValidator;
+    });
+    readonly getSnapshot: () => JsonDocumentSnapshot;
+    readonly subscribe: (listener: () => void) => (() => void);
+    private publish;
+    private remember;
+    private isAcknowledgedEcho;
+    /** Receive a persisted host snapshot. Authoritative reloads can intentionally restore
+     * a historical identity; opaque revisions alone cannot distinguish that from an echo.
+     */
+    receive(source: JsonDocumentSource, options?: {
+        authoritative?: boolean;
+    }): void;
+    /** Source is stored exactly; format-aware clients can report validity separately. */
+    edit(content: string): void;
+    /** Discard the current draft and restore the latest acknowledged host source. */
+    reset(): void;
+    commit(buildNext: (source: string) => string, save: JsonDocumentSave): Promise<void>;
+}

package/dist/document-session.js

@@ -0,0 +1,164 @@
+export class JsonDocumentConflictError extends Error {
+    constructor() {
+        super('The document changed outside this editor. Your draft is preserved; reload the saved document before retrying.');
+        this.name = 'JsonDocumentConflictError';
+    }
+}
+/** One document's draft, acknowledged source and in-flight persistence operation. */
+export class JsonDocumentSession {
+    snapshot;
+    observed;
+    listeners = new Set();
+    acknowledgements = [];
+    generation = 0;
+    pending;
+    conflicted = false;
+    validateContent;
+    constructor(source) {
+        this.validateContent = source.validateContent ?? (() => undefined);
+        this.observed = { content: source.content, revision: source.revision };
+        this.snapshot = {
+            documentId: source.id,
+            content: source.content,
+            acknowledgedContent: source.content,
+            revision: source.revision,
+            dirty: false,
+            saving: false,
+        };
+        this.remember(source);
+    }
+    getSnapshot = () => this.snapshot;
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    };
+    publish(next) {
+        this.snapshot = { ...this.snapshot, ...next };
+        this.snapshot.dirty = this.snapshot.content !== this.snapshot.acknowledgedContent;
+        this.listeners.forEach((listener) => listener());
+    }
+    remember(source) {
+        const existing = this.acknowledgements.findIndex((entry) => (entry.content === source.content && entry.revision === source.revision));
+        if (existing >= 0)
+            this.acknowledgements.splice(existing, 1);
+        this.acknowledgements.push({ content: source.content, revision: source.revision });
+        // Retain recent accepted identities to recognize delayed host echoes.
+        if (this.acknowledgements.length > 32)
+            this.acknowledgements.shift();
+    }
+    isAcknowledgedEcho(source) {
+        return this.acknowledgements.some((entry) => entry.content === source.content
+            && (source.revision === undefined || entry.revision === source.revision));
+    }
+    /** Receive a persisted host snapshot. Authoritative reloads can intentionally restore
+     * a historical identity; opaque revisions alone cannot distinguish that from an echo.
+     */
+    receive(source, options = {}) {
+        if (!options.authoritative && source.content === this.observed.content && source.revision === this.observed.revision)
+            return;
+        if (!options.authoritative && this.isAcknowledgedEcho(source)) {
+            this.observed = { ...source };
+            return;
+        }
+        if (source.content === this.pending?.content) {
+            // Matching in-flight observations remain provisional until persistence resolves.
+            this.pending.observed = {
+                content: source.content,
+                revision: source.revision ?? (this.pending.observed?.content === source.content ? this.pending.observed.revision : undefined),
+            };
+            return;
+        }
+        this.observed = { ...source };
+        if (source.content === this.snapshot.acknowledgedContent && !this.pending) {
+            if (source.revision !== undefined)
+                this.publish({ revision: source.revision });
+            this.remember({ content: source.content, revision: this.snapshot.revision });
+            return;
+        }
+        const preserveDraft = (this.snapshot.dirty && source.content !== this.snapshot.content) || this.pending !== undefined;
+        this.conflicted = preserveDraft;
+        if (this.pending) {
+            this.pending.conflicted = true;
+            this.pending.observed = { ...source };
+        }
+        this.remember(source);
+        this.publish({
+            acknowledgedContent: source.content,
+            revision: source.revision,
+            content: preserveDraft ? this.snapshot.content : source.content,
+            error: preserveDraft ? new JsonDocumentConflictError() : undefined,
+        });
+    }
+    /** Source is stored exactly; format-aware clients can report validity separately. */
+    edit(content) {
+        if (content === this.snapshot.content)
+            return;
+        this.generation += 1;
+        this.publish({ content, error: this.conflicted ? this.snapshot.error : undefined });
+    }
+    /** Discard the current draft and restore the latest acknowledged host source. */
+    reset() {
+        if (this.pending)
+            throw new Error('Wait for the current save before reloading the document');
+        this.generation += 1;
+        this.conflicted = false;
+        this.publish({ content: this.snapshot.acknowledgedContent, error: undefined });
+    }
+    async commit(buildNext, save) {
+        if (this.pending)
+            throw new Error('A save is already in progress');
+        if (this.conflicted)
+            throw new JsonDocumentConflictError();
+        let content;
+        try {
+            content = buildNext(this.snapshot.content);
+            this.validateContent(content);
+        }
+        catch (error) {
+            this.publish({ error: error instanceof Error ? error : new Error(String(error)) });
+            throw error;
+        }
+        if (content === this.snapshot.acknowledgedContent) {
+            this.edit(content);
+            this.publish({ error: undefined });
+            return;
+        }
+        const context = {
+            documentId: this.snapshot.documentId,
+            baseContent: this.snapshot.acknowledgedContent,
+            baseRevision: this.snapshot.revision,
+        };
+        if (content !== this.snapshot.content)
+            this.generation += 1;
+        const pending = { content, generation: this.generation, conflicted: false };
+        this.pending = pending;
+        this.publish({ content, saving: true, error: undefined });
+        try {
+            const result = await save(content, context);
+            const response = result ?? { content, revision: this.snapshot.revision };
+            if (pending.conflicted && pending.observed?.content !== response.content)
+                throw new JsonDocumentConflictError();
+            // A matching host observation during the request is newer evidence than its response.
+            // Revisions are opaque: only an identical accepted content can inherit that revision.
+            const accepted = pending.observed?.content === response.content && pending.observed.revision !== undefined
+                ? { content: response.content, revision: pending.observed.revision } : response;
+            this.remember(response);
+            this.remember(accepted);
+            this.conflicted = false;
+            this.publish({
+                error: undefined,
+                acknowledgedContent: accepted.content,
+                revision: accepted.revision,
+                content: this.generation === pending.generation ? accepted.content : this.snapshot.content,
+            });
+        }
+        catch (error) {
+            this.publish({ error: error instanceof Error ? error : new Error(String(error)) });
+            throw error;
+        }
+        finally {
+            this.pending = undefined;
+            this.publish({ saving: false });
+        }
+    }
+}

package/dist/formats/conversion.d.ts

@@ -0,0 +1,17 @@
+import type { StructuredDocumentFormat } from './document-format.js';
+export interface ConvertToJsonViewsDocumentOptions {
+    root: unknown;
+    metadata?: unknown;
+    sourceFormat: StructuredDocumentFormat;
+    /** Authoritative JSON source when available; preserves exact data tokens. */
+    source?: string;
+}
+export declare function rebaseJsonViewsRootPath(path: string): string;
+/** Rebase only specification-defined path positions. Filter values and extension
+ * payloads are user data, even when they contain properties named path/title.
+ */
+export declare function rebaseJsonViewsMetadata(metadata: unknown): Record<string, unknown>;
+/** Converts an array-root JSON or CSV-normalized root into the canonical envelope.
+ * Pass source for imported JSON; a parsed root alone cannot retain source spelling.
+ */
+export declare function convertToJsonViewsDocument({ root, metadata, sourceFormat, source }: ConvertToJsonViewsDocumentOptions): string;

package/dist/formats/conversion.js

@@ -0,0 +1,75 @@
+import { stringifyJsonValue, upsertJsonObjectPropertyInSource } from '../json-source-patcher.js';
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function versionOneMetadata(value) {
+    if (value === undefined)
+        return { version: 1, schema: {}, views: [] };
+    if (!isRecord(value))
+        throw new TypeError('Annotations must be an object');
+    if (value.version !== undefined && value.version !== 1)
+        throw new TypeError('Only version 1 annotations can be converted');
+    return { ...value, version: 1 };
+}
+export function rebaseJsonViewsRootPath(path) {
+    if (path === '$')
+        return '$.data';
+    return path.startsWith('$') ? `$.data${path.slice(1)}` : path;
+}
+function rebaseField(value) {
+    if (!isRecord(value))
+        return value;
+    return { ...value, ...(typeof value.path === 'string' ? { path: rebaseJsonViewsRootPath(value.path) } : {}) };
+}
+/** Rebase only specification-defined path positions. Filter values and extension
+ * payloads are user data, even when they contain properties named path/title.
+ */
+export function rebaseJsonViewsMetadata(metadata) {
+    const source = versionOneMetadata(metadata);
+    const views = Array.isArray(source.views) ? source.views.map((value) => {
+        if (!isRecord(value))
+            return value;
+        const view = { ...value };
+        for (const key of ['path', 'groupBy', 'orderPath']) {
+            if (typeof view[key] === 'string')
+                view[key] = rebaseJsonViewsRootPath(view[key]);
+        }
+        for (const key of ['columns', 'sort']) {
+            if (Array.isArray(view[key]))
+                view[key] = view[key].map(rebaseField);
+        }
+        if (isRecord(view.filter) && Array.isArray(view.filter.rules)) {
+            view.filter = { ...view.filter, rules: view.filter.rules.map(rebaseField) };
+        }
+        return view;
+    }) : source.views ?? [];
+    const schema = isRecord(source.schema)
+        ? Object.fromEntries(Object.entries(source.schema).map(([path, descriptor]) => [rebaseJsonViewsRootPath(path), descriptor]))
+        : source.schema ?? {};
+    return { ...source, schema, views };
+}
+/** Converts an array-root JSON or CSV-normalized root into the canonical envelope.
+ * Pass source for imported JSON; a parsed root alone cannot retain source spelling.
+ */
+export function convertToJsonViewsDocument({ root, metadata, sourceFormat, source }) {
+    const authoritative = source === undefined ? root : JSON.parse(source);
+    if (sourceFormat === 'json-object') {
+        if (!isRecord(authoritative))
+            throw new TypeError('Object-root conversion requires a JSON object');
+        const annotations = versionOneMetadata(metadata);
+        if (source !== undefined)
+            return upsertJsonObjectPropertyInSource(source, [], '$jsonviews', annotations);
+        return `${stringifyJsonValue({ ...authoritative, $jsonviews: annotations }, 2)}\n`;
+    }
+    if (!Array.isArray(authoritative))
+        throw new TypeError('CSV and array-root conversion requires an array root');
+    if (sourceFormat === 'json-array' && source !== undefined) {
+        const newline = source.includes('\r\n') ? '\r\n' : '\n';
+        const indent = (value) => value.replace(/\r?\n/g, `${newline}  `);
+        const metadataSource = indent(stringifyJsonValue(rebaseJsonViewsMetadata(metadata), 2));
+        const dataSource = indent(source.trim());
+        const trailing = /\r?\n$/.test(source) ? newline : '';
+        return `{${newline}  "$jsonviews": ${metadataSource},${newline}  "data": ${dataSource}${newline}}${trailing}`;
+    }
+    return `${stringifyJsonValue({ $jsonviews: rebaseJsonViewsMetadata(metadata), data: authoritative }, 2)}\n`;
+}

package/dist/formats/csv-format.d.ts

@@ -0,0 +1,31 @@
+import type { DocumentDiagnostic, StructuredDocumentAdapter, ValueReplacement } from './document-format.js';
+export interface CsvCellState {
+    start: number;
+    end: number;
+    raw: string;
+    value: string;
+    quoted: boolean;
+}
+export interface CsvRecordState {
+    start: number;
+    end: number;
+    separatorStart: number;
+    separatorEnd: number;
+    cells: CsvCellState[];
+}
+export interface CsvDocumentState {
+    headers: string[];
+    records: CsvRecordState[];
+    lineEnding: '\n' | '\r\n';
+    bom: boolean;
+    finalNewline: boolean;
+    editable: boolean;
+}
+export declare function inspectCsvSource(source: string): {
+    root: Array<Record<string, unknown>>;
+    state: CsvDocumentState;
+    diagnostics: DocumentDiagnostic[];
+};
+export declare function validateCsvSource(source: string): void;
+export declare const csvFormat: StructuredDocumentAdapter<CsvDocumentState>;
+export type { ValueReplacement };

package/dist/formats/csv-format.js

@@ -0,0 +1,269 @@
+import { describeValuePath } from '../json-path.js';
+import { sourceDiagnosticHelp } from '../diagnostics.js';
+function parseCsv(source) {
+    const diagnostics = [];
+    const records = [];
+    const bom = source.charCodeAt(0) === 0xfeff;
+    let index = bom ? 1 : 0;
+    let firstLineEnding;
+    let fatal;
+    while (index < source.length) {
+        const recordStart = index;
+        const cells = [];
+        let recordEnd = index;
+        let separatorStart = index;
+        let separatorEnd = index;
+        let finished = false;
+        while (!finished) {
+            const start = index;
+            let value = '';
+            let quoted = false;
+            if (source[index] === '"') {
+                quoted = true;
+                index += 1;
+                let closed = false;
+                while (index < source.length) {
+                    if (source[index] !== '"') {
+                        value += source[index++];
+                        continue;
+                    }
+                    if (source[index + 1] === '"') {
+                        value += '"';
+                        index += 2;
+                        continue;
+                    }
+                    index += 1;
+                    closed = true;
+                    break;
+                }
+                if (!closed) {
+                    fatal = new SyntaxError('Unterminated quoted CSV cell');
+                    diagnostics.push({ code: 'unterminated-quote', message: fatal.message, severity: 'error', start, end: index });
+                }
+                if (closed && index < source.length && source[index] !== ',' && source[index] !== '\n' && source[index] !== '\r') {
+                    fatal = new SyntaxError('Unexpected content after a quoted CSV cell');
+                    diagnostics.push({ code: 'invalid-quoted-cell', message: fatal.message, severity: 'error', start, end: index + 1 });
+                    while (index < source.length && source[index] !== ',' && source[index] !== '\n' && source[index] !== '\r')
+                        index += 1;
+                }
+            }
+            else {
+                while (index < source.length && source[index] !== ',' && source[index] !== '\n' && source[index] !== '\r') {
+                    if (source[index] === '"' && !fatal) {
+                        fatal = new SyntaxError('Quotes inside an unquoted CSV cell are invalid');
+                        diagnostics.push({ code: 'invalid-quote', message: fatal.message, severity: 'error', start: index, end: index + 1 });
+                    }
+                    value += source[index++];
+                }
+            }
+            cells.push({ start, end: index, raw: source.slice(start, index), value, quoted });
+            if (source[index] === ',') {
+                index += 1;
+                if (index === source.length) {
+                    cells.push({ start: index, end: index, raw: '', value: '', quoted: false });
+                    recordEnd = index;
+                    separatorStart = index;
+                    separatorEnd = index;
+                    finished = true;
+                }
+                continue;
+            }
+            recordEnd = index;
+            separatorStart = index;
+            if (source[index] === '\r' && source[index + 1] === '\n') {
+                firstLineEnding ??= '\r\n';
+                index += 2;
+            }
+            else if (source[index] === '\n') {
+                firstLineEnding ??= '\n';
+                index += 1;
+            }
+            else if (source[index] === '\r') {
+                firstLineEnding ??= '\n';
+                diagnostics.push({ code: 'bare-cr', message: 'Bare carriage returns are not a supported CSV line ending', severity: 'warning', start: index, end: index + 1 });
+                index += 1;
+            }
+            separatorEnd = index;
+            finished = true;
+        }
+        records.push({ start: recordStart, end: recordEnd, separatorStart, separatorEnd, cells });
+    }
+    const headerRecord = records[0];
+    const headers = headerRecord?.cells.map((cell) => cell.value) ?? [];
+    if (!headerRecord)
+        diagnostics.push({ code: 'missing-header', message: 'CSV requires a header record', severity: 'error' });
+    const seen = new Set();
+    headers.forEach((header, column) => {
+        const cell = headerRecord.cells[column];
+        if (!header)
+            diagnostics.push({ code: 'missing-header', message: `Column ${column + 1} has an empty header`, severity: 'error', path: [column], start: cell.start, end: cell.end });
+        else if (seen.has(header))
+            diagnostics.push({ code: 'duplicate-header', message: `Header ${JSON.stringify(header)} is duplicated`, severity: 'error', path: [column], start: cell.start, end: cell.end });
+        seen.add(header);
+    });
+    records.slice(1).forEach((record, row) => {
+        if (record.cells.length !== headers.length)
+            diagnostics.push({
+                code: 'irregular-row',
+                message: `Row ${row + 2} has ${record.cells.length} cells; expected ${headers.length}`,
+                severity: 'warning', path: [row], start: record.start, end: record.end,
+            });
+    });
+    const editable = Boolean(headerRecord) && headers.length > 0 && headers.every(Boolean) && new Set(headers).size === headers.length && !fatal;
+    return {
+        state: {
+            headers,
+            records,
+            lineEnding: firstLineEnding ?? '\n',
+            bom,
+            finalNewline: Boolean(records.at(-1) && records.at(-1).separatorEnd > records.at(-1).separatorStart),
+            editable,
+        },
+        diagnostics: diagnostics.map((item) => ({ ...item, help: sourceDiagnosticHelp(item.code) })),
+        ...(fatal ? { fatal } : {}),
+    };
+}
+function safelyRoundTripsNumber(value) {
+    if (!/^-?(?:0|[1-9]\d*)(?:\.\d+)?$/.test(value))
+        return false;
+    const number = Number(value);
+    if (!Number.isFinite(number) || Object.is(number, -0))
+        return false;
+    if (Number.isInteger(number) && !Number.isSafeInteger(number))
+        return false;
+    return String(number) === value;
+}
+function inferredColumns(state) {
+    return state.headers.map((_header, column) => {
+        const values = state.records.slice(1).map((record) => record.cells[column]?.value ?? '').filter((value) => value !== '');
+        if (values.length > 0 && values.every((value) => value === 'true' || value === 'false'))
+            return 'boolean';
+        if (values.length > 0 && values.every(safelyRoundTripsNumber))
+            return 'number';
+        return 'string';
+    });
+}
+function normalizedRoot(state) {
+    const types = inferredColumns(state);
+    return state.records.slice(1).map((record) => Object.fromEntries(record.cells.map((cell, column) => {
+        const original = state.headers[column];
+        let key = original || `$column${column + 1}`;
+        if (state.headers.indexOf(key) !== column)
+            key = `${key} [${column + 1}]`;
+        const value = cell.value === '' ? '' : types[column] === 'number' ? Number(cell.value) : types[column] === 'boolean' ? cell.value === 'true' : cell.value;
+        return [key, value];
+    })));
+}
+function assertEditable(state) {
+    if (!state.editable)
+        throw new TypeError('Repair missing or duplicate CSV headers before structured editing');
+}
+function csvScalar(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    throw new TypeError('CSV cells can contain only strings, finite numbers, or booleans');
+}
+function encodeCell(value, forceQuote = false) {
+    const text = csvScalar(value);
+    const quote = forceQuote || /[",\r\n]/.test(text) || /^\s|\s$/.test(text);
+    return quote ? `"${text.replace(/"/g, '""')}"` : text;
+}
+function cellForPath(state, path) {
+    assertEditable(state);
+    if (path.length !== 2 || typeof path[0] !== 'number' || !Number.isSafeInteger(path[0]) || path[0] < 0 || typeof path[1] !== 'string') {
+        throw new TypeError(`CSV path ${describeValuePath(path)} must identify a row and header`);
+    }
+    const column = state.headers.indexOf(path[1]);
+    const cell = state.records[path[0] + 1]?.cells[column];
+    if (column < 0 || !cell)
+        throw new RangeError(`CSV path ${describeValuePath(path)} does not exist`);
+    return cell;
+}
+function applyEdits(source, edits) {
+    const ordered = edits.sort((left, right) => left.start - right.start || left.end - right.end);
+    for (let index = 1; index < ordered.length; index += 1) {
+        if (ordered[index].start < ordered[index - 1].end || ordered[index].start === ordered[index - 1].start)
+            throw new TypeError('CSV edits overlap');
+    }
+    let cursor = 0;
+    const parts = [];
+    ordered.forEach((edit) => {
+        parts.push(source.slice(cursor, edit.start), edit.text);
+        cursor = edit.end;
+    });
+    parts.push(source.slice(cursor));
+    return parts.join('');
+}
+export function inspectCsvSource(source) {
+    const parsed = parseCsv(source);
+    return { root: normalizedRoot(parsed.state), state: parsed.state, diagnostics: parsed.diagnostics };
+}
+export function validateCsvSource(source) {
+    const parsed = parseCsv(source);
+    if (parsed.fatal)
+        throw parsed.fatal;
+}
+export const csvFormat = {
+    format: 'csv',
+    inspect: inspectCsvSource,
+    validate: validateCsvSource,
+    replace(source, state, path, value) {
+        const cell = cellForPath(state, path);
+        return applyEdits(source, [{ start: cell.start, end: cell.end, text: encodeCell(value, cell.quoted) }]);
+    },
+    replaceMany(source, state, changes) {
+        const edits = changes.map(({ path, value }) => {
+            const cell = cellForPath(state, path);
+            return { start: cell.start, end: cell.end, text: encodeCell(value, cell.quoted) };
+        });
+        return applyEdits(source, edits);
+    },
+    removeMany(source, state, paths) {
+        assertEditable(state);
+        const rows = [...new Set(paths.map((path) => {
+                if (path.length !== 1 || typeof path[0] !== 'number' || !Number.isSafeInteger(path[0]) || path[0] < 0)
+                    throw new TypeError(`CSV path ${describeValuePath(path)} must identify a row`);
+                if (!state.records[path[0] + 1])
+                    throw new RangeError(`CSV row ${path[0]} does not exist`);
+                return path[0];
+            }))].sort((a, b) => a - b);
+        const edits = [];
+        for (let cursor = 0; cursor < rows.length; cursor++) {
+            const first = rows[cursor];
+            let last = first;
+            while (rows[cursor + 1] === last + 1)
+                last = rows[++cursor];
+            const start = state.records[first + 1];
+            const end = state.records[last + 1];
+            edits.push(end.separatorEnd > end.separatorStart
+                ? { start: start.start, end: end.separatorEnd, text: '' }
+                : { start: state.records[first].separatorStart, end: end.end, text: '' });
+        }
+        return applyEdits(source, edits);
+    },
+    append(source, state, path, value) {
+        assertEditable(state);
+        if (path.length !== 0 || value === null || typeof value !== 'object' || Array.isArray(value)) {
+            throw new TypeError('CSV rows must be appended to the document root as objects');
+        }
+        const row = value;
+        if (Object.keys(row).some((key) => !state.headers.includes(key)))
+            throw new TypeError('CSV rows cannot contain properties missing from the header');
+        const encoded = state.headers.map((header) => encodeCell(Object.prototype.hasOwnProperty.call(row, header) ? row[header] : '')).join(',');
+        const separator = state.lineEnding;
+        return state.finalNewline ? `${source}${encoded}${separator}` : `${source}${separator}${encoded}`;
+    },
+    canRepresent(value) {
+        try {
+            csvScalar(value);
+            return { representable: true };
+        }
+        catch {
+            return { representable: false, reason: 'CSV cells cannot represent nested values or null distinctly from an empty cell' };
+        }
+    },
+};

package/dist/formats/document-format.d.ts

@@ -0,0 +1,35 @@
+import type { ValuePath } from '../json-path.js';
+export type StructuredDocumentFormat = 'json-object' | 'json-array' | 'csv';
+export interface DocumentDiagnostic {
+    code: string;
+    message: string;
+    severity: 'warning' | 'error';
+    path?: ValuePath;
+    start?: number;
+    end?: number;
+    help?: import('../annotation-capabilities.js').JsonViewDiagnosticHelp;
+}
+export interface ValueReplacement {
+    path: ValuePath;
+    value: unknown;
+}
+export type FormatCapability = {
+    representable: true;
+} | {
+    representable: false;
+    reason: string;
+};
+export interface StructuredDocumentAdapter<TState> {
+    readonly format: StructuredDocumentFormat;
+    inspect(source: string): {
+        root: unknown;
+        state: TState;
+        diagnostics: DocumentDiagnostic[];
+    };
+    validate(source: string): void;
+    replace(source: string, state: TState, path: ValuePath, value: unknown): string;
+    replaceMany(source: string, state: TState, changes: readonly ValueReplacement[]): string;
+    removeMany(source: string, state: TState, paths: readonly ValuePath[]): string;
+    append(source: string, state: TState, path: ValuePath, value: unknown): string;
+    canRepresent(value: unknown): FormatCapability;
+}

package/dist/formats/document-format.js

@@ -0,0 +1 @@
+export {};

package/dist/formats/json-format.d.ts

@@ -0,0 +1,12 @@
+import type { ValuePath } from '../json-path.js';
+import type { StructuredDocumentAdapter, ValueReplacement } from './document-format.js';
+export interface JsonDocumentState {
+    root: unknown;
+}
+export declare const jsonObjectFormat: StructuredDocumentAdapter<JsonDocumentState>;
+export declare const jsonArrayFormat: StructuredDocumentAdapter<JsonDocumentState>;
+export declare function jsonFormatForSource(source: string): StructuredDocumentAdapter<JsonDocumentState>;
+export declare function jsonFormatForRoot(root: unknown): StructuredDocumentAdapter<JsonDocumentState>;
+/** Pretty-print JSON without changing numeric spelling, duplicate keys, or string contents. */
+export declare function formatJsonSource(source: string): string;
+export type { ValuePath, ValueReplacement };