jsonc-effect 0.2.0 → 0.3.0

package/ast.js

@@ -0,0 +1,255 @@
+import { Effect, Function, Option } from "effect";
+
+//#region src/ast.ts
+/**
+* AST navigation functions for JSONC parse trees.
+*
+* Operates on JsoncNode trees produced by parseTree().
+*
+* @packageDocumentation
+*/
+/**
+* Find an AST node at a specific JSON path.
+*
+* Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
+* for both data-first and data-last (pipeline) usage.
+*
+* @param root - The AST root node obtained from {@link parseTree}.
+* @param path - An array of string keys and numeric indices describing the path to traverse.
+*
+* @returns `Effect<Option<JsoncNode>>` — the node at the given path, or `Option.none()` if the
+*   path does not exist in the tree.
+*
+* @remarks
+* String segments navigate object properties and number segments navigate array indices.
+* Returns `Option.none()` when any segment along the path cannot be resolved — for example,
+* accessing a property on a non-object node or an out-of-bounds array index.
+*
+* @see {@link parseTree} — produces the AST root this function operates on
+* @see {@link getNodeValue} — reconstructs a JS value from a found node
+* @see {@link JsoncNode} — the AST node type
+* @see {@link (JsoncPath:type)} — the path segment array type
+*
+* @example Data-first usage
+* ```ts
+* import { Effect, Option } from "effect";
+* import type { JsoncNode } from "jsonc-effect";
+* import { parseTree, findNode } from "jsonc-effect";
+*
+* const program = Effect.gen(function* () {
+*   const root: Option.Option<JsoncNode> = yield* parseTree('{ "a": { "b": 1 } }');
+*   if (Option.isNone(root)) return Option.none();
+*   return yield* findNode(root.value, ["a", "b"]);
+* });
+*
+* const result = Effect.runSync(program);
+* // result is Option.some(node) where node.value === 1
+* ```
+*
+* @example Data-last pipeline usage
+* ```ts
+* import { Effect, Option, pipe } from "effect";
+* import type { JsoncNode } from "jsonc-effect";
+* import { parseTree, findNode } from "jsonc-effect";
+*
+* const program = Effect.gen(function* () {
+*   const root: Option.Option<JsoncNode> = yield* parseTree('{ "x": [10, 20] }');
+*   if (Option.isNone(root)) return Option.none();
+*   return yield* pipe(root.value, findNode(["x", 1]));
+* });
+*
+* const result = Effect.runSync(program);
+* // result is Option.some(node) where node.value === 20
+* ```
+*
+* @privateRemarks
+* Wrapped in `Effect.sync`; the underlying traversal is fully synchronous.
+*
+* @public
+*/
+const findNode = Function.dual(2, (root, path) => Effect.sync(() => findNodeImpl(root, path)));
+/**
+* Find the innermost AST node covering a character offset.
+*
+* Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
+* for both data-first and data-last (pipeline) usage.
+*
+* @param root - The AST root node obtained from {@link parseTree}.
+* @param offset - A zero-based character offset into the original JSONC string.
+*
+* @returns `Effect<Option<JsoncNode>>` — the most deeply nested node whose span
+*   includes the offset, or `Option.none()` if the offset is outside the tree.
+*
+* @remarks
+* This is useful for editor integrations such as hover information, go-to-definition,
+* and code completions where you need to identify the token under the cursor.
+*
+* @see {@link parseTree} — produces the AST root this function operates on
+* @see {@link getNodePath} — returns the JSON path to the node at an offset
+*
+* @example Finding a node at an offset
+* ```ts
+* import { Effect, Option } from "effect";
+* import type { JsoncNode } from "jsonc-effect";
+* import { parseTree, findNodeAtOffset } from "jsonc-effect";
+*
+* const program = Effect.gen(function* () {
+*   const root: Option.Option<JsoncNode> = yield* parseTree('{ "key": "value" }');
+*   if (Option.isNone(root)) return Option.none();
+*   // Offset 10 is inside the "value" string literal
+*   return yield* findNodeAtOffset(root.value, 10);
+* });
+*
+* const result = Effect.runSync(program);
+* // result is Option.some(node) where node.type === "string"
+* ```
+*
+* @privateRemarks
+* Wrapped in `Effect.sync`; the underlying traversal is fully synchronous.
+*
+* @public
+*/
+const findNodeAtOffset = Function.dual(2, (root, offset) => Effect.sync(() => findNodeAtOffsetImpl(root, offset)));
+/**
+* Get the JSON path to the node at a specific character offset.
+*
+* Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
+* for both data-first and data-last (pipeline) usage.
+*
+* @param root - The AST root node obtained from {@link parseTree}.
+* @param targetOffset - A zero-based character offset into the original JSONC string.
+*
+* @returns `Effect<Option<JsoncPath>>` — an array of path segments (string keys
+*   and numeric indices) leading to the innermost node at the offset, or
+*   `Option.none()` if the offset is outside the tree.
+*
+* @remarks
+* Returns the path segments leading to the innermost node that spans the given
+* offset. This is the inverse of {@link findNode} — given an offset you get the path,
+* and given a path you get the node.
+*
+* @see {@link findNodeAtOffset} — returns the node itself rather than its path
+* @see {@link (JsoncPath:type)} — the path segment array type
+*
+* @example Getting the path at an offset
+* ```ts
+* import { Effect, Option } from "effect";
+* import type { JsoncNode, JsoncPath } from "jsonc-effect";
+* import { parseTree, getNodePath } from "jsonc-effect";
+*
+* const program = Effect.gen(function* () {
+*   const root: Option.Option<JsoncNode> = yield* parseTree('{ "a": { "b": 42 } }');
+*   if (Option.isNone(root)) return Option.none();
+*   // Offset 15 points inside the value 42
+*   return yield* getNodePath(root.value, 15);
+* });
+*
+* const result: Option.Option<JsoncPath> = Effect.runSync(program);
+* // result is Option.some(["a", "b"])
+* ```
+*
+* @public
+*/
+const getNodePath = Function.dual(2, (root, targetOffset) => Effect.sync(() => buildPath(root, targetOffset, [])));
+/**
+* Reconstruct a plain JavaScript value from an AST subtree.
+*
+* @param node - The AST node to evaluate, typically obtained via {@link findNode} or
+*   as the root from {@link parseTree}.
+*
+* @returns `Effect<unknown>` — the reconstructed JS value (object, array, string,
+*   number, boolean, or null).
+*
+* @remarks
+* Recursively evaluates the node tree to produce a plain JavaScript value.
+* This is the inverse of {@link parseTree}: where `parseTree` turns a JSONC string
+* into an AST, `getNodeValue` turns an AST subtree back into a JS value.
+*
+* @see {@link parseTree} — produces the AST that this function evaluates
+* @see {@link findNode} — locates a subtree to pass to this function
+*
+* @example Extracting the value of a found node
+* ```ts
+* import { Effect, Option } from "effect";
+* import type { JsoncNode } from "jsonc-effect";
+* import { parseTree, findNode, getNodeValue } from "jsonc-effect";
+*
+* const program = Effect.gen(function* () {
+*   const root: Option.Option<JsoncNode> = yield* parseTree('{ "items": [1, 2, 3] }');
+*   if (Option.isNone(root)) return undefined;
+*   const node: Option.Option<JsoncNode> = yield* findNode(root.value, ["items"]);
+*   if (Option.isNone(node)) return undefined;
+*   return yield* getNodeValue(node.value);
+* });
+*
+* const result = Effect.runSync(program);
+* // result is [1, 2, 3]
+* ```
+*
+* @privateRemarks
+* Useful after {@link findNode} to extract a subtree's value without manual
+* AST traversal.
+*
+* @public
+*/
+const getNodeValue = (node) => Effect.sync(() => evaluateNode(node));
+function findNodeImpl(root, path) {
+	let current = root;
+	for (const segment of path) {
+		if (!current?.children) return Option.none();
+		if (typeof segment === "string") {
+			if (current.type !== "object") return Option.none();
+			current = current.children.find((child) => child.type === "property" && child.children !== void 0 && child.children[0]?.value === segment)?.children?.[1];
+		} else {
+			if (current.type !== "array") return Option.none();
+			current = current.children[segment];
+		}
+	}
+	return current ? Option.some(current) : Option.none();
+}
+function findNodeAtOffsetImpl(root, offset) {
+	if (offset < root.offset || offset >= root.offset + root.length) return Option.none();
+	if (!root.children) return Option.some(root);
+	for (const child of root.children) if (offset >= child.offset && offset < child.offset + child.length) return findNodeAtOffsetImpl(child, offset);
+	return Option.some(root);
+}
+function buildPath(node, targetOffset, currentPath) {
+	if (targetOffset < node.offset || targetOffset >= node.offset + node.length) return Option.none();
+	if (!node.children) return Option.some(currentPath);
+	if (node.type === "object") {
+		for (const prop of node.children) if (prop.type === "property" && prop.children !== void 0 && targetOffset >= prop.offset && targetOffset < prop.offset + prop.length) {
+			const key = prop.children[0]?.value;
+			const valuePath = [...currentPath, key];
+			const valueChild = prop.children[1];
+			if (valueChild && targetOffset >= valueChild.offset && targetOffset < valueChild.offset + valueChild.length) return buildPath(valueChild, targetOffset, valuePath);
+			return Option.some(valuePath);
+		}
+	} else if (node.type === "array") for (let i = 0; i < node.children.length; i++) {
+		const child = node.children[i];
+		if (targetOffset >= child.offset && targetOffset < child.offset + child.length) return buildPath(child, targetOffset, [...currentPath, i]);
+	}
+	return Option.some(currentPath);
+}
+function evaluateNode(node) {
+	switch (node.type) {
+		case "object": {
+			const obj = {};
+			if (node.children) {
+				for (const prop of node.children) if (prop.type === "property" && prop.children !== void 0 && prop.children.length === 2) {
+					const key = prop.children[0].value;
+					obj[key] = evaluateNode(prop.children[1]);
+				}
+			}
+			return obj;
+		}
+		case "array": return (node.children ?? []).map(evaluateNode);
+		case "property": return node.children?.[1] ? evaluateNode(node.children[1]) : void 0;
+		case "string":
+		case "number":
+		case "boolean":
+		case "null": return node.value;
+	}
+}
+
+//#endregion
+export { findNode, findNodeAtOffset, getNodePath, getNodeValue };

package/equality.js

@@ -0,0 +1,166 @@
+import { parse } from "./parse.js";
+import { Effect, Function } from "effect";
+
+//#region src/equality.ts
+/**
+* JSONC equality comparisons — semantic equivalence for JSONC documents.
+*
+* Compares parsed values ignoring comments, whitespace, formatting,
+* and object key ordering.
+*
+* @packageDocumentation
+*/
+/**
+* Deep-compare two plain JS values for structural equality (key-order independent for objects, order sensitive for arrays).
+*
+* @internal
+*/
+function deepEqual(a, b) {
+	if (a === b) return true;
+	if (a === null || b === null) return false;
+	if (typeof a !== typeof b) return false;
+	if (Array.isArray(a)) {
+		if (!Array.isArray(b)) return false;
+		if (a.length !== b.length) return false;
+		for (let i = 0; i < a.length; i++) if (!deepEqual(a[i], b[i])) return false;
+		return true;
+	}
+	if (Array.isArray(b)) return false;
+	if (typeof a === "object" && typeof b === "object") {
+		const aObj = a;
+		const bObj = b;
+		const aKeys = Object.keys(aObj);
+		const bKeys = Object.keys(bObj);
+		if (aKeys.length !== bKeys.length) return false;
+		for (const key of aKeys) {
+			if (!Object.hasOwn(bObj, key)) return false;
+			if (!deepEqual(aObj[key], bObj[key])) return false;
+		}
+		return true;
+	}
+	return false;
+}
+/**
+* Compare two JSONC strings for semantic equality.
+*
+* Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
+* for both data-first and data-last (pipeline) usage.
+*
+* @param self - The first JSONC string.
+* @param that - The second JSONC string.
+*
+* @returns `Effect<boolean, JsoncParseError>` — `true` when both strings parse to
+*   semantically equivalent values, `false` otherwise. Fails with
+*   {@link JsoncParseError} if either string is malformed.
+*
+* @remarks
+* Both strings are parsed via {@link parse} and then deep-compared. The comparison
+* ignores comments, whitespace, formatting, and object key ordering. Array order
+* IS significant. Uses `Effect.all` internally, so the effect fails on the first
+* parse error encountered.
+*
+* @see {@link equalsValue} — compare a JSONC string against an existing JS value
+* @see {@link parse} — the underlying parser used for both strings
+*
+* @example Data-first comparison
+* ```ts
+* import { Effect } from "effect";
+* import { equals } from "jsonc-effect";
+*
+* const result = Effect.runSync(
+*   equals('{ "a": 1, "b": 2 }', '{"b":2,"a":1}')
+* );
+* // result is true
+* ```
+*
+* @example Key-order independence
+* ```ts
+* import { Effect } from "effect";
+* import { equals } from "jsonc-effect";
+*
+* // Object key order does not matter
+* const sameKeys = Effect.runSync(
+*   equals('{"z":1,"a":2}', '{"a":2,"z":1}')
+* );
+* // sameKeys is true
+*
+* // Array order DOES matter
+* const differentOrder = Effect.runSync(
+*   equals('[1, 2]', '[2, 1]')
+* );
+* // differentOrder is false
+* ```
+*
+* @example Error handling
+* ```ts
+* import { Effect, Either } from "effect";
+* import type { JsoncParseError } from "jsonc-effect";
+* import { equals } from "jsonc-effect";
+*
+* const result: Either.Either<boolean, JsoncParseError> = Effect.runSync(
+*   Effect.either(equals('{ invalid }', '{}'))
+* );
+* // result is Either.left(JsoncParseError)
+* ```
+*
+* @privateRemarks
+* Uses a simple recursive `deepEqual` helper rather than Effect's `Equal` module
+* because the parsed values are plain JS objects and arrays, not Effect data types.
+*
+* @public
+*/
+const equals = Function.dual(2, (self, that) => Effect.map(Effect.all([parse(self), parse(that)]), ([a, b]) => deepEqual(a, b)));
+/**
+* Compare a JSONC string against a JavaScript value for semantic equality.
+*
+* Supports {@link https://effect.website/docs/effect/function#dual | Function.dual}
+* for both data-first and data-last (pipeline) usage.
+*
+* @param self - The JSONC string to parse.
+* @param value - The JavaScript value to compare against.
+*
+* @returns `Effect<boolean, JsoncParseError>` — `true` when the parsed JSONC
+*   is semantically equivalent to the provided value, `false` otherwise.
+*   Fails with {@link JsoncParseError} if the string is malformed.
+*
+* @remarks
+* Only the JSONC string is parsed; the JS value is used as-is. This makes
+* `equalsValue` useful for assertions and testing where the expected value
+* is already a JS object. The comparison semantics are the same as
+* {@link equals}: comments, whitespace, formatting, and object key ordering
+* are ignored, while array order IS significant.
+*
+* @see {@link equals} — compare two JSONC strings against each other
+* @see {@link parse} — the underlying parser
+*
+* @example Basic comparison
+* ```ts
+* import { Effect } from "effect";
+* import { equalsValue } from "jsonc-effect";
+*
+* const result = Effect.runSync(
+*   equalsValue('{"port": 3000, "host": "localhost"}', { host: "localhost", port: 3000 })
+* );
+* // result is true
+* ```
+*
+* @example Pipeline usage for testing
+* ```ts
+* import { Effect, pipe } from "effect";
+* import { equalsValue } from "jsonc-effect";
+*
+* const jsonc = '{ "enabled": true, "count": 5 }';
+* const expected = { enabled: true, count: 5 };
+*
+* const result = Effect.runSync(
+*   pipe(jsonc, equalsValue(expected))
+* );
+* // result is true
+* ```
+*
+* @public
+*/
+const equalsValue = Function.dual(2, (self, value) => Effect.map(parse(self), (parsed) => deepEqual(parsed, value)));
+
+//#endregion
+export { equals, equalsValue };

package/errors.js

@@ -0,0 +1,218 @@
+import { Data, Schema } from "effect";
+
+//#region src/errors.ts
+/**
+* JSONC error types using Effect's Data.TaggedError pattern.
+*
+* @packageDocumentation
+*/
+/**
+* Error codes representing specific JSONC parse failures.
+*
+* @remarks
+* Each code maps to a distinct syntactic error the parser can encounter,
+* from invalid symbols and number formats to missing delimiters and
+* unexpected end-of-input conditions.
+*
+* @see {@link JsoncParseErrorDetail} — carries one of these codes alongside
+*   position information
+*
+* @public
+*/
+const JsoncParseErrorCode = Schema.Literal("InvalidSymbol", "InvalidNumberFormat", "PropertyNameExpected", "ValueExpected", "ColonExpected", "CommaExpected", "CloseBraceExpected", "CloseBracketExpected", "EndOfFileExpected", "InvalidCommentToken", "UnexpectedEndOfComment", "UnexpectedEndOfString", "UnexpectedEndOfNumber", "InvalidUnicode", "InvalidEscapeCharacter", "InvalidCharacter");
+/**
+* Detail for a single parse error, including the error code, a human-readable
+* message, and the exact position within the source document.
+*
+* @remarks
+* - `code` — a {@link (JsoncParseErrorCode:type)} identifying the error kind.
+* - `message` — a descriptive message suitable for display.
+* - `offset` — zero-based character offset where the error occurred.
+* - `length` — character length of the problematic span.
+* - `startLine` — zero-based line number of the error.
+* - `startCharacter` — zero-based column within `startLine`.
+*
+* @see {@link JsoncParseError} — aggregates an array of these details
+*
+* @example
+* ```ts
+* import { JsoncParseErrorDetail } from "jsonc-effect";
+*
+* const detail = new JsoncParseErrorDetail({
+*   code: "ValueExpected",
+*   message: "Value expected",
+*   offset: 5,
+*   length: 1,
+*   startLine: 0,
+*   startCharacter: 5,
+* });
+*
+* console.log(detail.code); // "ValueExpected"
+* console.log(detail.offset); // 5
+* ```
+*
+* @public
+*/
+var JsoncParseErrorDetail = class extends Schema.Class("JsoncParseErrorDetail")({
+	code: JsoncParseErrorCode,
+	message: Schema.String,
+	offset: Schema.Number,
+	length: Schema.Number,
+	startLine: Schema.Number,
+	startCharacter: Schema.Number
+}) {};
+/**
+* Base class for {@link JsoncParseError}; not intended to be constructed or
+* caught directly — use `JsoncParseError` instead.
+*
+* @privateRemarks
+* The `*Base` pattern is required because `Data.TaggedError` produces complex
+* type signatures involving intersection types and branded generics that
+* api-extractor cannot roll up into a single `.d.ts` bundle. Exporting the
+* base separately lets the public `JsoncParseError` class extend it with
+* concrete fields, giving api-extractor a simple class declaration to work
+* with. It is tagged `@public` (rather than `@internal`) because it appears
+* in `JsoncParseError`'s heritage clause in the public `.d.ts`, and API
+* Extractor requires release tags to be compatible across a signature.
+*
+* @public
+*/
+const JsoncParseErrorBase = Data.TaggedError("JsoncParseError");
+/**
+* Error raised when JSONC parsing encounters one or more syntax errors.
+*
+* @remarks
+* Contains the full source `text`, the `options` used for parsing, and an
+* `errors` array of {@link JsoncParseErrorDetail} instances with precise
+* position information for each problem found.
+*
+* @see {@link parse} — may fail with this error
+* @see {@link parseTree} — may fail with this error
+*
+* @example Catching with `Effect.catchTag`
+* ```ts
+* import { Effect } from "effect";
+* import { parse } from "jsonc-effect";
+*
+* const program = parse("{ invalid }").pipe(
+*   Effect.catchTag("JsoncParseError", (e) => {
+*     console.error(e.errors); // Array of JsoncParseErrorDetail
+*     return Effect.succeed({});
+*   }),
+* );
+* ```
+*
+* @example Inspecting error details
+* ```ts
+* import { Effect } from "effect";
+* import { parse } from "jsonc-effect";
+*
+* const program = parse("{ invalid }").pipe(
+*   Effect.catchTag("JsoncParseError", (e) => {
+*     for (const detail of e.errors) {
+*       console.error(
+*         `[${detail.code}] ${detail.message} at line ${detail.startLine}:${detail.startCharacter}`,
+*       );
+*     }
+*     return Effect.succeed({});
+*   }),
+* );
+* ```
+*
+* @public
+*/
+var JsoncParseError = class extends JsoncParseErrorBase {
+	get message() {
+		const count = this.errors.length;
+		return `JSONC parse failed with ${count} error${count !== 1 ? "s" : ""}: ${this.errors.map((e) => e.message).join("; ")}`;
+	}
+};
+/**
+* Base class for {@link JsoncNodeNotFoundError}; not intended to be
+* constructed or caught directly — use `JsoncNodeNotFoundError` instead.
+*
+* @privateRemarks
+* Uses the same `*Base` pattern as {@link JsoncParseErrorBase} to work
+* around api-extractor's inability to roll up the complex type produced
+* by `Data.TaggedError` into a single `.d.ts` declaration. Tagged `@public`
+* for the same heritage-clause-compatibility reason as `JsoncParseErrorBase`.
+*
+* @public
+*/
+const JsoncNodeNotFoundErrorBase = Data.TaggedError("JsoncNodeNotFoundError");
+/**
+* Error raised when AST navigation fails to find a node at the given path.
+*
+* @remarks
+* Contains the `path` that was searched and the `rootNodeType` of the tree
+* that was traversed.
+*
+* @see {@link findNode} — may fail with this error
+*
+* @example
+* ```ts
+* import { Effect } from "effect";
+* import { parseTree, findNode } from "jsonc-effect";
+*
+* const program = parseTree('{ "a": 1 }').pipe(
+*   Effect.flatMap((root) => findNode(root, ["missing", "path"])),
+*   Effect.catchTag("JsoncNodeNotFoundError", (e) => {
+*     console.error(`Not found: [${e.path.join(", ")}] in ${e.rootNodeType}`);
+*     return Effect.succeed(undefined);
+*   }),
+* );
+* ```
+*
+* @public
+*/
+var JsoncNodeNotFoundError = class extends JsoncNodeNotFoundErrorBase {
+	get message() {
+		return `Node not found at path [${this.path.join(", ")}] in ${this.rootNodeType} node`;
+	}
+};
+/**
+* Base class for {@link JsoncModificationError}; not intended to be
+* constructed or caught directly — use `JsoncModificationError` instead.
+*
+* @privateRemarks
+* Uses the same `*Base` pattern as {@link JsoncParseErrorBase} to work
+* around api-extractor's inability to roll up the complex type produced
+* by `Data.TaggedError` into a single `.d.ts` declaration. Tagged `@public`
+* for the same heritage-clause-compatibility reason as `JsoncParseErrorBase`.
+*
+* @public
+*/
+const JsoncModificationErrorBase = Data.TaggedError("JsoncModificationError");
+/**
+* Error raised when {@link modify} produces invalid edits or encounters
+* an unsupported modification scenario.
+*
+* @remarks
+* Contains the `path` where modification was attempted and a `reason`
+* string explaining why it failed.
+*
+* @see {@link modify} — may fail with this error
+*
+* @example
+* ```ts
+* import { Effect } from "effect";
+* import { modify } from "jsonc-effect";
+*
+* const program = modify("{}", ["deep", "path"], 42).pipe(
+*   Effect.catchTag("JsoncModificationError", (e) => {
+*     console.error(`Failed at [${e.path.join(", ")}]: ${e.reason}`);
+*     return Effect.succeed([]);
+*   }),
+* );
+* ```
+*
+* @public
+*/
+var JsoncModificationError = class extends JsoncModificationErrorBase {
+	get message() {
+		return `Modification failed at path [${this.path.join(", ")}]: ${this.reason}`;
+	}
+};
+
+//#endregion
+export { JsoncModificationError, JsoncModificationErrorBase, JsoncNodeNotFoundError, JsoncNodeNotFoundErrorBase, JsoncParseError, JsoncParseErrorBase, JsoncParseErrorCode, JsoncParseErrorDetail };