@effected/toml 0.15.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/Toml.js +34 -28
  2. package/TomlDocument.js +84 -43
  3. package/TomlFormat.js +76 -22
  4. package/TomlVisitor.js +8 -19
  5. package/index.d.ts +113 -5
  6. package/package.json +1 -1
package/Toml.js CHANGED
@@ -58,41 +58,47 @@ var TomlStringifyError = class extends Schema.TaggedError()("TomlStringifyError"
58
58
  }
59
59
  };
60
60
  /**
61
- * Run the parser and semantic pass, materializing the engine's raw carriers
62
- * into the typed error: `RawTomlError` becomes a positioned diagnostic and a
63
- * `GuardExceeded` depth trip becomes a `NestingDepthExceeded` diagnostic
64
- * (never an unhandled defect). Anything else is a genuine defect and rethrows
65
- * — synchronously to a `Result` caller, and as a `Die` through the `Effect`
66
- * forms, which evaluate this inside the effect.
61
+ * Materialize an engine throw into the typed {@link TomlParseError}:
62
+ * `RawTomlError` becomes a positioned diagnostic and a `GuardExceeded` depth
63
+ * trip becomes a `NestingDepthExceeded` diagnostic (never an unhandled
64
+ * defect). Anything else is a genuine defect and rethrows — synchronously to a
65
+ * `Result` caller, and as a `Die` through the `Effect` forms, which evaluate
66
+ * it inside the effect.
67
+ *
68
+ * The one mapping shared by every parse path — `Toml.parse`/`parseResult`,
69
+ * `TomlDocument.parseResult`/`toValueResult` and `TomlVisitor.visit` — so a
70
+ * given input fails identically through each of them.
71
+ *
72
+ * @internal
67
73
  */
68
- const parseToResult = (text) => {
69
- try {
70
- return Result.succeed(buildValue(parseExpressions(text)));
71
- } catch (defect) {
72
- if (isRawTomlError(defect)) return Result.fail(new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, defect.diagnostic)] }));
73
- if (isGuardExceeded(defect)) return Result.fail(new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, {
74
- code: "NestingDepthExceeded",
75
- message: defect.message,
76
- offset: defect.offset,
77
- length: 0
78
- })] }));
79
- throw defect;
80
- }
74
+ const toTomlParseError = (text, defect) => {
75
+ if (isRawTomlError(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, defect.diagnostic)] });
76
+ if (isGuardExceeded(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, {
77
+ code: "NestingDepthExceeded",
78
+ message: defect.message,
79
+ offset: defect.offset,
80
+ length: 0
81
+ })] });
82
+ throw defect;
81
83
  };
82
- const stringifyToResult = (value, options) => {
83
- try {
84
- return Result.succeed(stringifyValue(value, options?.newline ?? "\n"));
85
- } catch (defect) {
86
- if (isRawTomlError(defect)) return Result.fail(new TomlStringifyError({ diagnostic: TomlDiagnostic.fromRaw("", defect.diagnostic) }));
87
- if (isGuardExceeded(defect)) return Result.fail(new TomlStringifyError({ diagnostic: TomlDiagnostic.fromRaw("", {
84
+ /** Run the parser and semantic pass, materializing failures via {@link toTomlParseError}. */
85
+ const parseToResult = (text) => Result.try({
86
+ try: () => buildValue(parseExpressions(text)),
87
+ catch: (defect) => toTomlParseError(text, defect)
88
+ });
89
+ const stringifyToResult = (value, options) => Result.try({
90
+ try: () => stringifyValue(value, options?.newline ?? "\n"),
91
+ catch: (defect) => {
92
+ if (isRawTomlError(defect)) return new TomlStringifyError({ diagnostic: TomlDiagnostic.fromRaw("", defect.diagnostic) });
93
+ if (isGuardExceeded(defect)) return new TomlStringifyError({ diagnostic: TomlDiagnostic.fromRaw("", {
88
94
  code: "NestingDepthExceeded",
89
95
  message: defect.message,
90
96
  offset: 0,
91
97
  length: 0
92
- }) }));
98
+ }) });
93
99
  throw defect;
94
100
  }
95
- };
101
+ });
96
102
  /**
97
103
  * Static entry points for TOML parsing, stringification and the schema
98
104
  * factories. Not instantiable.
@@ -303,4 +309,4 @@ var Toml = class Toml {
303
309
  }
304
310
  };
305
311
 
306
- export { Toml, TomlParseError, TomlStringifyError, TomlStringifyOptions };
312
+ export { Toml, TomlParseError, TomlStringifyError, TomlStringifyOptions, toTomlParseError };
package/TomlDocument.js CHANGED
@@ -1,30 +1,13 @@
1
1
  import { isRawTomlError } from "./internal/diagnostics.js";
2
- import { isGuardExceeded } from "./internal/limits.js";
3
2
  import { TomlExpression } from "./TomlNode.js";
4
3
  import { parseExpressions } from "./internal/parser.js";
5
4
  import { analyze, buildValue } from "./internal/semantic.js";
6
5
  import { TomlDiagnostic } from "./TomlDiagnostic.js";
7
- import { TomlParseError } from "./Toml.js";
8
- import { Effect, Schema, SchemaIssue, SchemaTransformation } from "effect";
6
+ import { TomlParseError, toTomlParseError } from "./Toml.js";
7
+ import { Effect, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
9
8
 
10
9
  // src/TomlDocument.ts
11
10
  /**
12
- * Materialize an engine throw into the typed error: `RawTomlError` becomes a
13
- * positioned diagnostic and a `GuardExceeded` depth trip becomes a
14
- * `NestingDepthExceeded` diagnostic. Anything else is a genuine defect and
15
- * rethrows.
16
- */
17
- const materializeError = (text, defect) => {
18
- if (isRawTomlError(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, defect.diagnostic)] });
19
- if (isGuardExceeded(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, {
20
- code: "NestingDepthExceeded",
21
- message: defect.message,
22
- offset: defect.offset,
23
- length: 0
24
- })] });
25
- throw defect;
26
- };
27
- /**
28
11
  * A parsed TOML document that never loses a byte: the `source` text, the
29
12
  * linear {@link (TomlExpression:type)} CST whose spans tile the source
30
13
  * exactly, and
@@ -61,36 +44,64 @@ var TomlDocument = class TomlDocument extends Schema.Class("TomlDocument")({
61
44
  expressions: Schema.Array(TomlExpression),
62
45
  diagnostics: Schema.Array(TomlDiagnostic)
63
46
  }) {
47
+ /**
48
+ * Synchronous {@link TomlDocument.parse}, returning a `Result` instead of
49
+ * an `Effect` — the primitive `parse` is defined in terms of, so a
50
+ * synchronous host can call it without an Effect runtime. Fails with
51
+ * {@link TomlParseError} only on lex/parse errors — including a
52
+ * nesting-depth bomb, which surfaces as a `NestingDepthExceeded`
53
+ * diagnostic, never a throw. Semantic violations do not fail: they land in
54
+ * `diagnostics` as data (first violation wins, so there is at most one
55
+ * today; the array shape is the contract).
56
+ *
57
+ * @example
58
+ * ```ts
59
+ * import { TomlDocument } from "@effected/toml";
60
+ * import { Result } from "effect";
61
+ *
62
+ * const result = TomlDocument.parseResult('name = "Alice"\n');
63
+ * if (Result.isSuccess(result)) {
64
+ * console.log(result.success.stringify()); // => 'name = "Alice"\n'
65
+ * }
66
+ * ```
67
+ *
68
+ * @param text - The TOML source to parse.
69
+ * @returns A `Result` succeeding with the {@link TomlDocument}, or failing
70
+ * with {@link TomlParseError}.
71
+ */
72
+ static parseResult(text) {
73
+ return Result.map(Result.try({
74
+ try: () => parseExpressions(text),
75
+ catch: (defect) => toTomlParseError(text, defect)
76
+ }), (expressions) => {
77
+ const diagnostics = [];
78
+ try {
79
+ analyze(expressions);
80
+ } catch (defect) {
81
+ if (!isRawTomlError(defect)) throw defect;
82
+ diagnostics.push(TomlDiagnostic.fromRaw(text, defect.diagnostic));
83
+ }
84
+ return TomlDocument.make({
85
+ source: text,
86
+ expressions,
87
+ diagnostics
88
+ });
89
+ });
90
+ }
64
91
  /**
65
92
  * Parse TOML text into a lossless document. Fails with
66
93
  * {@link TomlParseError} only on lex/parse errors — including a
67
94
  * nesting-depth bomb, which surfaces as a `NestingDepthExceeded`
68
95
  * diagnostic, never an unhandled defect. Semantic violations do not fail:
69
- * they land in `diagnostics` as data (first violation wins, so there is at
70
- * most one today; the array shape is the contract).
96
+ * they land in `diagnostics` as data. Defined in terms of
97
+ * {@link TomlDocument.parseResult} — synchronous callers can use that
98
+ * variant directly.
71
99
  *
72
100
  * @param text - The TOML source to parse.
73
101
  * @returns An `Effect` that succeeds with the {@link TomlDocument}, or fails
74
102
  * with {@link TomlParseError}.
75
103
  */
76
- static parse = Effect.fn("TomlDocument.parse")(function* (text) {
77
- const expressions = yield* Effect.try({
78
- try: () => parseExpressions(text),
79
- catch: (defect) => materializeError(text, defect)
80
- });
81
- const diagnostics = [];
82
- try {
83
- analyze(expressions);
84
- } catch (defect) {
85
- if (!isRawTomlError(defect)) throw defect;
86
- diagnostics.push(TomlDiagnostic.fromRaw(text, defect.diagnostic));
87
- }
88
- return TomlDocument.make({
89
- source: text,
90
- expressions,
91
- diagnostics
92
- });
93
- });
104
+ static parse = Effect.fn("TomlDocument.parse")((text) => Effect.fromResult(TomlDocument.parseResult(text)));
94
105
  /**
95
106
  * A `Schema<TomlDocument, string>` decoding TOML text into a full document
96
107
  * (source, expressions, diagnostics) and encoding a document back to its
@@ -111,13 +122,43 @@ var TomlDocument = class TomlDocument extends Schema.Class("TomlDocument")({
111
122
  * {@link TomlParseError} carrying the stored `diagnostics` when the parse
112
123
  * recorded semantic violations; otherwise builds the value from the
113
124
  * expression list (already validated, so the defensive materialization
114
- * wrapper is belt-and-suspenders).
125
+ * wrapper is belt-and-suspenders). Defined in terms of
126
+ * {@link TomlDocument.toValueResult} — synchronous callers can use that
127
+ * variant directly.
128
+ *
129
+ * @returns An `Effect` that succeeds with the plain value, or fails with
130
+ * {@link TomlParseError}.
115
131
  */
116
132
  toValue() {
117
- if (this.diagnostics.length > 0) return Effect.fail(new TomlParseError({ diagnostics: this.diagnostics }));
118
- return Effect.try({
133
+ return Effect.suspend(() => Effect.fromResult(this.toValueResult()));
134
+ }
135
+ /**
136
+ * Synchronous {@link TomlDocument.toValue}, returning a `Result` — the
137
+ * second half of a synchronous document round-trip that starts at
138
+ * {@link TomlDocument.parseResult}. Fails with {@link TomlParseError}
139
+ * carrying the stored `diagnostics` when the parse recorded semantic
140
+ * violations.
141
+ *
142
+ * @example
143
+ * ```ts
144
+ * import { TomlDocument } from "@effected/toml";
145
+ * import { Result } from "effect";
146
+ *
147
+ * const parsed = TomlDocument.parseResult("a = 1\na = 2\n");
148
+ * if (Result.isSuccess(parsed)) {
149
+ * const value = parsed.success.toValueResult();
150
+ * console.log(Result.isFailure(value)); // => true — DuplicateKey
151
+ * }
152
+ * ```
153
+ *
154
+ * @returns A `Result` succeeding with the plain value, or failing with
155
+ * {@link TomlParseError}.
156
+ */
157
+ toValueResult() {
158
+ if (this.diagnostics.length > 0) return Result.fail(new TomlParseError({ diagnostics: this.diagnostics }));
159
+ return Result.try({
119
160
  try: () => buildValue(this.expressions),
120
- catch: (defect) => materializeError(this.source, defect)
161
+ catch: (defect) => toTomlParseError(this.source, defect)
121
162
  });
122
163
  }
123
164
  /**
package/TomlFormat.js CHANGED
@@ -7,7 +7,7 @@ import { renderInlineValue, renderKey } from "./internal/stringifyValue.js";
7
7
  import { TomlDiagnostic } from "./TomlDiagnostic.js";
8
8
  import { TomlDocument } from "./TomlDocument.js";
9
9
  import { TomlEdit } from "./TomlEdit.js";
10
- import { Effect, Schema } from "effect";
10
+ import { Effect, Result, Schema } from "effect";
11
11
 
12
12
  // src/TomlFormat.ts
13
13
  /**
@@ -579,7 +579,9 @@ var TomlFormat = class TomlFormat {
579
579
  }
580
580
  /**
581
581
  * Compute the edits that replace, delete, or insert a value at `path`,
582
- * resolved through the document's semantic view. Every segment but the
582
+ * synchronously — the primitive {@link TomlFormat.modify} is defined in
583
+ * terms of, so a synchronous host can call it without an Effect runtime.
584
+ * Paths resolve through the document's semantic view. Every segment but the
583
585
  * last must resolve — intermediate tables are never auto-created. A
584
586
  * `value` of `undefined` deletes: a key-value's whole line, an inline
585
587
  * entry, or an array item, splicing separators. A new key inserts per the
@@ -596,22 +598,24 @@ var TomlFormat = class TomlFormat {
596
598
  * target instead.
597
599
  * @param options - Optional {@link TomlFormattingOptions}; `newline` overrides
598
600
  * the newline used for inserted lines.
599
- * @returns An `Effect` that succeeds with the edits to apply (via
600
- * `TomlEdit.applyAll`), or fails with {@link TomlParseError} when the
601
+ * @returns A `Result` succeeding with the edits to apply (via
602
+ * `TomlEdit.applyAll`), or failing with {@link TomlParseError} when the
601
603
  * source does not parse, or {@link TomlModificationError} when `path`
602
604
  * cannot be resolved or the insertion target is not allowed.
603
605
  */
604
- static modify = Effect.fn("TomlFormat.modify")(function* (text, path, value, options) {
605
- const failWith = (code, message, offset = 0, length = 0) => new TomlModificationError({ diagnostic: TomlDiagnostic.fromRaw(text, {
606
+ static modifyResult(text, path, value, options) {
607
+ const failWith = (code, message, offset = 0, length = 0) => Result.fail(new TomlModificationError({ diagnostic: TomlDiagnostic.fromRaw(text, {
606
608
  code,
607
609
  message,
608
610
  offset,
609
611
  length
610
- }) });
611
- if (path.length === 0) return yield* failWith("DottedKeyConflict", "an empty path does not address a value");
612
- if (path.length > 256) return yield* failWith("NestingDepthExceeded", `path depth ${path.length} exceeds the ${256} cap`);
613
- const doc = yield* TomlDocument.parse(text);
614
- if (doc.diagnostics.length > 0) return yield* new TomlModificationError({ diagnostic: doc.diagnostics[0] });
612
+ }) }));
613
+ if (path.length === 0) return failWith("DottedKeyConflict", "an empty path does not address a value");
614
+ if (path.length > 256) return failWith("NestingDepthExceeded", `path depth ${path.length} exceeds the ${256} cap`);
615
+ const parsed = TomlDocument.parseResult(text);
616
+ if (Result.isFailure(parsed)) return Result.fail(parsed.failure);
617
+ const doc = parsed.success;
618
+ if (doc.diagnostics.length > 0) return Result.fail(new TomlModificationError({ diagnostic: doc.diagnostics[0] }));
615
619
  const { root, sections } = buildSemanticIndex(doc.expressions);
616
620
  const ctx = {
617
621
  source: text,
@@ -627,20 +631,73 @@ var TomlFormat = class TomlFormat {
627
631
  for (let i = 0; i < path.length - 1; i++) cursor = step(cursor, path[i]);
628
632
  raw = terminal(cursor, path[path.length - 1], value, ctx);
629
633
  } catch (defect) {
630
- if (defect instanceof ModifyFailure) return yield* failWith(defect.code, defect.message, defect.offset, defect.len);
631
- if (isRawTomlError(defect)) return yield* new TomlModificationError({ diagnostic: TomlDiagnostic.fromRaw(text, defect.diagnostic) });
632
- if (isGuardExceeded(defect)) return yield* failWith("NestingDepthExceeded", defect.message, defect.offset);
634
+ if (defect instanceof ModifyFailure) return failWith(defect.code, defect.message, defect.offset, defect.len);
635
+ if (isRawTomlError(defect)) return Result.fail(new TomlModificationError({ diagnostic: TomlDiagnostic.fromRaw(text, defect.diagnostic) }));
636
+ if (isGuardExceeded(defect)) return failWith("NestingDepthExceeded", defect.message, defect.offset);
633
637
  throw defect;
634
638
  }
635
- return raw.map((edit) => TomlEdit.make({
639
+ return Result.succeed(raw.map((edit) => TomlEdit.make({
636
640
  offset: edit.offset,
637
641
  length: edit.length,
638
642
  content: edit.newText
639
- }));
640
- });
643
+ })));
644
+ }
645
+ /**
646
+ * Compute the edits that replace, delete, or insert a value at `path`.
647
+ * Defined in terms of {@link TomlFormat.modifyResult}, which carries the
648
+ * full contract — semantic path resolution, deletion splicing and the
649
+ * pinned insertion placement rules — behind a `TomlFormat.modify` span;
650
+ * synchronous callers can use that variant directly.
651
+ *
652
+ * @param text - The TOML source to modify.
653
+ * @param path - The location to set, replace or delete.
654
+ * @param value - The plain JavaScript value to write; `undefined` deletes the
655
+ * target instead.
656
+ * @param options - Optional {@link TomlFormattingOptions}; `newline` overrides
657
+ * the newline used for inserted lines.
658
+ * @returns An `Effect` that succeeds with the edits to apply (via
659
+ * `TomlEdit.applyAll`), or fails with {@link TomlParseError} when the
660
+ * source does not parse, or {@link TomlModificationError} when `path`
661
+ * cannot be resolved or the insertion target is not allowed.
662
+ *
663
+ * @remarks
664
+ * The source is parsed through `TomlDocument.parseResult`, so this span no
665
+ * longer opens a nested `TomlDocument.parse` child span.
666
+ */
667
+ static modify = Effect.fn("TomlFormat.modify")((text, path, value, options) => Effect.fromResult(TomlFormat.modifyResult(text, path, value, options)));
668
+ /**
669
+ * Synchronous {@link TomlFormat.modifyToString}: modify `text` and apply the
670
+ * resulting edits in one step (`TomlEdit.applyAll ∘ modifyResult`),
671
+ * returning a `Result`. Inherits the {@link TomlFormat.modifyResult} error
672
+ * channel.
673
+ *
674
+ * @example
675
+ * ```ts
676
+ * import { TomlFormat } from "@effected/toml";
677
+ * import { Result } from "effect";
678
+ *
679
+ * const result = TomlFormat.modifyToStringResult("port = 3000 # dev\n", ["port"], 8080);
680
+ * if (Result.isSuccess(result)) {
681
+ * console.log(result.success); // => "port = 8080 # dev\n"
682
+ * }
683
+ * ```
684
+ *
685
+ * @param text - The TOML source to modify.
686
+ * @param path - The location to set, replace or delete.
687
+ * @param value - The plain JavaScript value to write; `undefined` deletes the
688
+ * target instead.
689
+ * @param options - Optional {@link TomlFormattingOptions}.
690
+ * @returns A `Result` succeeding with the modified text, or failing with
691
+ * {@link TomlParseError} or {@link TomlModificationError}.
692
+ */
693
+ static modifyToStringResult(text, path, value, options) {
694
+ return Result.map(TomlFormat.modifyResult(text, path, value, options), (edits) => TomlEdit.applyAll(text, edits));
695
+ }
641
696
  /**
642
697
  * Modify `text` and apply the resulting edits in one step
643
- * (`TomlEdit.applyAll ∘ modify`).
698
+ * (`TomlEdit.applyAll ∘ modify`). Defined in terms of
699
+ * {@link TomlFormat.modifyToStringResult}; it opens its own span and no
700
+ * longer a nested `TomlFormat.modify` child span.
644
701
  *
645
702
  * @param text - The TOML source to modify.
646
703
  * @param path - The location to set, replace or delete.
@@ -651,10 +708,7 @@ var TomlFormat = class TomlFormat {
651
708
  * {@link TomlParseError} or {@link TomlModificationError}, as
652
709
  * {@link TomlFormat.modify} does.
653
710
  */
654
- static modifyToString = Effect.fn("TomlFormat.modifyToString")(function* (text, path, value, options) {
655
- const edits = yield* TomlFormat.modify(text, path, value, options);
656
- return TomlEdit.applyAll(text, edits);
657
- });
711
+ static modifyToString = Effect.fn("TomlFormat.modifyToString")((text, path, value, options) => Effect.fromResult(TomlFormat.modifyToStringResult(text, path, value, options)));
658
712
  };
659
713
 
660
714
  export { TomlFormat, TomlFormattingOptions, TomlModificationError };
package/TomlVisitor.js CHANGED
@@ -1,12 +1,9 @@
1
- import { isRawTomlError } from "./internal/diagnostics.js";
2
- import { isGuardExceeded } from "./internal/limits.js";
3
1
  import { TomlKeyValue, TomlTrivia } from "./TomlNode.js";
4
2
  import { scanComment, scanNewline, scanWhitespace } from "./internal/scanner.js";
5
3
  import { parseExpressions } from "./internal/parser.js";
6
4
  import { analyze } from "./internal/semantic.js";
7
- import { TomlDiagnostic } from "./TomlDiagnostic.js";
8
- import { TomlParseError } from "./Toml.js";
9
- import { Data, Effect, Stream } from "effect";
5
+ import { toTomlParseError } from "./Toml.js";
6
+ import { Data, Effect, Result, Stream } from "effect";
10
7
 
11
8
  // src/TomlVisitor.ts
12
9
  /**
@@ -108,22 +105,14 @@ const collectEvents = (text) => {
108
105
  };
109
106
  /**
110
107
  * Run `collectEvents`, materializing the engine's raw carriers into
111
- * {@link TomlParseError} exactly like `Toml.parse` — a lex/parse error and a
112
- * semantic-pass error (e.g. `DuplicateKey`) both fail the same way.
108
+ * {@link TomlParseError} through the same `toTomlParseError` mapping
109
+ * `Toml.parse` uses — a lex/parse error and a semantic-pass error (e.g.
110
+ * `DuplicateKey`) both fail the same way.
113
111
  */
114
- const collectEventsOrFail = (text) => Effect.try({
112
+ const collectEventsOrFail = (text) => Effect.suspend(() => Effect.fromResult(Result.try({
115
113
  try: () => collectEvents(text),
116
- catch: (defect) => {
117
- if (isRawTomlError(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, defect.diagnostic)] });
118
- if (isGuardExceeded(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, {
119
- code: "NestingDepthExceeded",
120
- message: defect.message,
121
- offset: defect.offset,
122
- length: 0
123
- })] });
124
- throw defect;
125
- }
126
- });
114
+ catch: (defect) => toTomlParseError(text, defect)
115
+ })));
127
116
  /**
128
117
  * Walks TOML text as a `Stream` of table, array-table, key-value and comment
129
118
  * events in document order, without building a value. Not instantiable.
package/index.d.ts CHANGED
@@ -678,13 +678,40 @@ declare const TomlDocument_base: Schema.Class<TomlDocument, Schema.Struct<{
678
678
  * @public
679
679
  */
680
680
  export declare class TomlDocument extends TomlDocument_base {
681
+ /**
682
+ * Synchronous {@link TomlDocument.parse}, returning a `Result` instead of
683
+ * an `Effect` — the primitive `parse` is defined in terms of, so a
684
+ * synchronous host can call it without an Effect runtime. Fails with
685
+ * {@link TomlParseError} only on lex/parse errors — including a
686
+ * nesting-depth bomb, which surfaces as a `NestingDepthExceeded`
687
+ * diagnostic, never a throw. Semantic violations do not fail: they land in
688
+ * `diagnostics` as data (first violation wins, so there is at most one
689
+ * today; the array shape is the contract).
690
+ *
691
+ * @example
692
+ * ```ts
693
+ * import { TomlDocument } from "@effected/toml";
694
+ * import { Result } from "effect";
695
+ *
696
+ * const result = TomlDocument.parseResult('name = "Alice"\n');
697
+ * if (Result.isSuccess(result)) {
698
+ * console.log(result.success.stringify()); // => 'name = "Alice"\n'
699
+ * }
700
+ * ```
701
+ *
702
+ * @param text - The TOML source to parse.
703
+ * @returns A `Result` succeeding with the {@link TomlDocument}, or failing
704
+ * with {@link TomlParseError}.
705
+ */
706
+ static parseResult(text: string): Result.Result<TomlDocument, TomlParseError>;
681
707
  /**
682
708
  * Parse TOML text into a lossless document. Fails with
683
709
  * {@link TomlParseError} only on lex/parse errors — including a
684
710
  * nesting-depth bomb, which surfaces as a `NestingDepthExceeded`
685
711
  * diagnostic, never an unhandled defect. Semantic violations do not fail:
686
- * they land in `diagnostics` as data (first violation wins, so there is at
687
- * most one today; the array shape is the contract).
712
+ * they land in `diagnostics` as data. Defined in terms of
713
+ * {@link TomlDocument.parseResult} — synchronous callers can use that
714
+ * variant directly.
688
715
  *
689
716
  * @param text - The TOML source to parse.
690
717
  * @returns An `Effect` that succeeds with the {@link TomlDocument}, or fails
@@ -706,9 +733,37 @@ export declare class TomlDocument extends TomlDocument_base {
706
733
  * {@link TomlParseError} carrying the stored `diagnostics` when the parse
707
734
  * recorded semantic violations; otherwise builds the value from the
708
735
  * expression list (already validated, so the defensive materialization
709
- * wrapper is belt-and-suspenders).
736
+ * wrapper is belt-and-suspenders). Defined in terms of
737
+ * {@link TomlDocument.toValueResult} — synchronous callers can use that
738
+ * variant directly.
739
+ *
740
+ * @returns An `Effect` that succeeds with the plain value, or fails with
741
+ * {@link TomlParseError}.
710
742
  */
711
743
  toValue(): Effect.Effect<unknown, TomlParseError>;
744
+ /**
745
+ * Synchronous {@link TomlDocument.toValue}, returning a `Result` — the
746
+ * second half of a synchronous document round-trip that starts at
747
+ * {@link TomlDocument.parseResult}. Fails with {@link TomlParseError}
748
+ * carrying the stored `diagnostics` when the parse recorded semantic
749
+ * violations.
750
+ *
751
+ * @example
752
+ * ```ts
753
+ * import { TomlDocument } from "@effected/toml";
754
+ * import { Result } from "effect";
755
+ *
756
+ * const parsed = TomlDocument.parseResult("a = 1\na = 2\n");
757
+ * if (Result.isSuccess(parsed)) {
758
+ * const value = parsed.success.toValueResult();
759
+ * console.log(Result.isFailure(value)); // => true — DuplicateKey
760
+ * }
761
+ * ```
762
+ *
763
+ * @returns A `Result` succeeding with the plain value, or failing with
764
+ * {@link TomlParseError}.
765
+ */
766
+ toValueResult(): Result.Result<unknown, TomlParseError>;
712
767
  /**
713
768
  * Reconstruct the document text by concatenating each expression's source
714
769
  * span in order. The expression spans tile the source exactly, so the
@@ -874,7 +929,9 @@ export declare class TomlFormat {
874
929
  static formatToString(text: string, range?: TomlRangeLike, options?: TomlFormattingOptions): string;
875
930
  /**
876
931
  * Compute the edits that replace, delete, or insert a value at `path`,
877
- * resolved through the document's semantic view. Every segment but the
932
+ * synchronously — the primitive {@link TomlFormat.modify} is defined in
933
+ * terms of, so a synchronous host can call it without an Effect runtime.
934
+ * Paths resolve through the document's semantic view. Every segment but the
878
935
  * last must resolve — intermediate tables are never auto-created. A
879
936
  * `value` of `undefined` deletes: a key-value's whole line, an inline
880
937
  * entry, or an array item, splicing separators. A new key inserts per the
@@ -891,15 +948,66 @@ export declare class TomlFormat {
891
948
  * target instead.
892
949
  * @param options - Optional {@link TomlFormattingOptions}; `newline` overrides
893
950
  * the newline used for inserted lines.
951
+ * @returns A `Result` succeeding with the edits to apply (via
952
+ * `TomlEdit.applyAll`), or failing with {@link TomlParseError} when the
953
+ * source does not parse, or {@link TomlModificationError} when `path`
954
+ * cannot be resolved or the insertion target is not allowed.
955
+ */
956
+ static modifyResult(text: string, path: TomlPath, value: unknown, options?: TomlFormattingOptions): Result.Result<ReadonlyArray<TomlEdit>, TomlParseError | TomlModificationError>;
957
+ /**
958
+ * Compute the edits that replace, delete, or insert a value at `path`.
959
+ * Defined in terms of {@link TomlFormat.modifyResult}, which carries the
960
+ * full contract — semantic path resolution, deletion splicing and the
961
+ * pinned insertion placement rules — behind a `TomlFormat.modify` span;
962
+ * synchronous callers can use that variant directly.
963
+ *
964
+ * @param text - The TOML source to modify.
965
+ * @param path - The location to set, replace or delete.
966
+ * @param value - The plain JavaScript value to write; `undefined` deletes the
967
+ * target instead.
968
+ * @param options - Optional {@link TomlFormattingOptions}; `newline` overrides
969
+ * the newline used for inserted lines.
894
970
  * @returns An `Effect` that succeeds with the edits to apply (via
895
971
  * `TomlEdit.applyAll`), or fails with {@link TomlParseError} when the
896
972
  * source does not parse, or {@link TomlModificationError} when `path`
897
973
  * cannot be resolved or the insertion target is not allowed.
974
+ *
975
+ * @remarks
976
+ * The source is parsed through `TomlDocument.parseResult`, so this span no
977
+ * longer opens a nested `TomlDocument.parse` child span.
898
978
  */
899
979
  static readonly modify: (text: string, path: TomlPath, value: unknown, options?: TomlFormattingOptions | undefined) => Effect.Effect<readonly TomlEdit[], TomlModificationError | TomlParseError, never>;
980
+ /**
981
+ * Synchronous {@link TomlFormat.modifyToString}: modify `text` and apply the
982
+ * resulting edits in one step (`TomlEdit.applyAll ∘ modifyResult`),
983
+ * returning a `Result`. Inherits the {@link TomlFormat.modifyResult} error
984
+ * channel.
985
+ *
986
+ * @example
987
+ * ```ts
988
+ * import { TomlFormat } from "@effected/toml";
989
+ * import { Result } from "effect";
990
+ *
991
+ * const result = TomlFormat.modifyToStringResult("port = 3000 # dev\n", ["port"], 8080);
992
+ * if (Result.isSuccess(result)) {
993
+ * console.log(result.success); // => "port = 8080 # dev\n"
994
+ * }
995
+ * ```
996
+ *
997
+ * @param text - The TOML source to modify.
998
+ * @param path - The location to set, replace or delete.
999
+ * @param value - The plain JavaScript value to write; `undefined` deletes the
1000
+ * target instead.
1001
+ * @param options - Optional {@link TomlFormattingOptions}.
1002
+ * @returns A `Result` succeeding with the modified text, or failing with
1003
+ * {@link TomlParseError} or {@link TomlModificationError}.
1004
+ */
1005
+ static modifyToStringResult(text: string, path: TomlPath, value: unknown, options?: TomlFormattingOptions): Result.Result<string, TomlParseError | TomlModificationError>;
900
1006
  /**
901
1007
  * Modify `text` and apply the resulting edits in one step
902
- * (`TomlEdit.applyAll ∘ modify`).
1008
+ * (`TomlEdit.applyAll ∘ modify`). Defined in terms of
1009
+ * {@link TomlFormat.modifyToStringResult}; it opens its own span and no
1010
+ * longer a nested `TomlFormat.modify` child span.
903
1011
  *
904
1012
  * @param text - The TOML source to modify.
905
1013
  * @param path - The location to set, replace or delete.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@effected/toml",
3
- "version": "0.15.0",
3
+ "version": "0.16.0",
4
4
  "private": false,
5
5
  "description": "TOML 1.1.0 parsing, editing and formatting as Effect schemas: typed diagnostics, a lossless CST and first-class date-time values.",
6
6
  "keywords": [