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

package/dist/json-path.js

@@ -0,0 +1,84 @@
+export const VALUE_PATH_MISSING = Symbol('value-path-missing');
+export function describeValuePath(path) {
+    if (path.length === 0)
+        return '<root>';
+    return path
+        .map((segment) => typeof segment === 'number' ? `[${segment}]` : `[${JSON.stringify(segment)}]`)
+        .join('');
+}
+/** Resolves an existing typed path or explains why it is invalid. */
+export function requireValueAtPath(root, path) {
+    let current = root;
+    for (let index = 0; index < path.length; index++) {
+        const segment = path[index];
+        if (Array.isArray(current)) {
+            if (typeof segment !== 'number' || !Number.isInteger(segment) || segment < 0) {
+                throw new TypeError(`JSON array path segment at index ${index} must be a non-negative integer`);
+            }
+            if (segment >= current.length || !Object.prototype.hasOwnProperty.call(current, segment)) {
+                throw new RangeError(`JSON path ${describeValuePath(path)} does not exist`);
+            }
+            current = current[segment];
+            continue;
+        }
+        if (current !== null && typeof current === 'object') {
+            if (typeof segment !== 'string') {
+                throw new TypeError(`JSON object path segment at index ${index} must be a string`);
+            }
+            if (!Object.prototype.hasOwnProperty.call(current, segment)) {
+                throw new RangeError(`JSON path ${describeValuePath(path)} does not exist`);
+            }
+            current = current[segment];
+            continue;
+        }
+        throw new TypeError(`JSON path ${describeValuePath(path.slice(0, index))} is not a container`);
+    }
+    return current;
+}
+/** Resolves typed segments without conflating array indices and object keys. */
+export function getValueAtPath(root, path) {
+    try {
+        return requireValueAtPath(root, path);
+    }
+    catch {
+        return VALUE_PATH_MISSING;
+    }
+}
+/** Stable key for view state associated with an exact JSON path. */
+export function valuePathKey(path) {
+    return JSON.stringify(path);
+}
+/** 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 function setJsonValueAtPath(root, path, value) {
+    if (path.length === 0)
+        throw new TypeError('A property path is required');
+    let current = root;
+    for (let index = 0; index < path.length; index += 1) {
+        const segment = path[index];
+        if (Array.isArray(current)) {
+            if (typeof segment !== 'number' || !Number.isSafeInteger(segment) || segment < 0 || segment > current.length) {
+                throw new TypeError('Array writes require an existing index or the next consecutive index');
+            }
+        }
+        else if (typeof segment !== 'string') {
+            throw new TypeError('Object writes require a string property');
+        }
+        if (index === path.length - 1) {
+            Object.defineProperty(current, segment, { value, enumerable: true, writable: true, configurable: true });
+            return;
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(current, segment);
+        const child = descriptor && 'value' in descriptor ? descriptor.value : undefined;
+        const needsArray = typeof path[index + 1] === 'number';
+        if (child !== null && typeof child === 'object' && Array.isArray(child) === needsArray) {
+            current = child;
+        }
+        else {
+            const next = needsArray ? [] : Object.create(null);
+            Object.defineProperty(current, segment, { value: next, enumerable: true, writable: true, configurable: true });
+            current = next;
+        }
+    }
+}

package/dist/json-source-patcher.d.ts

@@ -0,0 +1,97 @@
+import { type AtomicValue } from './atomic-value.js';
+import { type ValuePath } from './json-path.js';
+export interface JsonSourceRange {
+    start: number;
+    end: number;
+}
+/** Locates the exact source span represented by a parsed JSON value path. */
+export declare function jsonSourceRangeAtPath(source: string, path: ValuePath): JsonSourceRange;
+/** Locates several value paths with one source parse, preserving path order. */
+export declare function jsonSourceRangesAtPaths(source: string, paths: readonly ValuePath[]): JsonSourceRange[];
+/** Serializes only JSON data: finite numbers, strings, booleans, null, dense arrays,
+ * and plain data objects. Accessors, toJSON methods, cycles and lossy coercions are rejected.
+ */
+export declare function stringifyJsonValue(value: unknown, space?: number): string;
+export interface JsonSourceDiagnostic {
+    /** The token belongs to an earlier duplicate property or one of its descendants. */
+    shadowed?: boolean;
+    code: 'duplicate-key' | 'unsafe-number';
+    sourcePath: ValuePath;
+    message: string;
+    token: string;
+    start: number;
+    end: number;
+    help?: import('./annotation-capabilities.js').JsonViewDiagnosticHelp;
+}
+/** Reads a source-preserving inspection value and identifies information JSON.parse cannot retain. */
+export declare function inspectJsonSource(source: string): {
+    value: unknown;
+    diagnostics: JsonSourceDiagnostic[];
+};
+/** Replaces one existing JSON value while preserving every unrelated source byte. */
+export declare function replaceJsonValueInSource(source: string, path: ValuePath, next: unknown): string;
+/** Adds or replaces one property while preserving the surrounding JSON source. */
+export declare function upsertJsonObjectPropertyInSource(source: string, objectPath: ValuePath, key: string, next: unknown): string;
+/** Appends one item while preserving every byte outside the target array. */
+export declare function appendJsonArrayItemInSource(source: string, arrayPath: ValuePath, next: unknown): string;
+export interface JsonValueReplacement {
+    path: ValuePath;
+    value: unknown;
+}
+export interface JsonPropertyUpsert {
+    objectPath: ValuePath;
+    key: string;
+    value: unknown;
+}
+/** Adds/replaces properties against one source scan, preserving unrelated tokens. */
+export declare function upsertJsonObjectPropertiesInSource(source: string, changes: readonly JsonPropertyUpsert[]): string;
+/** Replaces independent existing values as one source-preserving document update. */
+export declare function replaceJsonValuesInSource(source: string, replacements: readonly JsonValueReplacement[]): string;
+/** Parses, validates, and replaces only the selected atomic token in the source. */
+export declare function replaceJsonAtomicValueInSource(source: string, path: ValuePath, next: AtomicValue): string;
+/** Removes one array item or object property while preserving unrelated JSON source bytes. */
+export declare function removeJsonValueInSource(source: string, path: ValuePath): string;
+/** Removes locations in the original source, independent of caller order.
+ * Duplicate locations are idempotent; ancestor/descendant plans are rejected.
+ * Adjacent siblings share a removal span so commas remain valid.
+ */
+export declare function removeJsonValuesInSource(source: string, paths: readonly ValuePath[]): string;
+export type JsonPatchOperation = {
+    op: 'add';
+    path: string;
+    value: unknown;
+} | {
+    op: 'remove';
+    path: string;
+} | {
+    op: 'replace';
+    path: string;
+    value: unknown;
+} | {
+    op: 'move';
+    path: string;
+    from: string;
+} | {
+    op: 'copy';
+    path: string;
+    from: string;
+} | {
+    op: 'test';
+    path: string;
+    value: unknown;
+};
+export type JsonPatchErrorCode = 'invalid-document' | 'invalid-patch' | 'invalid-operation' | 'invalid-pointer' | 'missing-path' | 'invalid-array-index' | 'invalid-value' | 'test-failed' | 'move-into-descendant' | 'root-removal-not-supported';
+export declare class JsonPatchError extends Error {
+    readonly code: JsonPatchErrorCode;
+    readonly path?: string;
+    readonly from?: string;
+    operationIndex?: number;
+    constructor(code: JsonPatchErrorCode, message: string, details?: {
+        path?: string;
+        from?: string;
+        operationIndex?: number;
+        cause?: unknown;
+    });
+}
+/** Applies an RFC 6902 JSON Patch atomically while preserving every unrelated source byte. */
+export declare function applyJsonPatchInSource(source: string, patch: readonly unknown[]): string;