jsonc-effect 0.2.1 → 0.3.0

package/package.json

@@ -1,58 +1,52 @@
 {
-  "name": "jsonc-effect",
-  "version": "0.2.1",
-  "private": false,
-  "description": "Pure Effect-TS implementation of a JSONC (JSON with Comments) parser",
-  "keywords": [
-    "jsonc",
-    "json",
-    "json-with-comments",
-    "parser",
-    "scanner",
-    "lexer",
-    "ast",
-    "effect",
-    "effect-ts",
-    "schema",
-    "typed-errors",
-    "config",
-    "tsconfig",
-    "formatting",
-    "visitor"
-  ],
-  "homepage": "https://github.com/spencerbeggs/jsonc-effect#readme",
-  "bugs": {
-    "url": "https://github.com/spencerbeggs/jsonc-effect/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/spencerbeggs/jsonc-effect.git"
-  },
-  "license": "MIT",
-  "author": {
-    "name": "C. Spencer Beggs",
-    "email": "spencer@beggs.codes",
-    "url": "https://spencerbeg.gs"
-  },
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./index.d.ts",
-      "import": "./index.js"
-    }
-  },
-  "peerDependencies": {
-    "effect": ">=3.21.0"
-  },
-  "files": [
-    "!jsonc-effect.api.json",
-    "!tsconfig.json",
-    "!tsdoc.json",
-    "LICENSE",
-    "README.md",
-    "index.d.ts",
-    "index.js",
-    "package.json",
-    "tsdoc-metadata.json"
-  ]
+	"name": "jsonc-effect",
+	"version": "0.3.0",
+	"private": false,
+	"description": "Pure Effect-TS implementation of a JSONC (JSON with Comments) parser",
+	"keywords": [
+		"jsonc",
+		"json",
+		"json-with-comments",
+		"parser",
+		"scanner",
+		"lexer",
+		"ast",
+		"effect",
+		"effect-ts",
+		"schema",
+		"typed-errors",
+		"config",
+		"tsconfig",
+		"formatting",
+		"visitor"
+	],
+	"homepage": "https://github.com/spencerbeggs/jsonc-effect#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/jsonc-effect/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/jsonc-effect.git"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"effect": "^3.21.0"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
 }

package/parse.js

@@ -0,0 +1,548 @@
+import { JsoncParseError, JsoncParseErrorDetail } from "./errors.js";
+import { createScanner } from "./scanner.js";
+import { Effect, Option } from "effect";
+
+//#region src/parse.ts
+/**
+* JSONC Parser — converts token stream into JavaScript values or AST nodes.
+*
+* Pure Effect implementation using recursive descent parsing.
+* Reference: Microsoft's jsonc-parser parser design (MIT).
+*
+* @packageDocumentation
+*/
+/**
+* Parse a JSONC string into a JavaScript value.
+*
+* @param text - JSONC string to parse
+* @param options - Optional {@link JsoncParseOptions} controlling comment and
+*   trailing-comma handling.
+* @returns `Effect<unknown, JsoncParseError>` — succeeds with the parsed value
+*   or fails with a {@link JsoncParseError} containing every error encountered.
+*
+* @remarks
+* The return type is `unknown` (not `any`) so consumers are forced to narrow
+* the result, which is safer in Effect pipelines. By default
+* `allowTrailingComma` is `true`, matching common JSONC conventions used in
+* VS Code settings and `tsconfig.json`.
+*
+* @see {@link parseTree} — parse into an AST instead of a plain value
+* @see {@link JsoncParseOptions} — available parse options
+* @see {@link JsoncParseError} — the tagged error type on the failure channel
+*
+* @example
+* Basic parsing:
+* ```ts
+* import { Effect } from "effect";
+* import { parse } from "jsonc-effect";
+*
+* const value = Effect.runSync(parse('{ "key": 42 }'));
+* console.log(value); // { key: 42 }
+* ```
+*
+* @example
+* Parsing with options:
+* ```ts
+* import { Effect } from "effect";
+* import { parse } from "jsonc-effect";
+*
+* const value = Effect.runSync(
+*   parse('{ "key": 42 }', { disallowComments: true }),
+* );
+* ```
+*
+* @example
+* Error handling with `catchTag`:
+* ```ts
+* import { Effect } from "effect";
+* import { parse } from "jsonc-effect";
+*
+* const program = parse("{ bad }").pipe(
+*   Effect.catchTag("JsoncParseError", (err) =>
+*     Effect.succeed({ fallback: true, errors: err.errors }),
+*   ),
+* );
+*
+* const result = Effect.runSync(program);
+* console.log(result);
+* ```
+*
+* @example
+* Using `Effect.gen`:
+* ```ts
+* import { Effect } from "effect";
+* import { parse } from "jsonc-effect";
+*
+* const program = Effect.gen(function* () {
+*   const config = yield* parse('{ "port": 3000 }');
+*   return config;
+* });
+*
+* const result = Effect.runSync(program);
+* console.log(result); // { port: 3000 }
+* ```
+*
+* @privateRemarks
+* Uses {@link createScanner} internally with a recursive descent parser.
+* The scanner is created with `ignoreTrivia = false` so the parser can
+* report comment-related errors when `disallowComments` is set.
+*
+* @public
+*/
+const parse = (text, options) => Effect.sync(() => parseInternal(text, options ?? {}, false)).pipe(Effect.flatMap(({ value, errors }) => {
+	if (errors.length > 0) return Effect.fail(new JsoncParseError({
+		errors,
+		text,
+		...options !== void 0 ? { options } : {}
+	}));
+	return Effect.succeed(value);
+}));
+/**
+* Parse a JSONC string into an immutable AST.
+*
+* @param text - JSONC string to parse
+* @param options - Optional {@link JsoncParseOptions} controlling comment and
+*   trailing-comma handling.
+* @returns `Effect<Option<JsoncNode>, JsoncParseError>` — succeeds with
+*   `Option.some(root)` for non-empty documents or `Option.none()` when the
+*   input is empty (and `allowEmptyContent` is set).
+*
+* @remarks
+* The returned AST is immutable and does **not** contain parent pointers, which
+* keeps nodes safe to share across fibers. Use the AST navigation helpers
+* ({@link findNode}, {@link getNodeValue}) to traverse and extract values from
+* the tree.
+*
+* `Option.none()` is returned only when the document contains no value tokens
+* and `allowEmptyContent` is enabled; otherwise an empty document produces a
+* {@link JsoncParseError}.
+*
+* @see {@link parse} — parse into a plain JavaScript value instead of an AST
+* @see {@link findNode} — locate a node by JSON path segments
+* @see {@link getNodeValue} — extract the JavaScript value from a subtree
+* @see {@link JsoncNode} — the AST node type
+*
+* @example
+* Parsing a JSONC string and navigating the tree:
+* ```ts
+* import { Effect, Option } from "effect";
+* import { parseTree } from "jsonc-effect";
+*
+* const program = Effect.gen(function* () {
+*   const maybeRoot = yield* parseTree('{ "a": [1, 2, 3] }');
+*   if (Option.isSome(maybeRoot)) {
+*     const root = maybeRoot.value;
+*     console.log(root.type); // "object"
+*     console.log(root.children?.length); // 1
+*   }
+* });
+*
+* Effect.runSync(program);
+* ```
+*
+* @privateRemarks
+* Internally the parser builds a mutable tree using `MutableJsoncNode` and
+* casts to the readonly `JsoncNode` on output.
+*
+* @public
+*/
+const parseTree = (text, options) => Effect.sync(() => parseInternal(text, options ?? {}, true)).pipe(Effect.flatMap(({ root, errors }) => {
+	if (errors.length > 0) return Effect.fail(new JsoncParseError({
+		errors,
+		text,
+		...options !== void 0 ? { options } : {}
+	}));
+	return Effect.succeed(root ? Option.some(root) : Option.none());
+}));
+/**
+* Remove all comments from JSONC text, producing valid JSON.
+*
+* @param text - JSONC string to strip comments from
+* @param replaceCh - Optional single character used to replace each character of
+*   every comment. When provided, the output has the **same length** as the
+*   input so that all offsets are preserved (line breaks inside block comments
+*   are kept as-is).
+* @returns `Effect<string>` — the text with all comments removed (or replaced).
+*
+* @remarks
+* When `replaceCh` is omitted the comment text is simply deleted, which means
+* character offsets in the output no longer match the original document. Pass a
+* space (`" "`) as `replaceCh` to keep offsets stable — this is useful when you
+* need to correlate positions between the original JSONC and the stripped JSON.
+*
+* @see {@link parse} — parse JSONC directly without a stripping step
+*
+* @example
+* Basic comment stripping:
+* ```ts
+* import { Effect } from "effect";
+* import { stripComments } from "jsonc-effect";
+*
+* const json = Effect.runSync(
+*   stripComments('{ "a": 1 // comment\n}'),
+* );
+* console.log(json); // '{ "a": 1 \n}'
+* ```
+*
+* @example
+* Using a replacement character to preserve offsets:
+* ```ts
+* import { Effect } from "effect";
+* import { stripComments } from "jsonc-effect";
+*
+* const json = Effect.runSync(
+*   stripComments('{ "a": 1 // comment\n}', " "),
+* );
+* console.log(json.length === '{ "a": 1 // comment\n}'.length); // true
+* ```
+*
+* @public
+*/
+const stripComments = (text, replaceCh) => Effect.sync(() => {
+	const scanner = createScanner(text);
+	const parts = [];
+	let lastOffset = 0;
+	let kind;
+	do {
+		kind = scanner.scan();
+		const offset = scanner.getTokenOffset();
+		const length = scanner.getTokenLength();
+		if (kind === "LineComment" || kind === "BlockComment") {
+			if (lastOffset < offset) parts.push(text.substring(lastOffset, offset));
+			if (replaceCh !== void 0) for (let i = 0; i < length; i++) {
+				const ch = text.charCodeAt(offset + i);
+				parts.push(ch === 10 || ch === 13 ? text[offset + i] : replaceCh);
+			}
+			lastOffset = offset + length;
+		}
+	} while (kind !== "EOF");
+	if (lastOffset < text.length) parts.push(text.substring(lastOffset));
+	return parts.join("");
+});
+function parseInternal(text, options, buildTree) {
+	const scanner = createScanner(text, false);
+	const errors = [];
+	const disallowComments = options.disallowComments ?? false;
+	const allowTrailingComma = options.allowTrailingComma ?? true;
+	const allowEmptyContent = options.allowEmptyContent ?? false;
+	let currentToken = "Unknown";
+	function token() {
+		return currentToken;
+	}
+	function scanNext() {
+		for (;;) {
+			currentToken = scanner.scan();
+			switch (scanner.getTokenError()) {
+				case "InvalidUnicode":
+					handleError("InvalidUnicode");
+					break;
+				case "InvalidEscapeCharacter":
+					handleError("InvalidEscapeCharacter");
+					break;
+				case "UnexpectedEndOfNumber":
+					handleError("InvalidNumberFormat");
+					break;
+				case "UnexpectedEndOfComment":
+					handleError("UnexpectedEndOfComment");
+					break;
+				case "UnexpectedEndOfString":
+					handleError("UnexpectedEndOfString");
+					break;
+				case "InvalidCharacter":
+					handleError("InvalidCharacter");
+					break;
+			}
+			switch (currentToken) {
+				case "LineComment":
+				case "BlockComment":
+					if (disallowComments) handleError("InvalidCommentToken");
+					break;
+				case "Trivia":
+				case "LineBreak": break;
+				default: return currentToken;
+			}
+		}
+	}
+	function handleError(code, skipUntilAfter = [], skipUntil = []) {
+		errors.push(new JsoncParseErrorDetail({
+			code,
+			message: formatError(code, scanner.getTokenOffset()),
+			offset: scanner.getTokenOffset(),
+			length: scanner.getTokenLength(),
+			startLine: scanner.getTokenStartLine(),
+			startCharacter: scanner.getTokenStartCharacter()
+		}));
+		if (skipUntilAfter.length > 0 || skipUntil.length > 0) {
+			let t = token();
+			while (t !== "EOF") {
+				if (skipUntilAfter.includes(t)) {
+					scanNext();
+					break;
+				}
+				if (skipUntil.includes(t)) break;
+				t = scanNext();
+			}
+		}
+	}
+	function parseValue() {
+		switch (token()) {
+			case "OpenBracket": return parseArray();
+			case "OpenBrace": return parseObject();
+			case "String": return parseString();
+			case "Number": return parseNumber();
+			case "True":
+				scanNext();
+				return true;
+			case "False":
+				scanNext();
+				return false;
+			case "Null":
+				scanNext();
+				return null;
+			default: return;
+		}
+	}
+	function parseString() {
+		const value = scanner.getTokenValue();
+		scanNext();
+		return value;
+	}
+	function parseNumber() {
+		const value = Number.parseFloat(scanner.getTokenValue());
+		scanNext();
+		return value;
+	}
+	function parseArray() {
+		scanNext();
+		const arr = [];
+		let needsComma = false;
+		while (token() !== "CloseBracket" && token() !== "EOF") {
+			if (token() === "Comma") {
+				if (!needsComma) handleError("ValueExpected");
+				scanNext();
+				if (token() === "CloseBracket" && allowTrailingComma) break;
+			} else if (needsComma) handleError("CommaExpected");
+			const value = parseValue();
+			if (value === void 0) handleError("ValueExpected", [], ["CloseBracket", "Comma"]);
+			else arr.push(value);
+			needsComma = true;
+		}
+		if (token() !== "CloseBracket") handleError("CloseBracketExpected");
+		else scanNext();
+		return arr;
+	}
+	function parseObject() {
+		scanNext();
+		const obj = {};
+		let needsComma = false;
+		while (token() !== "CloseBrace" && token() !== "EOF") {
+			if (token() === "Comma") {
+				if (!needsComma) handleError("PropertyNameExpected");
+				scanNext();
+				if (token() === "CloseBrace" && allowTrailingComma) break;
+			} else if (needsComma) handleError("CommaExpected");
+			if (token() !== "String") {
+				handleError("PropertyNameExpected", [], ["CloseBrace", "Comma"]);
+				continue;
+			}
+			const key = scanner.getTokenValue();
+			scanNext();
+			if (token() !== "Colon") {
+				handleError("ColonExpected", [], ["CloseBrace", "Comma"]);
+				continue;
+			}
+			scanNext();
+			const value = parseValue();
+			if (value === void 0) handleError("ValueExpected", [], ["CloseBrace", "Comma"]);
+			else obj[key] = value;
+			needsComma = true;
+		}
+		if (token() !== "CloseBrace") handleError("CloseBraceExpected");
+		else scanNext();
+		return obj;
+	}
+	function parseValueTree() {
+		switch (token()) {
+			case "OpenBracket": return parseArrayTree();
+			case "OpenBrace": return parseObjectTree();
+			case "String": {
+				const node = {
+					type: "string",
+					offset: scanner.getTokenOffset(),
+					length: 0,
+					value: scanner.getTokenValue()
+				};
+				scanNext();
+				node.length = scanner.getTokenOffset() - node.offset;
+				return node;
+			}
+			case "Number": {
+				const node = {
+					type: "number",
+					offset: scanner.getTokenOffset(),
+					length: 0,
+					value: Number.parseFloat(scanner.getTokenValue())
+				};
+				scanNext();
+				node.length = scanner.getTokenOffset() - node.offset;
+				return node;
+			}
+			case "True": {
+				const node = {
+					type: "boolean",
+					offset: scanner.getTokenOffset(),
+					length: 0,
+					value: true
+				};
+				scanNext();
+				node.length = scanner.getTokenOffset() - node.offset;
+				return node;
+			}
+			case "False": {
+				const node = {
+					type: "boolean",
+					offset: scanner.getTokenOffset(),
+					length: 0,
+					value: false
+				};
+				scanNext();
+				node.length = scanner.getTokenOffset() - node.offset;
+				return node;
+			}
+			case "Null": {
+				const node = {
+					type: "null",
+					offset: scanner.getTokenOffset(),
+					length: 0,
+					value: null
+				};
+				scanNext();
+				node.length = scanner.getTokenOffset() - node.offset;
+				return node;
+			}
+			default: return;
+		}
+	}
+	function parseArrayTree() {
+		const node = {
+			type: "array",
+			offset: scanner.getTokenOffset(),
+			length: 0,
+			children: []
+		};
+		scanNext();
+		let needsComma = false;
+		while (token() !== "CloseBracket" && token() !== "EOF") {
+			if (token() === "Comma") {
+				if (!needsComma) handleError("ValueExpected");
+				scanNext();
+				if (token() === "CloseBracket" && allowTrailingComma) break;
+			} else if (needsComma) handleError("CommaExpected");
+			const child = parseValueTree();
+			if (child) node.children.push(child);
+			else handleError("ValueExpected", [], ["CloseBracket", "Comma"]);
+			needsComma = true;
+		}
+		if (token() !== "CloseBracket") handleError("CloseBracketExpected");
+		else scanNext();
+		node.length = scanner.getTokenOffset() - node.offset;
+		return node;
+	}
+	function parseObjectTree() {
+		const node = {
+			type: "object",
+			offset: scanner.getTokenOffset(),
+			length: 0,
+			children: []
+		};
+		scanNext();
+		let needsComma = false;
+		while (token() !== "CloseBrace" && token() !== "EOF") {
+			if (token() === "Comma") {
+				if (!needsComma) handleError("PropertyNameExpected");
+				scanNext();
+				if (token() === "CloseBrace" && allowTrailingComma) break;
+			} else if (needsComma) handleError("CommaExpected");
+			if (token() !== "String") {
+				handleError("PropertyNameExpected", [], ["CloseBrace", "Comma"]);
+				continue;
+			}
+			const property = {
+				type: "property",
+				offset: scanner.getTokenOffset(),
+				length: 0,
+				children: []
+			};
+			const keyNode = {
+				type: "string",
+				offset: scanner.getTokenOffset(),
+				length: 0,
+				value: scanner.getTokenValue()
+			};
+			scanNext();
+			keyNode.length = scanner.getTokenOffset() - keyNode.offset;
+			property.children.push(keyNode);
+			if (token() !== "Colon") {
+				handleError("ColonExpected", [], ["CloseBrace", "Comma"]);
+				property.length = scanner.getTokenOffset() - property.offset;
+				node.children.push(property);
+				continue;
+			}
+			property.colonOffset = scanner.getTokenOffset();
+			scanNext();
+			const valueNode = parseValueTree();
+			if (valueNode) property.children.push(valueNode);
+			else handleError("ValueExpected", [], ["CloseBrace", "Comma"]);
+			property.length = scanner.getTokenOffset() - property.offset;
+			node.children.push(property);
+			needsComma = true;
+		}
+		if (token() !== "CloseBrace") handleError("CloseBraceExpected");
+		else scanNext();
+		node.length = scanner.getTokenOffset() - node.offset;
+		return node;
+	}
+	scanNext();
+	if (buildTree) {
+		const root = parseValueTree();
+		if (token() !== "EOF") handleError("EndOfFileExpected");
+		if (!root && !allowEmptyContent) handleError("ValueExpected");
+		return {
+			value: void 0,
+			root,
+			errors
+		};
+	}
+	const value = parseValue();
+	if (token() !== "EOF") handleError("EndOfFileExpected");
+	if (value === void 0 && !allowEmptyContent) handleError("ValueExpected");
+	return {
+		value,
+		root: void 0,
+		errors
+	};
+}
+function formatError(code, offset) {
+	switch (code) {
+		case "InvalidSymbol": return `Invalid symbol at offset ${offset}`;
+		case "InvalidNumberFormat": return `Invalid number format at offset ${offset}`;
+		case "PropertyNameExpected": return `Property name expected at offset ${offset}`;
+		case "ValueExpected": return `Value expected at offset ${offset}`;
+		case "ColonExpected": return `Colon expected at offset ${offset}`;
+		case "CommaExpected": return `Comma expected at offset ${offset}`;
+		case "CloseBraceExpected": return `Close brace expected at offset ${offset}`;
+		case "CloseBracketExpected": return `Close bracket expected at offset ${offset}`;
+		case "EndOfFileExpected": return `End of file expected at offset ${offset}`;
+		case "InvalidCommentToken": return `Comments not allowed at offset ${offset}`;
+		case "UnexpectedEndOfComment": return `Unexpected end of comment at offset ${offset}`;
+		case "UnexpectedEndOfString": return `Unexpected end of string at offset ${offset}`;
+		case "UnexpectedEndOfNumber": return `Unexpected end of number at offset ${offset}`;
+		case "InvalidUnicode": return `Invalid unicode escape at offset ${offset}`;
+		case "InvalidEscapeCharacter": return `Invalid escape character at offset ${offset}`;
+		case "InvalidCharacter": return `Invalid character at offset ${offset}`;
+		default: return `Parse error at offset ${offset}`;
+	}
+}
+
+//#endregion
+export { parse, parseTree, stripComments };