jsonc-effect 0.3.0 → 0.3.1

package/README.md

@@ -1,27 +1,31 @@
 # jsonc-effect
 
-[![npm version](https://img.shields.io/npm/v/jsonc-effect)](https://www.npmjs.com/package/jsonc-effect)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
+[![npm](https://img.shields.io/npm/v/jsonc-effect?label=npm&color=cb3837)](https://www.npmjs.com/package/jsonc-effect)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-Pure [Effect](https://effect.website) JSONC (JSON with Comments) parser with no external parser dependencies. Scanner, parser, AST, and formatting are all implemented natively.
+Pure [Effect](https://effect.website) JSONC (JSON with Comments) parser with no external parser dependencies. Scanner, parser, AST and formatting are all implemented natively.
 
 ## Features
 
-- **Effect-native** -- typed errors, Schema integration, and composable pipelines
+- **Effect-native** -- typed errors, Schema integration and composable pipelines
 - **Zero parser dependencies** -- `effect` is the sole runtime dependency
 - **Schema integration** -- parse JSONC strings directly into validated types
-- **Full toolchain** -- scanner, parser, AST navigation, visitor stream, formatting, and modification
-- **Equality comparisons** -- compare JSONC documents semantically, ignoring comments, formatting, and key ordering
+- **Full toolchain** -- scanner, parser, AST navigation, visitor stream, formatting and modification
+- **Byte-minimal edits** -- `modify` targets exactly the value's span, preserving surrounding whitespace and comments
+- **Equality comparisons** -- compare JSONC documents semantically, ignoring comments, formatting and key ordering
 - **Safe by default** -- returns `unknown` (not `any`) and `Option` (not `undefined`)
 
-## Installation
+## Install
 
 ```bash
 npm install jsonc-effect effect
+# or
+pnpm add jsonc-effect effect
 ```
 
-## Quick Start
+## Quick start
 
 ```typescript
 import { parse } from "jsonc-effect"
@@ -59,8 +63,10 @@ This library is for Effect-based programs that need deeper introspection and edi
 
 ## Documentation
 
-For API reference, advanced usage, and examples, see [docs](./docs/README.md).
+- [Getting started](./docs/01-getting-started.md) — installation, first example, core concepts
+- [Examples](./docs/02-examples.md) — real-world usage patterns
+- [API reference](./docs/03-api-reference.md) — all exports with signatures and descriptions
 
 ## License
 
-[MIT](./LICENSE)
+[MIT](LICENSE)

package/format.js

@@ -302,9 +302,13 @@ function modifyImpl(text, path, value, formattingOptions) {
 	}
 	const scanner = createScanner(text, true);
 	let currentToken = scanner.scan();
+	function tokenEnd() {
+		return scanner.getTokenOffset() + scanner.getTokenLength();
+	}
 	function skipValue() {
 		switch (currentToken) {
 			case "OpenBrace": {
+				let end = tokenEnd();
 				currentToken = scanner.scan();
 				let first = true;
 				while (currentToken !== "CloseBrace" && currentToken !== "EOF") {
@@ -313,28 +317,40 @@ function modifyImpl(text, path, value, formattingOptions) {
 						currentToken = scanner.scan();
 						if (currentToken === "Colon") {
 							currentToken = scanner.scan();
-							skipValue();
+							end = skipValue();
 						}
-					} else currentToken = scanner.scan();
+					} else {
+						end = tokenEnd();
+						currentToken = scanner.scan();
+					}
 					first = false;
 				}
-				if (currentToken === "CloseBrace") currentToken = scanner.scan();
-				break;
+				if (currentToken === "CloseBrace") {
+					end = tokenEnd();
+					currentToken = scanner.scan();
+				}
+				return end;
 			}
 			case "OpenBracket": {
+				let end = tokenEnd();
 				currentToken = scanner.scan();
 				let first = true;
 				while (currentToken !== "CloseBracket" && currentToken !== "EOF") {
 					if (!first && currentToken === "Comma") currentToken = scanner.scan();
-					skipValue();
+					end = skipValue();
 					first = false;
 				}
-				if (currentToken === "CloseBracket") currentToken = scanner.scan();
-				break;
+				if (currentToken === "CloseBracket") {
+					end = tokenEnd();
+					currentToken = scanner.scan();
+				}
+				return end;
 			}
-			default:
+			default: {
+				const end = tokenEnd();
 				currentToken = scanner.scan();
-				break;
+				return end;
+			}
 		}
 	}
 	let depth = 0;
@@ -357,8 +373,7 @@ function modifyImpl(text, path, value, formattingOptions) {
 						if (depth === path.length) {
 							const valueStart = scanner.getTokenOffset();
 							const prevEnd = valueStart;
-							skipValue();
-							const valueEnd = scanner.getTokenOffset();
+							const valueEnd = skipValue();
 							if (value === void 0) {
 								let removeStart = valueStart;
 								let removeEnd = valueEnd;
@@ -385,9 +400,11 @@ function modifyImpl(text, path, value, formattingOptions) {
 						}
 						break;
 					}
-					skipValue();
-				} else currentToken = scanner.scan();
-				lastValueEnd = scanner.getTokenOffset();
+					lastValueEnd = skipValue();
+				} else {
+					currentToken = scanner.scan();
+					lastValueEnd = scanner.getTokenOffset();
+				}
 				isFirst = false;
 			}
 			if (!found && depth === path.length && value !== void 0) {
@@ -410,8 +427,7 @@ function modifyImpl(text, path, value, formattingOptions) {
 				if (idx === segment) {
 					if (depth === path.length) {
 						const valueStart = scanner.getTokenOffset();
-						skipValue();
-						const valueEnd = scanner.getTokenOffset();
+						const valueEnd = skipValue();
 						if (value === void 0) {
 							let removeEnd = valueEnd;
 							if (text.substring(removeEnd).trimStart().startsWith(",")) removeEnd = text.indexOf(",", removeEnd) + 1;
@@ -430,8 +446,7 @@ function modifyImpl(text, path, value, formattingOptions) {
 					}
 					break;
 				}
-				skipValue();
-				lastEnd = scanner.getTokenOffset();
+				lastEnd = skipValue();
 				idx++;
 			}
 			if (idx <= segment && depth === path.length && value !== void 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "jsonc-effect",
-	"version": "0.3.0",
+	"version": "0.3.1",
 	"private": false,
 	"description": "Pure Effect-TS implementation of a JSONC (JSON with Comments) parser",
 	"keywords": [

package/parse.js

@@ -263,6 +263,9 @@ function parseInternal(text, options, buildTree) {
 			}
 		}
 	}
+	function tokenEnd() {
+		return scanner.getTokenOffset() + scanner.getTokenLength();
+	}
 	function handleError(code, skipUntilAfter = [], skipUntil = []) {
 		errors.push(new JsoncParseErrorDetail({
 			code,
@@ -372,8 +375,9 @@ function parseInternal(text, options, buildTree) {
 					length: 0,
 					value: scanner.getTokenValue()
 				};
+				const end = tokenEnd();
 				scanNext();
-				node.length = scanner.getTokenOffset() - node.offset;
+				node.length = end - node.offset;
 				return node;
 			}
 			case "Number": {
@@ -383,8 +387,9 @@ function parseInternal(text, options, buildTree) {
 					length: 0,
 					value: Number.parseFloat(scanner.getTokenValue())
 				};
+				const end = tokenEnd();
 				scanNext();
-				node.length = scanner.getTokenOffset() - node.offset;
+				node.length = end - node.offset;
 				return node;
 			}
 			case "True": {
@@ -394,8 +399,9 @@ function parseInternal(text, options, buildTree) {
 					length: 0,
 					value: true
 				};
+				const end = tokenEnd();
 				scanNext();
-				node.length = scanner.getTokenOffset() - node.offset;
+				node.length = end - node.offset;
 				return node;
 			}
 			case "False": {
@@ -405,8 +411,9 @@ function parseInternal(text, options, buildTree) {
 					length: 0,
 					value: false
 				};
+				const end = tokenEnd();
 				scanNext();
-				node.length = scanner.getTokenOffset() - node.offset;
+				node.length = end - node.offset;
 				return node;
 			}
 			case "Null": {
@@ -416,8 +423,9 @@ function parseInternal(text, options, buildTree) {
 					length: 0,
 					value: null
 				};
+				const end = tokenEnd();
 				scanNext();
-				node.length = scanner.getTokenOffset() - node.offset;
+				node.length = end - node.offset;
 				return node;
 			}
 			default: return;
@@ -443,9 +451,15 @@ function parseInternal(text, options, buildTree) {
 			else handleError("ValueExpected", [], ["CloseBracket", "Comma"]);
 			needsComma = true;
 		}
-		if (token() !== "CloseBracket") handleError("CloseBracketExpected");
-		else scanNext();
-		node.length = scanner.getTokenOffset() - node.offset;
+		let end;
+		if (token() !== "CloseBracket") {
+			handleError("CloseBracketExpected");
+			end = scanner.getTokenOffset();
+		} else {
+			end = tokenEnd();
+			scanNext();
+		}
+		node.length = end - node.offset;
 		return node;
 	}
 	function parseObjectTree() {
@@ -479,8 +493,9 @@ function parseInternal(text, options, buildTree) {
 				length: 0,
 				value: scanner.getTokenValue()
 			};
+			const keyEnd = tokenEnd();
 			scanNext();
-			keyNode.length = scanner.getTokenOffset() - keyNode.offset;
+			keyNode.length = keyEnd - keyNode.offset;
 			property.children.push(keyNode);
 			if (token() !== "Colon") {
 				handleError("ColonExpected", [], ["CloseBrace", "Comma"]);
@@ -491,15 +506,25 @@ function parseInternal(text, options, buildTree) {
 			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;
+			if (valueNode) {
+				property.children.push(valueNode);
+				property.length = valueNode.offset + valueNode.length - property.offset;
+			} 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;
+		let end;
+		if (token() !== "CloseBrace") {
+			handleError("CloseBraceExpected");
+			end = scanner.getTokenOffset();
+		} else {
+			end = tokenEnd();
+			scanNext();
+		}
+		node.length = end - node.offset;
 		return node;
 	}
 	scanNext();