@effected/toml 0.9.0 → 0.11.0

package/README.md

@@ -7,10 +7,10 @@
 
 Zero-dependency TOML 1.1.0 parsing, editing and formatting expressed as Effect schemas and pure functions. Parse TOML into plain values or a byte-exact linear CST, compute comment-preserving edits, format, modify by path, walk a document as a `Stream`, and decode straight into a validated domain schema.
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered

package/Toml.js

@@ -244,6 +244,9 @@ var Toml = class Toml {
 	*
 	* Schema-producing: bind the result to a `const` on hot paths (see
 	* {@link Toml.fromString}).
+	*
+	* @param target - The domain schema decoded values must satisfy.
+	* @returns A `Schema.Codec<T, string>` decoding TOML text straight into `T`.
 	*/
 	static schema(target) {
 		return Toml.TomlFromString.pipe(Schema.decodeTo(target));

package/TomlDiagnostic.js

@@ -61,8 +61,12 @@ var TomlDiagnostic = class TomlDiagnostic extends Schema.Class("TomlDiagnostic")
 }) {
 	/**
 	* Materialize an engine record, deriving `line`/`character` (0-based)
-	* from `offset` against the source `text`. Advanced — the parse/stringify
+	* from `offset` against the source text. Advanced — the parse/stringify
 	* entry points call this for you.
+	*
+	* @param source - The source text the record's `offset` indexes into.
+	* @param raw - The engine record: `code`, `message`, `offset` and `length`.
+	* @returns The diagnostic with `line` and `character` filled in.
 	*/
 	static fromRaw(source, raw) {
 		const { line, character } = lineChar(source, raw.offset);

package/TomlDocument.js

@@ -68,6 +68,10 @@ var TomlDocument = class TomlDocument extends Schema.Class("TomlDocument")({
 	* diagnostic, never an unhandled defect. Semantic violations do not fail:
 	* they land in `diagnostics` as data (first violation wins, so there is at
 	* most one today; the array shape is the contract).
+	*
+	* @param text - The TOML source to parse.
+	* @returns An `Effect` that succeeds with the {@link TomlDocument}, or fails
+	*   with {@link TomlParseError}.
 	*/
 	static parse = Effect.fn("TomlDocument.parse")(function* (text) {
 		const expressions = yield* Effect.try({

package/TomlEdit.js

@@ -17,9 +17,9 @@ var TomlRange = class extends Schema.Class("TomlRange")({
 * `content`. Set `length` to `0` to insert, `content` to `""` to delete.
 *
 * @remarks
-* Structurally identical to `@effected/jsonc`'s and `@effected/yaml`'s edit
-* shapes (same field names, types and semantics) per the jsonc/yaml parity
-* convention, so consumer code can be written once over "a document codec's
+* Structurally identical to the edit shapes of `@effected/jsonc`,
+* `@effected/yaml` and `@effected/markdown` (same field names, types and
+* semantics), so consumer code can be written once over "a document codec's
 * Edit/Range/Path".
 *
 * @public
@@ -34,6 +34,10 @@ var TomlEdit = class extends Schema.Class("TomlEdit")({
 	* reverse-offset order so earlier offsets stay valid; the input `edits`
 	* array is not mutated. Overlapping edits are a programmer error and throw
 	* as a defect — `TomlFormat` never produces them.
+	*
+	* @param text - The source text to edit.
+	* @param edits - The edits to apply, in any order.
+	* @returns The edited text.
 	*/
 	static applyAll(text, edits) {
 		const sorted = [...edits].sort((a, b) => b.offset - a.offset);

package/TomlFormat.js

@@ -508,7 +508,22 @@ const terminal = (cur, segment, value, ctx) => {
 	return failResolve("DottedKeyConflict", "cannot address a key beneath a scalar value", node.offset, node.length);
 };
 /**
-* Formatting and modification statics. Not instantiable.
+* Formats TOML text and modifies values at a path as byte-minimal edits that
+* leave comments and layout elsewhere untouched. Not instantiable.
+*
+* @example
+* ```ts
+* import { TomlFormat } from "@effected/toml";
+* import { Effect } from "effect";
+*
+* const formatted = TomlFormat.formatToString('  title="x"   #note\n[server]\nport=1');
+* // => 'title = "x" # note\n[server]\nport = 1\n'
+*
+* const program = Effect.gen(function* () {
+*   return yield* TomlFormat.modifyToString("[server]\nport = 1 # dev\n", ["server", "port"], 2);
+*   // => "[server]\nport = 2 # dev\n"
+* });
+* ```
 *
 * @remarks
 * `format`/`formatToString` are pure and total: malformed input yields no
@@ -532,7 +547,14 @@ var TomlFormat = class TomlFormat {
 	* strings. Nothing else: no reordering, no blank-line collapsing, no value
 	* rewriting. `range` restricts edits to the expressions intersecting it.
 	* Non-mutating — apply with `TomlEdit.applyAll` (or use
-	* {@link TomlFormat.formatToString}).
+	* {@link TomlFormat.formatToString}). Pure and total.
+	*
+	* @param text - The TOML source to format.
+	* @param range - Optional sub-range; only edits whose expression intersects
+	*   it are returned.
+	* @param options - Optional {@link TomlFormattingOptions}.
+	* @returns The edits that bring `text` (or `range`) to canonical shape;
+	*   apply them with `TomlEdit.applyAll`.
 	*/
 	static format(text, range, options) {
 		const tagged = computeFormatEdits(text, options);
@@ -545,6 +567,12 @@ var TomlFormat = class TomlFormat {
 	/**
 	* Format `text` and apply the resulting edits in one step
 	* (`TomlEdit.applyAll ∘ format`). Pure and total.
+	*
+	* @param text - The TOML source to format.
+	* @param range - Optional sub-range; only edits whose expression intersects
+	*   it are applied.
+	* @param options - Optional {@link TomlFormattingOptions}.
+	* @returns The formatted text.
 	*/
 	static formatToString(text, range, options) {
 		return TomlEdit.applyAll(text, TomlFormat.format(text, range, options));
@@ -561,6 +589,17 @@ var TomlFormat = class TomlFormat {
 	* section; inline and implicitly created tables refuse. Inserted lines
 	* inherit the document's dominant newline unless `options.newline`
 	* overrides it. Every modified document reparses cleanly.
+	*
+	* @param text - The TOML source to modify.
+	* @param path - The location to set, replace or delete.
+	* @param value - The plain JavaScript value to write; `undefined` deletes the
+	*   target instead.
+	* @param options - Optional {@link TomlFormattingOptions}; `newline` overrides
+	*   the newline used for inserted lines.
+	* @returns An `Effect` that succeeds with the edits to apply (via
+	*   `TomlEdit.applyAll`), or fails with {@link TomlParseError} when the
+	*   source does not parse, or {@link TomlModificationError} when `path`
+	*   cannot be resolved or the insertion target is not allowed.
 	*/
 	static modify = Effect.fn("TomlFormat.modify")(function* (text, path, value, options) {
 		const failWith = (code, message, offset = 0, length = 0) => new TomlModificationError({ diagnostic: TomlDiagnostic.fromRaw(text, {
@@ -602,6 +641,15 @@ var TomlFormat = class TomlFormat {
 	/**
 	* Modify `text` and apply the resulting edits in one step
 	* (`TomlEdit.applyAll ∘ modify`).
+	*
+	* @param text - The TOML source to modify.
+	* @param path - The location to set, replace or delete.
+	* @param value - The plain JavaScript value to write; `undefined` deletes the
+	*   target instead.
+	* @param options - Optional {@link TomlFormattingOptions}.
+	* @returns An `Effect` that succeeds with the modified text, or fails with
+	*   {@link TomlParseError} or {@link TomlModificationError}, as
+	*   {@link TomlFormat.modify} does.
 	*/
 	static modifyToString = Effect.fn("TomlFormat.modifyToString")(function* (text, path, value, options) {
 		const edits = yield* TomlFormat.modify(text, path, value, options);

package/TomlVisitor.js

@@ -125,7 +125,21 @@ const collectEventsOrFail = (text) => Effect.try({
 	}
 });
 /**
-* SAX-style TOML visitor statics. Not instantiable.
+* Walks TOML text as a `Stream` of table, array-table, key-value and comment
+* events in document order, without building a value. Not instantiable.
+*
+* @example
+* ```ts
+* import { TomlVisitor, TomlVisitorEvent } from "@effected/toml";
+* import { Effect, Stream } from "effect";
+*
+* const keys = TomlVisitor.visit("[server]\nport = 1\n").pipe(
+*   Stream.filter(TomlVisitorEvent.$is("KeyValue")),
+*   Stream.map((event) => event.path.join(".")),
+*   Stream.runCollect,
+* );
+* // Effect.runSync(keys) // => ["server.port"]
+* ```
 *
 * @public
 */

package/index.d.ts

@@ -85,8 +85,12 @@ declare const TomlDiagnostic_base: Schema.Class<TomlDiagnostic, Schema.Struct<{
 export declare class TomlDiagnostic extends TomlDiagnostic_base {
   /**
    * Materialize an engine record, deriving `line`/`character` (0-based)
-   * from `offset` against the source `text`. Advanced — the parse/stringify
+   * from `offset` against the source text. Advanced — the parse/stringify
    * entry points call this for you.
+   *
+   * @param source - The source text the record's `offset` indexes into.
+   * @param raw - The engine record: `code`, `message`, `offset` and `length`.
+   * @returns The diagnostic with `line` and `character` filled in.
    */
   static fromRaw(source: string, raw: {
     readonly code: TomlErrorCode;
@@ -307,6 +311,9 @@ export declare class Toml {
    *
    * Schema-producing: bind the result to a `const` on hot paths (see
    * {@link Toml.fromString}).
+   *
+   * @param target - The domain schema decoded values must satisfy.
+   * @returns A `Schema.Codec<T, string>` decoding TOML text straight into `T`.
    */
   static schema<T, E, RD = never, RE = never>(target: Schema.Codec<T, E, RD, RE>): Schema.Codec<T, string, RD, RE>;
   /**
@@ -680,6 +687,10 @@ export declare class TomlDocument extends TomlDocument_base {
    * diagnostic, never an unhandled defect. Semantic violations do not fail:
    * they land in `diagnostics` as data (first violation wins, so there is at
    * most one today; the array shape is the contract).
+   *
+   * @param text - The TOML source to parse.
+   * @returns An `Effect` that succeeds with the {@link TomlDocument}, or fails
+   *   with {@link TomlParseError}.
    */
   static readonly parse: (text: string) => Effect.Effect<TomlDocument, TomlParseError, never>;
   /**
@@ -746,9 +757,9 @@ declare const TomlEdit_base: Schema.Class<TomlEdit, Schema.Struct<{
  * `content`. Set `length` to `0` to insert, `content` to `""` to delete.
  *
  * @remarks
- * Structurally identical to `@effected/jsonc`'s and `@effected/yaml`'s edit
- * shapes (same field names, types and semantics) per the jsonc/yaml parity
- * convention, so consumer code can be written once over "a document codec's
+ * Structurally identical to the edit shapes of `@effected/jsonc`,
+ * `@effected/yaml` and `@effected/markdown` (same field names, types and
+ * semantics), so consumer code can be written once over "a document codec's
  * Edit/Range/Path".
  *
  * @public
@@ -759,6 +770,10 @@ export declare class TomlEdit extends TomlEdit_base {
    * reverse-offset order so earlier offsets stay valid; the input `edits`
    * array is not mutated. Overlapping edits are a programmer error and throw
    * as a defect — `TomlFormat` never produces them.
+   *
+   * @param text - The source text to edit.
+   * @param edits - The edits to apply, in any order.
+   * @returns The edited text.
    */
   static applyAll(text: string, edits: ReadonlyArray<TomlEdit>): string;
 }
@@ -803,7 +818,22 @@ export declare class TomlModificationError extends TomlModificationError_base {
   get message(): string;
 }
 /**
- * Formatting and modification statics. Not instantiable.
+ * Formats TOML text and modifies values at a path as byte-minimal edits that
+ * leave comments and layout elsewhere untouched. Not instantiable.
+ *
+ * @example
+ * ```ts
+ * import { TomlFormat } from "@effected/toml";
+ * import { Effect } from "effect";
+ *
+ * const formatted = TomlFormat.formatToString('  title="x"   #note\n[server]\nport=1');
+ * // => 'title = "x" # note\n[server]\nport = 1\n'
+ *
+ * const program = Effect.gen(function* () {
+ *   return yield* TomlFormat.modifyToString("[server]\nport = 1 # dev\n", ["server", "port"], 2);
+ *   // => "[server]\nport = 2 # dev\n"
+ * });
+ * ```
  *
  * @remarks
  * `format`/`formatToString` are pure and total: malformed input yields no
@@ -827,12 +857,25 @@ export declare class TomlFormat {
    * strings. Nothing else: no reordering, no blank-line collapsing, no value
    * rewriting. `range` restricts edits to the expressions intersecting it.
    * Non-mutating — apply with `TomlEdit.applyAll` (or use
-   * {@link TomlFormat.formatToString}).
+   * {@link TomlFormat.formatToString}). Pure and total.
+   *
+   * @param text - The TOML source to format.
+   * @param range - Optional sub-range; only edits whose expression intersects
+   *   it are returned.
+   * @param options - Optional {@link TomlFormattingOptions}.
+   * @returns The edits that bring `text` (or `range`) to canonical shape;
+   *   apply them with `TomlEdit.applyAll`.
    */
   static format(text: string, range?: TomlRangeLike, options?: TomlFormattingOptions): ReadonlyArray<TomlEdit>;
   /**
    * Format `text` and apply the resulting edits in one step
    * (`TomlEdit.applyAll ∘ format`). Pure and total.
+   *
+   * @param text - The TOML source to format.
+   * @param range - Optional sub-range; only edits whose expression intersects
+   *   it are applied.
+   * @param options - Optional {@link TomlFormattingOptions}.
+   * @returns The formatted text.
    */
   static formatToString(text: string, range?: TomlRangeLike, options?: TomlFormattingOptions): string;
   /**
@@ -847,11 +890,31 @@ export declare class TomlFormat {
    * section; inline and implicitly created tables refuse. Inserted lines
    * inherit the document's dominant newline unless `options.newline`
    * overrides it. Every modified document reparses cleanly.
+   *
+   * @param text - The TOML source to modify.
+   * @param path - The location to set, replace or delete.
+   * @param value - The plain JavaScript value to write; `undefined` deletes the
+   *   target instead.
+   * @param options - Optional {@link TomlFormattingOptions}; `newline` overrides
+   *   the newline used for inserted lines.
+   * @returns An `Effect` that succeeds with the edits to apply (via
+   *   `TomlEdit.applyAll`), or fails with {@link TomlParseError} when the
+   *   source does not parse, or {@link TomlModificationError} when `path`
+   *   cannot be resolved or the insertion target is not allowed.
    */
   static readonly modify: (text: string, path: TomlPath, value: unknown, options?: TomlFormattingOptions | undefined) => Effect.Effect<readonly TomlEdit[], TomlModificationError | TomlParseError, never>;
   /**
    * Modify `text` and apply the resulting edits in one step
    * (`TomlEdit.applyAll ∘ modify`).
+   *
+   * @param text - The TOML source to modify.
+   * @param path - The location to set, replace or delete.
+   * @param value - The plain JavaScript value to write; `undefined` deletes the
+   *   target instead.
+   * @param options - Optional {@link TomlFormattingOptions}.
+   * @returns An `Effect` that succeeds with the modified text, or fails with
+   *   {@link TomlParseError} or {@link TomlModificationError}, as
+   *   {@link TomlFormat.modify} does.
    */
   static readonly modifyToString: (text: string, path: TomlPath, value: unknown, options?: TomlFormattingOptions | undefined) => Effect.Effect<string, TomlModificationError | TomlParseError, never>;
 }
@@ -863,7 +926,9 @@ export declare class TomlFormat {
  * event, then again for every `[table]` header. `ArrayTableStart` fires for
  * every `[[array]]` header with the 0-based element `index`. `KeyValue.path`
  * includes the final key. `Comment` covers both standalone (trivia) and
- * trailing comments — see the module remarks for `offset`'s exact meaning.
+ * trailing comments: `offset` is the source position of the comment's `#`
+ * marker, and `text` is the comment after the `#` with one leading space
+ * removed.
  *
  * @public
  */
@@ -1010,7 +1075,21 @@ export declare const TomlVisitorEvent: {
   }, "_tag">;
 };
 /**
- * SAX-style TOML visitor statics. Not instantiable.
+ * Walks TOML text as a `Stream` of table, array-table, key-value and comment
+ * events in document order, without building a value. Not instantiable.
+ *
+ * @example
+ * ```ts
+ * import { TomlVisitor, TomlVisitorEvent } from "@effected/toml";
+ * import { Effect, Stream } from "effect";
+ *
+ * const keys = TomlVisitor.visit("[server]\nport = 1\n").pipe(
+ *   Stream.filter(TomlVisitorEvent.$is("KeyValue")),
+ *   Stream.map((event) => event.path.join(".")),
+ *   Stream.runCollect,
+ * );
+ * // Effect.runSync(keys) // => ["server.port"]
+ * ```
  *
  * @public
  */

package/internal/parser.js

@@ -363,7 +363,7 @@ const parseHeaderExpression = (source, lineStart, bracketPos) => {
 /**
 * Parse a TOML document into its linear CST: the flat, source-tiling list of
 * expressions. Throws RawTomlError on malformed input and GuardExceeded when
-* value nesting exceeds MAX_NESTING_DEPTH; the facade (Task 7) materializes
+* value nesting exceeds MAX_NESTING_DEPTH; the facade materializes
 * both into typed errors.
 */
 const parseExpressions = (source) => {

package/internal/scanner.js

@@ -339,7 +339,7 @@ const LOCAL_DATE = /^([0-9]{4})-([0-9]{2})-([0-9]{2})$/;
 const LOCAL_TIME = /^([0-9]{2}):([0-9]{2})(?::([0-9]{2})(?:\.([0-9]+))?)?$/;
 /**
 * Scan a non-string scalar value token. Stops at whitespace, newlines, `,`,
-* `]`, `}` and `#` — with the G5 extension: a token that scanned as a full
+* `]`, `}` and `#` — with one extension: a token that scanned as a full
 * date followed by a single space and a digit continues through the time
 * part, so `1979-05-27 07:32:00Z` is one token.
 */
@@ -412,7 +412,7 @@ const decodeOffsetMinutes = (text, offset, length) => {
 	return text.charCodeAt(0) === HYPHEN ? -total : total;
 };
 /**
-* Classify a scanned value token per G4-G6: booleans, the four datetime
+* Classify a scanned value token: booleans, the four datetime
 * shapes (validated against the Gregorian calendar and clock ranges before
 * construction), integers across four radixes with int64 range checking and
 * number/bigint narrowing, and floats including the special spellings.

package/internal/semantic.js

@@ -17,7 +17,7 @@ const raise = (code, message, key) => {
 	});
 };
 /**
-* Header navigation (G8 rules 1 and 2, shared prefix): walk every segment but
+* Header navigation (rules 1 and 2, shared prefix): walk every segment but
 * the last, creating `table-implicit` for absent names, passing through
 * tables (dotted included — the corpus deviation) and descending into the
 * last element of an array of tables.
@@ -49,7 +49,7 @@ const navigateHeaderPrefix = (root, keyPath) => {
 	}
 	return current;
 };
-/** G8 rule 1, final segment: create `table-explicit`, promote `table-implicit`, or error. */
+/** Rule 1, final segment: create `table-explicit`, promote `table-implicit`, or error. */
 const openTable = (root, keyPath) => {
 	const parent = navigateHeaderPrefix(root, keyPath);
 	const key = keyPath[keyPath.length - 1];
@@ -65,7 +65,7 @@ const openTable = (root, keyPath) => {
 	}
 	return raise("TableRedefined", `table "${key.value}" is already defined`, key);
 };
-/** G8 rule 2, final segment: create the array and its first element, append to an existing one, or error. */
+/** Rule 2, final segment: create the array and its first element, append to an existing one, or error. */
 const openArrayTable = (root, keyPath) => {
 	const parent = navigateHeaderPrefix(root, keyPath);
 	const key = keyPath[keyPath.length - 1];
@@ -91,7 +91,7 @@ const openArrayTable = (root, keyPath) => {
 	return raise("ArrayOfTablesConflict", `"${key.value}" cannot be redefined as an array of tables`, key);
 };
 /**
-* G8 rule 3: a (possibly dotted) key assignment scoped to `table` under
+* Rule 3: a (possibly dotted) key assignment scoped to `table` under
 * `sectionId`. Intermediates must be absent (create `table-dotted`) or
 * `table-dotted` from the same section; the final key must be absent.
 */
@@ -135,7 +135,7 @@ const checkArrayItem = (item, context) => {
 	if (item instanceof TomlArray) for (const inner of item.items) checkArrayItem(inner, context);
 };
 /**
-* G8 rule 4: build an inline table's own scope (dotted keys follow rule 3
+* Rule 4: build an inline table's own scope (dotted keys follow rule 3
 * inside it), then freeze it — the returned node's `inline` kind makes every
 * later navigation through it an `InlineTableExtended` error.
 */
@@ -147,7 +147,7 @@ const inlineNode = (node, context) => {
 	return sem;
 };
 /**
-* Walk the expressions through the G8 state machine, firing the visitor after
+* Walk the expressions through the provenance state machine, firing the visitor after
 * each expression validates; throws `RawTomlError` at the first violation.
 */
 const analyze = (expressions, visitor) => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/toml",
-	"version": "0.9.0",
+	"version": "0.11.0",
 	"private": false,
 	"description": "TOML 1.1.0 parsing, editing and formatting as Effect schemas: typed diagnostics, a lossless CST and first-class date-time values.",
 	"keywords": [
@@ -38,7 +38,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"effect": "4.0.0-rc.117"
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"