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

package/dist/formats/json-format.js

@@ -0,0 +1,109 @@
+import { assertJsonDepth } from '../json-limits.js';
+import { appendJsonArrayItemInSource, inspectJsonSource, removeJsonValuesInSource, replaceJsonValueInSource, replaceJsonValuesInSource, stringifyJsonValue, } from '../json-source-patcher.js';
+function jsonCapability(value) {
+    try {
+        stringifyJsonValue(value);
+        return { representable: true };
+    }
+    catch {
+        return { representable: false, reason: 'The value is not losslessly representable as JSON data' };
+    }
+}
+function adapter(format) {
+    return {
+        format,
+        inspect(source) {
+            const inspected = inspectJsonSource(source);
+            const actual = Array.isArray(inspected.value) ? 'json-array' : 'json-object';
+            if (actual !== format)
+                throw new TypeError(`Expected ${format === 'json-array' ? 'an array' : 'a non-array'} JSON root`);
+            const diagnostics = inspected.diagnostics.map((item) => ({
+                code: item.code,
+                message: item.message,
+                severity: 'warning',
+                path: item.sourcePath,
+                start: item.start,
+                end: item.end,
+                help: item.help,
+            }));
+            return { root: inspected.value, state: { root: inspected.value }, diagnostics };
+        },
+        validate(source) { JSON.parse(source); },
+        replace(source, _state, path, value) { return replaceJsonValueInSource(source, path, value); },
+        replaceMany(source, _state, changes) {
+            return replaceJsonValuesInSource(source, changes);
+        },
+        removeMany(source, _state, paths) {
+            return removeJsonValuesInSource(source, paths);
+        },
+        append(source, _state, path, value) { return appendJsonArrayItemInSource(source, path, value); },
+        canRepresent: jsonCapability,
+    };
+}
+export const jsonObjectFormat = adapter('json-object');
+export const jsonArrayFormat = adapter('json-array');
+export function jsonFormatForSource(source) {
+    return Array.isArray(JSON.parse(source)) ? jsonArrayFormat : jsonObjectFormat;
+}
+export function jsonFormatForRoot(root) {
+    return Array.isArray(root) ? jsonArrayFormat : jsonObjectFormat;
+}
+/** Pretty-print JSON without changing numeric spelling, duplicate keys, or string contents. */
+export function formatJsonSource(source) {
+    assertJsonDepth(JSON.parse(source));
+    let formatted = '';
+    let depth = 0;
+    let escaped = false;
+    let inString = false;
+    const expandedContainers = [];
+    const indentation = () => '  '.repeat(depth);
+    for (let index = 0; index < source.length; index += 1) {
+        const character = source[index];
+        if (inString) {
+            formatted += character;
+            if (escaped)
+                escaped = false;
+            else if (character === '\\')
+                escaped = true;
+            else if (character === '"')
+                inString = false;
+            continue;
+        }
+        if (/\s/.test(character))
+            continue;
+        if (character === '"') {
+            inString = true;
+            formatted += character;
+            continue;
+        }
+        if (character === '{' || character === '[') {
+            const closingCharacter = character === '{' ? '}' : ']';
+            let nextIndex = index + 1;
+            while (nextIndex < source.length && /\s/.test(source[nextIndex]))
+                nextIndex += 1;
+            const expanded = source[nextIndex] !== closingCharacter;
+            expandedContainers.push(expanded);
+            formatted += character;
+            if (expanded) {
+                depth += 1;
+                formatted += `\n${indentation()}`;
+            }
+            continue;
+        }
+        if (character === '}' || character === ']') {
+            const expanded = expandedContainers.pop() ?? false;
+            if (expanded) {
+                depth -= 1;
+                formatted += `\n${indentation()}`;
+            }
+            formatted += character;
+            continue;
+        }
+        if (character === ',') {
+            formatted += `,\n${indentation()}`;
+            continue;
+        }
+        formatted += character === ':' ? ': ' : character;
+    }
+    return formatted;
+}

package/dist/html-view-bindings.d.ts

@@ -0,0 +1,4 @@
+import type { ValuePath } from './json-path.js';
+export { MAX_HTML_VIEW_BYTES } from './html-view-limits.js';
+export declare function resolveHtmlViewBinding(root: unknown, expression: string, aliases: Readonly<Record<string, ValuePath>>, scope: ValuePath): import("./metadata.js").ResolvedJsonViewPath;
+export declare function htmlRepeatKeys(items: readonly unknown[], key?: string): string[];

package/dist/html-view-bindings.js

@@ -0,0 +1,32 @@
+import { parseJsonViewPath, resolveJsonViewPath } from './metadata.js';
+export { MAX_HTML_VIEW_BYTES } from './html-view-limits.js';
+export function resolveHtmlViewBinding(root, expression, aliases, scope) {
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)(.*)$/.exec(expression);
+    const prefix = expression.startsWith('$') ? [] : match && Object.prototype.hasOwnProperty.call(aliases, match[1]) ? aliases[match[1]] : undefined;
+    if (!prefix)
+        throw new Error(`Unknown binding: ${expression}`);
+    const parsed = parseJsonViewPath(expression.startsWith('$') ? expression : `$${match[2]}`, { allowWildcard: false });
+    const relative = parsed.segments.map(segment => {
+        if (segment.kind === 'wildcard')
+            throw new Error('Single bindings cannot contain wildcards');
+        return segment.kind === 'property' ? segment.key : segment.index;
+    });
+    const path = [...prefix, ...relative];
+    if (path.includes('$jsonviews') || !scope.every((part, index) => path[index] === part) || path.length < scope.length)
+        throw new Error(`Binding outside the view data scope: ${expression}`);
+    const absolute = parseJsonViewPath('$' + path.map(part => typeof part === 'number' ? `[${part}]` : `['${part.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}']`).join(''));
+    return resolveJsonViewPath(root, absolute);
+}
+export function htmlRepeatKeys(items, key) {
+    if (!key)
+        return items.map((_, i) => `index:${i}`);
+    const keys = items.map(item => {
+        const value = item && typeof item === 'object' && Object.prototype.hasOwnProperty.call(item, key) ? item[key] : undefined;
+        if (typeof value !== 'string' && !(typeof value === 'number' && Number.isFinite(value)))
+            throw new Error(`Repeat key ${key} must be a string or finite number on every item`);
+        return `${typeof value}:${value}`;
+    });
+    if (new Set(keys).size !== keys.length)
+        throw new Error(`Repeat key ${key} must be unique`);
+    return keys;
+}

package/dist/html-view-limits.d.ts

@@ -0,0 +1 @@
+export declare const MAX_HTML_VIEW_BYTES: number;

package/dist/html-view-limits.js

@@ -0,0 +1 @@
+export const MAX_HTML_VIEW_BYTES = 256 * 1024;

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export * from './json-path.js';
+export * from './json-source-patcher.js';
+export * from './date-type.js';
+export * from './inference.js';
+export * from './table-suitability.js';
+export * from './metadata.js';
+export * from './diagnostics.js';
+export * from './schema-validation.js';
+export * from './type-registry.js';
+export * from './view-model.js';
+export * from './document-session.js';
+export * from './formats/document-format.js';
+export * from './formats/json-format.js';
+export * from './formats/csv-format.js';
+export * from './formats/conversion.js';
+export * from './value-comparison.js';
+export * from './json-limits.js';
+export { prefersSource } from './source-default.js';
+export * from './html-view-bindings.js';

package/dist/index.js

@@ -0,0 +1,19 @@
+export * from './json-path.js';
+export * from './json-source-patcher.js';
+export * from './date-type.js';
+export * from './inference.js';
+export * from './table-suitability.js';
+export * from './metadata.js';
+export * from './diagnostics.js';
+export * from './schema-validation.js';
+export * from './type-registry.js';
+export * from './view-model.js';
+export * from './document-session.js';
+export * from './formats/document-format.js';
+export * from './formats/json-format.js';
+export * from './formats/csv-format.js';
+export * from './formats/conversion.js';
+export * from './value-comparison.js';
+export * from './json-limits.js';
+export { prefersSource } from './source-default.js';
+export * from './html-view-bindings.js';

package/dist/inference-fields.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizedKey(key: string): string;
+/** A complete HTML document or a styled HTML fragment needs its own layout. */
+export declare function isHtmlDocument(value: string): boolean;
+/** Recognize common Markdown and supported HTML; keep bare hashtags and identifiers literal. */
+export declare function isMarkdownText(value: string): boolean;

package/dist/inference-fields.js

@@ -0,0 +1,23 @@
+export function normalizedKey(key) {
+    return key.toLocaleLowerCase().replace(/[^a-z0-9]+/g, '');
+}
+/** A complete HTML document or a styled HTML fragment needs its own layout. */
+export function isHtmlDocument(value) {
+    return /<!doctype\s+html\b/i.test(value)
+        || /<html\b[^>]*>[\s\S]*<\/html\s*>/i.test(value)
+        || (/<style\b[^>]*>[\s\S]*<\/style\s*>/i.test(value)
+            && /<(?:body|div|main|section|article|table)\b/i.test(value));
+}
+/** Recognize common Markdown and supported HTML; keep bare hashtags and identifiers literal. */
+export function isMarkdownText(value) {
+    return /(?:^|\n)#{1,6}\s+\S/.test(value)
+        || /(?:^|\n)(?:```|~~~)[^\n]*\n[\s\S]+\n(?:```|~~~)/.test(value)
+        || /(?:\*\*[^*\n]+\*\*|~~[^~\n]+~~|`[^`\n]+`)/.test(value)
+        || /!?\[[^\]\n]*\]\([^\s)]+\)/.test(value)
+        || /(?:^|\n)\s*(?:[-*+]|\d+[.)]|>)\s+\S/.test(value)
+        || /(?:^|[\s(])(?:_[^_\n]+_|\*[^*\n]+\*)(?=$|[\s).,!?:;])/.test(value)
+        || /(?:^|\n)[^\n]+\n(?:={3,}|-{3,})(?:\n|$)/.test(value)
+        || /(?:^|\n)\s*\|?\s*:?-{3,}:?\s*\|/.test(value)
+        || /<(?:br|hr|img)\b[^>]*\/?>/i.test(value)
+        || /<(div|span|svg|pre|code|p|h[1-6]|strong|em|ul|ol|li|table|blockquote|a)\b[^>]*>[\s\S]*<\/\1>/i.test(value);
+}

package/dist/inference.d.ts

@@ -0,0 +1,26 @@
+export interface InferredJsonViewSchemaDescriptor {
+    type: string;
+    title: string;
+    options?: string[];
+    defaultIncludeTime?: boolean;
+}
+export interface InferredJsonViewDefinition {
+    id: string;
+    name: string;
+    path: string;
+    columns?: Array<{
+        label: string;
+        path: string;
+    }>;
+    display?: 'kanban';
+    groupBy?: string;
+}
+export interface InferredJsonViewMetadata {
+    version: 1;
+    schema: Record<string, InferredJsonViewSchemaDescriptor>;
+    views: InferredJsonViewDefinition[];
+}
+/** Uses the metadata title policy. Disable the first-text fallback for record headings. */
+export declare function inferJsonViewRecordTitleKey(rows: readonly Record<string, unknown>[], allowFallback?: boolean): string | undefined;
+/** Predicts useful metadata without mutating the source JSON. */
+export declare function inferJsonViewMetadata(root: unknown): InferredJsonViewMetadata;

package/dist/inference.js

@@ -0,0 +1,304 @@
+import { parseDateValue } from './date-type.js';
+import { isJsonViewTableCandidate } from './table-suitability.js';
+import { isHtmlDocument, isMarkdownText, normalizedKey } from './inference-fields.js';
+const MAX_COLLECTIONS = 4;
+const MAX_PREDICTED_VIEWS = 2;
+const MAX_FIELDS_PER_SHAPE = 64;
+const MAX_DISCOVERY_DEPTH = 3;
+const MAX_SAMPLE_ROWS = 10;
+const WORKFLOW_KEYS = new Set(['phase', 'stage', 'state', 'status']);
+const WORKFLOW_VALUES = new Set(['new', 'open', 'todo', 'to do', 'backlog', 'pending', 'in progress', 'in review', 'review', 'blocked', 'done', 'completed', 'closed', 'cancelled', 'qualified', 'contacted', 'proposal', 'negotiation', 'won', 'lost', 'customer']);
+const TITLE_KEY_ORDER = [
+    'name', 'title', 'label', 'displayname', 'fullname', 'firstname', 'headline', 'subject', 'email', 'id',
+];
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function friendlyLabel(value) {
+    const spaced = value
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .trim();
+    return spaced ? `${spaced[0].toLocaleUpperCase()}${spaced.slice(1)}` : 'Value';
+}
+function appendProperty(source, key) {
+    if (/^[A-Za-z_$][\w$]*$/.test(key))
+        return `${source}.${key}`;
+    const escaped = key
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+    return `${source}['${escaped}']`;
+}
+function jsonPath(path) {
+    return path.reduce((source, segment) => (typeof segment === 'number' ? `${source}[${segment}]` : appendProperty(source, segment)), '$');
+}
+function fieldPath(base, collection, parts) {
+    return parts.reduce(appendProperty, `${jsonPath(base)}${collection ? '[*]' : ''}`);
+}
+function slug(value) {
+    return value.toLocaleLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'view';
+}
+function recordCollection(value) {
+    if (Array.isArray(value)) {
+        if (value.length === 0 || !value.every(isRecord))
+            return undefined;
+        const rows = value.slice(0, MAX_SAMPLE_ROWS);
+        return rows;
+    }
+    if (!isRecord(value))
+        return undefined;
+    const values = Object.values(value);
+    if (values.length < 2 || !values.every(isRecord))
+        return undefined;
+    const rows = values.slice(0, MAX_SAMPLE_ROWS);
+    return rows;
+}
+function collectionLabel(path, rootValue) {
+    const last = path[path.length - 1];
+    if (typeof last === 'string')
+        return friendlyLabel(last);
+    return Array.isArray(rootValue) ? 'Data' : 'Records';
+}
+function discoverCollections(root) {
+    const candidates = [];
+    const visit = (value, path, depth, promote) => {
+        const rows = recordCollection(value);
+        if (rows) {
+            const table = isJsonViewTableCandidate(value);
+            candidates.push({
+                label: collectionLabel(path, root),
+                path,
+                rows,
+                score: (table && promote ? 2000 : table ? 1000 : 0) + 100 - depth * 12 + Math.min(rows.length, 20),
+                table,
+                promote,
+                value,
+            });
+            // Never promote a child of a record collection as a document-level view.
+            // Continue discovering its field types when the parent is not tabular.
+            if (table)
+                return;
+        }
+        if (depth >= MAX_DISCOVERY_DEPTH || !isRecord(value))
+            return;
+        const children = Object.entries(value).filter(([key]) => key !== '$jsonviews').map(([, child]) => child);
+        const recordDictionary = children.length >= 2 && children.every(isRecord);
+        Object.entries(value).forEach(([key, child]) => {
+            if (key === '$jsonviews')
+                return;
+            if (Array.isArray(child) || isRecord(child))
+                visit(child, [...path, key], depth + 1, promote && !rows && !recordDictionary);
+        });
+    };
+    visit(root, [], 0, true);
+    return candidates
+        .sort((left, right) => right.score - left.score)
+        .slice(0, MAX_COLLECTIONS);
+}
+function validWebUrl(value) {
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+function uniqueStrings(values, limit = 64) {
+    const unique = [];
+    const seen = new Set();
+    for (const value of values) {
+        if (!value || seen.has(value))
+            continue;
+        seen.add(value);
+        unique.push(value);
+        if (unique.length >= limit)
+            break;
+    }
+    return unique;
+}
+function descriptorFor(key, values) {
+    const present = values.filter((value) => value !== null && value !== undefined);
+    if (present.length === 0)
+        return undefined;
+    const title = friendlyLabel(key);
+    if (present.every((value) => typeof value === 'boolean'))
+        return { type: 'checkbox', title };
+    if (present.every((value) => typeof value === 'number' && Number.isFinite(value)))
+        return { type: 'number', title };
+    if (present.every((value) => Array.isArray(value) && value.every((item) => typeof item === 'string'))) {
+        const options = uniqueStrings(present.flatMap((value) => value), 41);
+        if (options.length === 0)
+            return undefined;
+        if (options.length <= 40 && options.every((option) => option.length <= 40 && !/[\n@]/.test(option) && !validWebUrl(option))) {
+            return { type: 'multi-select', title, options };
+        }
+        return undefined;
+    }
+    if (!present.every((value) => typeof value === 'string'))
+        return undefined;
+    const strings = present;
+    if (strings.every((value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)))
+        return { type: 'email', title };
+    if (strings.every(validWebUrl))
+        return { type: 'url', title };
+    const dates = strings.map(parseDateValue);
+    if (dates.every((date) => date.kind === 'date' || date.kind === 'datetime' || date.kind === 'floating-datetime')) {
+        return {
+            type: 'date',
+            title,
+            ...(dates.some((date) => date.kind !== 'date') ? { defaultIncludeTime: true } : {}),
+        };
+    }
+    const nonempty = strings.filter((value) => value.trim().length > 0);
+    if (nonempty.length > 0 && nonempty.some(isHtmlDocument))
+        return { type: 'html', title };
+    if (nonempty.length > 0 && nonempty.some(isMarkdownText))
+        return { type: 'markdown', title };
+    const options = uniqueStrings(strings, 21);
+    const repeatedSmallSet = options.length <= 20 && options.length < strings.length;
+    if (repeatedSmallSet && options.length >= 1
+        && options.every((option) => option.trim().length > 0 && option.length <= 40 && !/[\n@]/.test(option) && !validWebUrl(option))) {
+        return { type: 'select', title, options };
+    }
+    return { type: 'text', title };
+}
+function inferFields(rows, base, collection) {
+    const fields = [];
+    const visit = (records, parts, depth) => {
+        if (fields.length >= MAX_FIELDS_PER_SHAPE)
+            return;
+        const keys = [];
+        const seen = new Set();
+        records.forEach((record) => Object.keys(record).forEach((key) => {
+            if (key === '$jsonviews' || seen.has(key))
+                return;
+            seen.add(key);
+            keys.push(key);
+        }));
+        for (const key of keys) {
+            if (fields.length >= MAX_FIELDS_PER_SHAPE)
+                return;
+            const values = records.flatMap((record) => Object.prototype.hasOwnProperty.call(record, key) ? [record[key]] : []);
+            const present = values.filter((value) => value !== null && value !== undefined);
+            if (depth < 2 && present.length / records.length >= 0.8 && present.every(isRecord)
+                && !present.some((value) => recordCollection(value) !== undefined)) {
+                visit(present, [...parts, key], depth + 1);
+                continue;
+            }
+            const descriptor = descriptorFor(key, values);
+            if (descriptor || parts.length === 0) {
+                fields.push({
+                    ...(parts.length > 0 ? { label: [...parts, key].map(friendlyLabel).join(' · ') } : {}),
+                    ...(descriptor ? { descriptor } : {}),
+                    direct: parts.length === 0,
+                    key,
+                    path: fieldPath(base, collection, [...parts, key]),
+                });
+            }
+        }
+    };
+    visit(rows, [], 0);
+    return fields;
+}
+function titleField(fields, allowFallback = true) {
+    for (const key of TITLE_KEY_ORDER) {
+        const field = fields.find((candidate) => (candidate.direct
+            && normalizedKey(candidate.key) === key
+            && candidate.descriptor !== undefined
+            && ['text', 'email', 'select', 'number'].includes(candidate.descriptor.type)));
+        if (field)
+            return field;
+    }
+    return allowFallback ? fields.find((field) => field.descriptor && field.descriptor.type === 'text') : undefined;
+}
+/** Uses the metadata title policy. Disable the first-text fallback for record headings. */
+export function inferJsonViewRecordTitleKey(rows, allowFallback = true) {
+    return titleField(inferFields(rows, [], true), allowFallback)?.key;
+}
+function visibleColumns(fields, title) {
+    return title ? [title, ...fields.filter((field) => field !== title)] : [...fields];
+}
+function groupField(fields, value, title) {
+    if (!title || normalizedKey(title.key) === 'id' || !TITLE_KEY_ORDER.includes(normalizedKey(title.key)))
+        return undefined;
+    // Tables sample shape, but a board must account for every group it will show.
+    const rows = (Array.isArray(value) ? value : Object.values(value));
+    const titles = rows.map((row) => row[title.key]);
+    if (!titles.every((value) => typeof value === 'string' && value.trim().length > 0)
+        || new Set(titles).size / rows.length < 0.8)
+        return undefined;
+    return fields.find((field) => (field.direct
+        && field.descriptor?.type === 'select'
+        && WORKFLOW_KEYS.has(normalizedKey(field.key))
+        && field.descriptor.options?.every((option) => WORKFLOW_VALUES.has(option.toLowerCase().replace(/[_-]+/g, ' ').trim()))
+        && (field.descriptor.options?.length ?? 0) >= 2
+        && (field.descriptor.options?.length ?? 0) <= 6
+        && rows.every((row) => typeof row[field.key] === 'string' && String(row[field.key]).trim().length > 0
+            && field.descriptor.options.includes(row[field.key]))
+        && field.descriptor.options.every((option) => rows.filter((row) => row[field.key] === option).length >= 2)));
+}
+function uniqueId(preferred, used) {
+    let id = preferred;
+    let suffix = 2;
+    while (used.has(id)) {
+        id = `${preferred}-${suffix}`;
+        suffix += 1;
+    }
+    used.add(id);
+    return id;
+}
+/** Predicts useful metadata without mutating the source JSON. */
+export function inferJsonViewMetadata(root) {
+    const schema = {};
+    const views = [];
+    const usedIds = new Set();
+    const collections = discoverCollections(root);
+    if (isRecord(root) && recordCollection(root) === undefined) {
+        inferFields([root], [], false).forEach((field) => {
+            if (field.descriptor)
+                schema[field.path] = field.descriptor;
+        });
+    }
+    collections.forEach((collection) => {
+        const fields = inferFields(collection.rows, collection.path, true);
+        const allRows = (Array.isArray(collection.value) ? collection.value : Object.values(collection.value));
+        for (const key of new Set(allRows.flatMap((row) => Object.keys(row)))) {
+            if (key === '$jsonviews' || fields.some((field) => field.key === key && field.direct || field.path.startsWith(`${fieldPath(collection.path, true, [key])}.`)))
+                continue;
+            fields.push({ key, direct: true, path: fieldPath(collection.path, true, [key]) });
+        }
+        fields.forEach((field) => {
+            if (field.descriptor)
+                schema[field.path] = field.descriptor;
+        });
+        if (collection.path.length === 0 || !collection.table || !collection.promote)
+            return;
+        const title = titleField(fields);
+        const columns = visibleColumns(fields, title);
+        const path = jsonPath(collection.path);
+        const baseId = slug(collection.path.map(String).join('-') || collection.label);
+        const table = {
+            id: uniqueId(baseId, usedIds),
+            name: collection.label,
+            path,
+            ...(columns.length > 0 ? { columns: columns.map((field) => ({ label: field.label ?? field.descriptor?.title ?? friendlyLabel(field.key), path: field.path })) } : {}),
+        };
+        if (views.length < MAX_PREDICTED_VIEWS)
+            views.push(table);
+        const group = groupField(fields, collection.value, title);
+        if (group && views.length < MAX_PREDICTED_VIEWS) {
+            views.push({
+                ...table,
+                id: uniqueId(`${baseId}-board`, usedIds),
+                name: `${collection.label} board`,
+                display: 'kanban',
+                groupBy: group.path,
+            });
+        }
+    });
+    return { version: 1, schema, views };
+}

package/dist/json-limits.d.ts

@@ -0,0 +1,8 @@
+/** Maximum number of nested object/array containers supported by structured views. */
+export declare const MAX_JSON_DEPTH = 512;
+export declare class JsonDepthLimitError extends RangeError {
+    readonly code = "json-depth-limit";
+    constructor();
+}
+/** Iterative guard for callers supplying already-parsed data. Cycles also fail boundedly. */
+export declare function assertJsonDepth(root: unknown): void;

package/dist/json-limits.js

@@ -0,0 +1,25 @@
+/** Maximum number of nested object/array containers supported by structured views. */
+export const MAX_JSON_DEPTH = 512;
+export class JsonDepthLimitError extends RangeError {
+    code = 'json-depth-limit';
+    constructor() {
+        super(`This document exceeds the supported nesting limit of ${MAX_JSON_DEPTH} containers. Its original JSON source is preserved; reduce nesting to use structured views.`);
+        this.name = 'JsonDepthLimitError';
+    }
+}
+/** Iterative guard for callers supplying already-parsed data. Cycles also fail boundedly. */
+export function assertJsonDepth(root) {
+    const pending = [{ value: root, depth: 0 }];
+    while (pending.length) {
+        const { value, depth } = pending.pop();
+        if (value === null || typeof value !== 'object')
+            continue;
+        if (depth >= MAX_JSON_DEPTH)
+            throw new JsonDepthLimitError();
+        for (const key of Object.keys(value)) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (descriptor && 'value' in descriptor)
+                pending.push({ value: descriptor.value, depth: depth + 1 });
+        }
+    }
+}

package/dist/json-path.d.ts

@@ -0,0 +1,14 @@
+export type ValuePathSegment = string | number;
+export type ValuePath = readonly ValuePathSegment[];
+export declare const VALUE_PATH_MISSING: unique symbol;
+export declare function describeValuePath(path: ValuePath): string;
+/** Resolves an existing typed path or explains why it is invalid. */
+export declare function requireValueAtPath(root: unknown, path: ValuePath): unknown;
+/** Resolves typed segments without conflating array indices and object keys. */
+export declare function getValueAtPath(root: unknown, path: ValuePath): unknown | typeof VALUE_PATH_MISSING;
+/** Stable key for view state associated with an exact JSON path. */
+export declare function valuePathKey(path: ValuePath): string;
+/** Creates nested JSON data properties without following inherited objects or setters.
+ * Array writes may replace an existing item or append one item; sparse arrays are rejected.
+ */
+export declare function setJsonValueAtPath(root: object, path: ValuePath, value: unknown): void;