jsonc-effect 0.2.0 → 0.3.0

package/scanner.js

@@ -0,0 +1,350 @@
+//#region src/scanner.ts
+const isWhitespace = (ch) => ch === 32 || ch === 9 || ch === 11 || ch === 12 || ch === 160 || ch === 65279;
+const isLineBreak = (ch) => ch === 10 || ch === 13 || ch === 8232 || ch === 8233;
+const isDigit = (ch) => ch >= 48 && ch <= 57;
+/**
+* Create a stateful {@link JsoncScanner} for the given JSONC string.
+*
+* @param text - JSONC string to tokenize
+* @param ignoreTrivia - If `true`, the scanner automatically skips whitespace,
+*   line-break, and comment tokens so that only structural tokens are returned
+*   (default: `false`).
+* @returns A stateful {@link JsoncScanner} positioned before the first token.
+*
+* @remarks
+* When `ignoreTrivia` is `true` the scanner is suitable for building parsers
+* that only care about structural tokens (`OpenBrace`, `String`, `Number`,
+* etc.). Set it to `false` (the default) when you need to preserve comments
+* or whitespace — for example in a formatter or a comment-stripping pass.
+*
+* @see {@link JsoncScanner} — the interface returned by this factory
+* @see {@link parse} — higher-level API that uses a scanner internally
+*
+* @example
+* Tokenizing a JSONC string and printing each token:
+* ```ts
+* import type { JsoncSyntaxKind } from "jsonc-effect";
+* import { createScanner } from "jsonc-effect";
+*
+* const scanner = createScanner('{ "name": "jsonc" }', true);
+* let kind: JsoncSyntaxKind;
+* do {
+*   kind = scanner.scan();
+*   console.log(kind, scanner.getTokenValue());
+* } while (kind !== "EOF");
+* ```
+*
+* @privateRemarks
+* Ported from Microsoft's jsonc-parser (MIT), adapted to use string literal
+* token types instead of numeric enums.
+*
+* @public
+*/
+const createScanner = (text, ignoreTrivia = false) => {
+	const len = text.length;
+	let pos = 0;
+	let tokenOffset = 0;
+	let token = "Unknown";
+	let tokenValue = "";
+	let tokenError = "None";
+	let lineNumber = 0;
+	let lineStartOffset = 0;
+	let tokenStartLine = 0;
+	let tokenStartCharacter = 0;
+	const scanHexDigits = (count) => {
+		let value = 0;
+		for (let i = 0; i < count; i++) {
+			if (pos >= len) return -1;
+			const ch = text.charCodeAt(pos);
+			if (ch >= 48 && ch <= 57) value = value * 16 + (ch - 48);
+			else if (ch >= 65 && ch <= 70) value = value * 16 + (ch - 65 + 10);
+			else if (ch >= 97 && ch <= 102) value = value * 16 + (ch - 97 + 10);
+			else return -1;
+			pos++;
+		}
+		return value;
+	};
+	const scanString = () => {
+		let result = "";
+		pos++;
+		let start = pos;
+		while (pos < len) {
+			const ch = text.charCodeAt(pos);
+			if (ch === 34) {
+				result += text.substring(start, pos);
+				pos++;
+				return result;
+			}
+			if (ch === 92) {
+				result += text.substring(start, pos);
+				pos++;
+				if (pos >= len) {
+					tokenError = "UnexpectedEndOfString";
+					return result;
+				}
+				const escaped = text.charCodeAt(pos);
+				pos++;
+				switch (escaped) {
+					case 34:
+						result += "\"";
+						break;
+					case 92:
+						result += "\\";
+						break;
+					case 47:
+						result += "/";
+						break;
+					case 98:
+						result += "\b";
+						break;
+					case 102:
+						result += "\f";
+						break;
+					case 110:
+						result += "\n";
+						break;
+					case 114:
+						result += "\r";
+						break;
+					case 116:
+						result += "	";
+						break;
+					case 117: {
+						const value = scanHexDigits(4);
+						if (value >= 0) result += String.fromCharCode(value);
+						else tokenError = "InvalidUnicode";
+						break;
+					}
+					default:
+						tokenError = "InvalidEscapeCharacter";
+						break;
+				}
+				start = pos;
+			} else if (isLineBreak(ch)) {
+				tokenError = "UnexpectedEndOfString";
+				return result + text.substring(start, pos);
+			} else pos++;
+		}
+		tokenError = "UnexpectedEndOfString";
+		return result + text.substring(start, pos);
+	};
+	const scanNumber = () => {
+		const start = pos;
+		if (text.charCodeAt(pos) === 45) pos++;
+		if (text.charCodeAt(pos) === 48) pos++;
+		else {
+			if (!isDigit(text.charCodeAt(pos))) {
+				tokenError = "UnexpectedEndOfNumber";
+				return text.substring(start, pos);
+			}
+			pos++;
+			while (pos < len && isDigit(text.charCodeAt(pos))) pos++;
+		}
+		if (pos < len && text.charCodeAt(pos) === 46) {
+			pos++;
+			if (!isDigit(text.charCodeAt(pos))) {
+				tokenError = "UnexpectedEndOfNumber";
+				return text.substring(start, pos);
+			}
+			pos++;
+			while (pos < len && isDigit(text.charCodeAt(pos))) pos++;
+		}
+		if (pos < len && (text.charCodeAt(pos) === 69 || text.charCodeAt(pos) === 101)) {
+			pos++;
+			if (pos < len && (text.charCodeAt(pos) === 43 || text.charCodeAt(pos) === 45)) pos++;
+			if (!isDigit(text.charCodeAt(pos))) {
+				tokenError = "UnexpectedEndOfNumber";
+				return text.substring(start, pos);
+			}
+			pos++;
+			while (pos < len && isDigit(text.charCodeAt(pos))) pos++;
+		}
+		return text.substring(start, pos);
+	};
+	const scan = () => {
+		tokenValue = "";
+		tokenError = "None";
+		if (pos >= len) {
+			tokenOffset = len;
+			tokenStartLine = lineNumber;
+			tokenStartCharacter = pos - lineStartOffset;
+			token = "EOF";
+			return token;
+		}
+		let ch = text.charCodeAt(pos);
+		if (isWhitespace(ch)) {
+			tokenOffset = pos;
+			tokenStartLine = lineNumber;
+			tokenStartCharacter = pos - lineStartOffset;
+			do {
+				pos++;
+				ch = pos < len ? text.charCodeAt(pos) : 0;
+			} while (isWhitespace(ch));
+			tokenValue = text.substring(tokenOffset, pos);
+			if (ignoreTrivia) return scan();
+			token = "Trivia";
+			return token;
+		}
+		if (isLineBreak(ch)) {
+			tokenOffset = pos;
+			tokenStartLine = lineNumber;
+			tokenStartCharacter = pos - lineStartOffset;
+			pos++;
+			if (ch === 13 && pos < len && text.charCodeAt(pos) === 10) pos++;
+			lineNumber++;
+			lineStartOffset = pos;
+			tokenValue = text.substring(tokenOffset, pos);
+			if (ignoreTrivia) return scan();
+			token = "LineBreak";
+			return token;
+		}
+		tokenOffset = pos;
+		tokenStartLine = lineNumber;
+		tokenStartCharacter = pos - lineStartOffset;
+		switch (ch) {
+			case 123:
+				pos++;
+				tokenValue = "{";
+				token = "OpenBrace";
+				return token;
+			case 125:
+				pos++;
+				tokenValue = "}";
+				token = "CloseBrace";
+				return token;
+			case 91:
+				pos++;
+				tokenValue = "[";
+				token = "OpenBracket";
+				return token;
+			case 93:
+				pos++;
+				tokenValue = "]";
+				token = "CloseBracket";
+				return token;
+			case 58:
+				pos++;
+				tokenValue = ":";
+				token = "Colon";
+				return token;
+			case 44:
+				pos++;
+				tokenValue = ",";
+				token = "Comma";
+				return token;
+			case 34:
+				tokenValue = scanString();
+				token = "String";
+				return token;
+			case 47: {
+				const nextCh = pos + 1 < len ? text.charCodeAt(pos + 1) : 0;
+				if (nextCh === 47) {
+					pos += 2;
+					while (pos < len && !isLineBreak(text.charCodeAt(pos))) pos++;
+					tokenValue = text.substring(tokenOffset, pos);
+					if (ignoreTrivia) return scan();
+					token = "LineComment";
+					return token;
+				}
+				if (nextCh === 42) {
+					pos += 2;
+					const safeLen = len - 1;
+					let commentClosed = false;
+					while (pos < safeLen) {
+						const cch = text.charCodeAt(pos);
+						if (isLineBreak(cch)) {
+							if (cch === 13 && pos + 1 < len && text.charCodeAt(pos + 1) === 10) pos++;
+							pos++;
+							lineNumber++;
+							lineStartOffset = pos;
+						} else if (cch === 42 && text.charCodeAt(pos + 1) === 47) {
+							pos += 2;
+							commentClosed = true;
+							break;
+						} else pos++;
+					}
+					if (!commentClosed) {
+						pos = len;
+						tokenError = "UnexpectedEndOfComment";
+					}
+					tokenValue = text.substring(tokenOffset, pos);
+					if (ignoreTrivia) return scan();
+					token = "BlockComment";
+					return token;
+				}
+				pos++;
+				tokenValue = text.substring(tokenOffset, pos);
+				token = "Unknown";
+				tokenError = "InvalidCharacter";
+				return token;
+			}
+			case 45:
+				if (pos + 1 < len && isDigit(text.charCodeAt(pos + 1))) {
+					tokenValue = scanNumber();
+					token = "Number";
+					return token;
+				}
+				pos++;
+				tokenValue = "-";
+				token = "Unknown";
+				tokenError = "InvalidSymbol";
+				return token;
+			default:
+				if (isDigit(ch)) {
+					tokenValue = scanNumber();
+					token = "Number";
+					return token;
+				}
+				if (ch >= 97 && ch <= 122) {
+					const start = pos;
+					pos++;
+					while (pos < len) {
+						const kch = text.charCodeAt(pos);
+						if (kch >= 97 && kch <= 122) pos++;
+						else break;
+					}
+					tokenValue = text.substring(start, pos);
+					switch (tokenValue) {
+						case "true":
+							token = "True";
+							return token;
+						case "false":
+							token = "False";
+							return token;
+						case "null":
+							token = "Null";
+							return token;
+						default:
+							token = "Unknown";
+							tokenError = "InvalidSymbol";
+							return token;
+					}
+				}
+				pos++;
+				tokenValue = text.substring(tokenOffset, pos);
+				token = "Unknown";
+				tokenError = "InvalidCharacter";
+				return token;
+		}
+	};
+	return {
+		scan,
+		getToken: () => token,
+		getTokenValue: () => tokenValue,
+		getTokenOffset: () => tokenOffset,
+		getTokenLength: () => pos - tokenOffset,
+		getTokenStartLine: () => tokenStartLine,
+		getTokenStartCharacter: () => tokenStartCharacter,
+		getTokenError: () => tokenError,
+		getPosition: () => pos,
+		setPosition: (newPos) => {
+			pos = newPos;
+			tokenValue = "";
+			token = "Unknown";
+			tokenError = "None";
+		}
+	};
+};
+
+//#endregion
+export { createScanner };

package/schema-integration.js

@@ -0,0 +1,178 @@
+import { parse } from "./parse.js";
+import { Effect, ParseResult, Schema } from "effect";
+
+//#region src/schema-integration.ts
+/**
+* Schema-based JSONC parsing pipelines.
+*
+* Transforms JSONC strings directly into typed domain objects
+* using Schema.transformOrFail and Schema.compose.
+*
+* @packageDocumentation
+*/
+/**
+* Pre-built `Schema<unknown, string>` that decodes a JSONC string into an
+* unknown JavaScript value using default parse options.
+*
+* This is the first stage of a typical parsing pipeline:
+*
+* ```
+* JSONC string  --JsoncFromString-->  unknown  --YourSchema-->  A
+* ```
+*
+* @remarks
+* Default parse options are used (comments allowed, trailing commas
+* allowed). The encode direction uses `JSON.stringify` with 2-space
+* indentation, which means comments present in the original JSONC
+* input are not preserved during a round-trip encode.
+*
+* For custom parse options, use {@link makeJsoncFromString} instead.
+*
+* @see {@link makeJsoncFromString} to create a schema with custom options.
+* @see {@link makeJsoncSchema} to compose JSONC parsing with a domain schema
+*   in one step.
+*
+* @example Decode a JSONC string
+* ```ts
+* import { Schema } from "effect";
+* import { JsoncFromString } from "jsonc-effect";
+*
+* const value: unknown = Schema.decodeUnknownSync(JsoncFromString)(
+*   '{ "key": 42 // comment\n}',
+* );
+* ```
+*
+* @example Compose with a domain schema
+* ```ts
+* import { Schema } from "effect";
+* import { JsoncFromString } from "jsonc-effect";
+*
+* const MyConfig = Schema.Struct({
+*   name: Schema.String,
+*   version: Schema.Number,
+* });
+*
+* const MyConfigFromJsonc = Schema.compose(JsoncFromString, MyConfig);
+* const config = Schema.decodeUnknownSync(MyConfigFromJsonc)(
+*   '{ "name": "app", "version": 1 }',
+* );
+* ```
+*
+* @public
+*/
+const JsoncFromString = makeJsoncFromString();
+/**
+* Create a `Schema<unknown, string>` that decodes JSONC with custom
+* parse options.
+*
+* @param options - Partial {@link JsoncParseOptions} controlling comment
+*   handling and trailing-comma tolerance.
+* @returns A `Schema<unknown, string>` configured with the given options.
+*
+* @remarks
+* The encode direction uses `JSON.stringify` with 2-space indentation,
+* which produces standard JSON. Comments present in the original JSONC
+* input are not preserved during a round-trip encode.
+*
+* @see {@link JsoncFromString} for a zero-config default instance.
+* @see {@link makeJsoncSchema} to compose JSONC parsing with a domain
+*   schema in one step.
+*
+* @example Strict mode (no comments, no trailing commas)
+* ```ts
+* import { Schema } from "effect";
+* import { makeJsoncFromString } from "jsonc-effect";
+*
+* const StrictJsoncFromString = makeJsoncFromString({
+*   disallowComments: true,
+*   allowTrailingComma: false,
+* });
+*
+* const value: unknown = Schema.decodeUnknownSync(StrictJsoncFromString)(
+*   '{ "key": 42 }',
+* );
+* ```
+*
+* @privateRemarks
+* Internally delegates to `Schema.transformOrFail` to wire up the decode
+* and encode directions.
+*
+* @public
+*/
+function makeJsoncFromString(options) {
+	return Schema.transformOrFail(Schema.String, Schema.Unknown, {
+		strict: true,
+		decode: (input, _options, ast) => {
+			const program = options ? parse(input, options) : parse(input);
+			return Effect.mapError(program, (parseError) => new ParseResult.Type(ast, input, parseError.message));
+		},
+		encode: (value) => ParseResult.succeed(JSON.stringify(value, null, 2))
+	}).annotations({
+		title: "JsoncFromString",
+		description: "Parse a JSONC string into an unknown JavaScript value"
+	});
+}
+/**
+* Create a composed `Schema<A, string>` that parses a JSONC string and
+* validates the result against a target domain schema in one step.
+*
+* @param targetSchema - The domain schema to validate the parsed value
+*   against. Its input type `I` must be assignable from `unknown`.
+* @param options - Optional partial {@link JsoncParseOptions} forwarded to
+*   the underlying JSONC parser.
+* @returns A `Schema<A, string>` that goes directly from a JSONC string
+*   to a fully validated domain value of type `A`.
+*
+* @remarks
+* Internally composes two schema stages:
+*
+* 1. JSONC string to `unknown` (via {@link makeJsoncFromString}).
+* 2. `unknown` to `A` (via the provided `targetSchema`).
+*
+* This avoids the need to manually call `Schema.compose`.
+*
+* @see {@link makeJsoncFromString} for the first stage of the pipeline.
+*
+* @example Typed configuration from JSONC
+* ```ts
+* import { Schema } from "effect";
+* import { makeJsoncSchema } from "jsonc-effect";
+*
+* const MyConfig = Schema.Struct({
+*   name: Schema.String,
+*   version: Schema.Number,
+* });
+*
+* const MyConfigFromJsonc = makeJsoncSchema(MyConfig);
+* const config = Schema.decodeUnknownSync(MyConfigFromJsonc)(
+*   '{ "name": "app", "version": 1 }',
+* );
+* ```
+*
+* @example With custom parse options
+* ```ts
+* import { Schema } from "effect";
+* import { makeJsoncSchema } from "jsonc-effect";
+*
+* const MyConfig = Schema.Struct({ debug: Schema.Boolean });
+*
+* const StrictConfig = makeJsoncSchema(MyConfig, {
+*   disallowComments: true,
+*   allowTrailingComma: false,
+* });
+*
+* const config = Schema.decodeUnknownSync(StrictConfig)(
+*   '{ "debug": true }',
+* );
+* ```
+*
+* @privateRemarks
+* Uses `Schema.compose` internally to chain the JSONC-from-string schema
+* with the provided target schema.
+*
+* @public
+*/
+const makeJsoncSchema = (targetSchema, options) => Schema.compose(makeJsoncFromString(options), targetSchema);
+
+//#endregion
+export { JsoncFromString, makeJsoncFromString, makeJsoncSchema };