@effected/toml 0.2.0 → 0.3.0

package/Toml.js

@@ -4,7 +4,7 @@ import { parseExpressions } from "./internal/parser.js";
 import { buildValue } from "./internal/semantic.js";
 import { stringifyValue } from "./internal/stringifyValue.js";
 import { TomlDiagnostic } from "./TomlDiagnostic.js";
-import { Effect, Option, Schema, SchemaIssue, SchemaTransformation } from "effect";
+import { Effect, Option, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
 
 //#region src/Toml.ts
 /**
@@ -54,34 +54,38 @@ var TomlStringifyError = class extends Schema.TaggedErrorClass()("TomlStringifyE
 * Run the parser and semantic pass, materializing the engine's raw carriers
 * into the typed error: `RawTomlError` becomes a positioned diagnostic and a
 * `GuardExceeded` depth trip becomes a `NestingDepthExceeded` diagnostic
-* (never an unhandled defect). Anything else is a genuine defect and rethrows.
+* (never an unhandled defect). Anything else is a genuine defect and rethrows
+* — synchronously to a `Result` caller, and as a `Die` through the `Effect`
+* forms, which evaluate this inside the effect.
 */
-const parseOrFail = (text) => Effect.try({
-	try: () => buildValue(parseExpressions(text)),
-	catch: (defect) => {
-		if (isRawTomlError(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, defect.diagnostic)] });
-		if (isGuardExceeded(defect)) return new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, {
+const parseToResult = (text) => {
+	try {
+		return Result.succeed(buildValue(parseExpressions(text)));
+	} catch (defect) {
+		if (isRawTomlError(defect)) return Result.fail(new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, defect.diagnostic)] }));
+		if (isGuardExceeded(defect)) return Result.fail(new TomlParseError({ diagnostics: [TomlDiagnostic.fromRaw(text, {
 			code: "NestingDepthExceeded",
 			message: defect.message,
 			offset: defect.offset,
 			length: 0
-		})] });
+		})] }));
 		throw defect;
 	}
-});
-const stringifyOrFail = (value, options) => Effect.try({
-	try: () => stringifyValue(value, options?.newline ?? "\n"),
-	catch: (defect) => {
-		if (isRawTomlError(defect)) return new TomlStringifyError({ diagnostic: TomlDiagnostic.fromRaw("", defect.diagnostic) });
-		if (isGuardExceeded(defect)) return new TomlStringifyError({ diagnostic: TomlDiagnostic.fromRaw("", {
+};
+const stringifyToResult = (value, options) => {
+	try {
+		return Result.succeed(stringifyValue(value, options?.newline ?? "\n"));
+	} catch (defect) {
+		if (isRawTomlError(defect)) return Result.fail(new TomlStringifyError({ diagnostic: TomlDiagnostic.fromRaw("", defect.diagnostic) }));
+		if (isGuardExceeded(defect)) return Result.fail(new TomlStringifyError({ diagnostic: TomlDiagnostic.fromRaw("", {
 			code: "NestingDepthExceeded",
 			message: defect.message,
 			offset: 0,
 			length: 0
-		}) });
+		}) }));
 		throw defect;
 	}
-});
+};
 /**
 * Static entry points for TOML parsing, stringification and the schema
 * factories. Not instantiable.
@@ -110,32 +114,110 @@ const stringifyOrFail = (value, options) => Effect.try({
 var Toml = class Toml {
 	constructor() {}
 	/**
-	* Parse a TOML 1.1.0 document into a plain JavaScript value: tables and
-	* inline tables become plain objects (`__proto__` lands as an own data
-	* property), arrays become plain arrays, integers become `number` (or
-	* `bigint` past 2^53) and date-times become the four `TomlDateTime`
-	* classes. Fails with {@link TomlParseError} at the first violation;
-	* returns `unknown`, never `any`.
+	* Parse a TOML 1.1.0 document into a plain JavaScript value, synchronously,
+	* returning a `Result` instead of an `Effect`: tables and inline tables
+	* become plain objects (`__proto__` lands as an own data property), arrays
+	* become plain arrays, integers become `number` (or `bigint` past 2^53) and
+	* date-times become the four `TomlDateTime` classes. Fails with
+	* {@link TomlParseError} at the first violation; returns `unknown`, never
+	* `any`.
 	*
 	* A nesting-depth bomb (arrays or inline tables past the engine cap) also
 	* fails through {@link TomlParseError} with a `NestingDepthExceeded`
 	* diagnostic, never as an unhandled defect.
+	*
+	* @remarks
+	* {@link Toml.parse} is defined in terms of this function; the two never
+	* diverge. Reach for the `Effect` variant inside Effect code — it carries
+	* the `Toml.parse` tracing span — and for this one at synchronous
+	* boundaries such as a lint-staged handler.
+	*
+	* @example
+	* ```ts
+	* import { Toml } from "@effected/toml";
+	* import { Result } from "effect";
+	*
+	* const ok = Toml.parseResult('name = "Alice"');
+	* if (Result.isSuccess(ok)) {
+	*   console.log(ok.success); // => { name: "Alice" }
+	* }
+	*
+	* const bad = Toml.parseResult("name = ");
+	* if (Result.isFailure(bad)) {
+	*   console.log(bad.failure._tag); // => "TomlParseError"
+	* }
+	* ```
+	*
+	* @param text - The TOML source to parse.
+	* @returns A `Result` succeeding with the decoded value (`unknown`, never
+	*   `any`), or failing with {@link TomlParseError}.
+	*/
+	static parseResult(text) {
+		return parseToResult(text);
+	}
+	/**
+	* Parse a TOML 1.1.0 document into a plain JavaScript value. Defined in
+	* terms of {@link Toml.parseResult} — synchronous callers can use that
+	* variant directly.
+	*
+	* @param text - The TOML source to parse.
+	* @returns An `Effect` that succeeds with the decoded value, or fails with
+	*   {@link TomlParseError}.
 	*/
-	static parse = Effect.fn("Toml.parse")(function* (text) {
-		return yield* parseOrFail(text);
-	});
+	static parse = Effect.fn("Toml.parse")((text) => Effect.fromResult(Toml.parseResult(text)));
 	/**
-	* Stringify a plain JavaScript value as a canonical TOML document: within
-	* a table, non-table pairs first, then sub-tables as `[dotted.header]`
+	* Stringify a plain JavaScript value as a canonical TOML document,
+	* synchronously, returning a `Result` instead of an `Effect`: within a
+	* table, non-table pairs first, then sub-tables as `[dotted.header]`
 	* sections depth-first, then arrays of tables as `[[dotted.header]]`
 	* sections, a blank line before every header except at document start.
 	* Fails with {@link TomlStringifyError} on unsupported values (TOML has no
 	* null), out-of-int64-range `bigint`s, circular references and
 	* depth-guard trips — all on the typed channel.
+	*
+	* @remarks
+	* {@link Toml.stringify} is defined in terms of this function; the two
+	* never diverge. Reach for the `Effect` variant inside Effect code — it
+	* carries the `Toml.stringify` tracing span — and for this one at
+	* synchronous boundaries.
+	*
+	* @example
+	* ```ts
+	* import { Toml } from "@effected/toml";
+	* import { Result } from "effect";
+	*
+	* const ok = Toml.stringifyResult({ name: "Alice" });
+	* if (Result.isSuccess(ok)) {
+	*   console.log(ok.success); // => 'name = "Alice"\n'
+	* }
+	*
+	* const bad = Toml.stringifyResult({ nope: null });
+	* if (Result.isFailure(bad)) {
+	*   console.log(bad.failure._tag); // => "TomlStringifyError"
+	* }
+	* ```
+	*
+	* @param value - The plain JavaScript value to stringify.
+	* @param options - Optional {@link TomlStringifyOptions}; `newline`
+	*   defaults to `"\n"`.
+	* @returns A `Result` succeeding with the TOML text, or failing with
+	*   {@link TomlStringifyError}.
+	*/
+	static stringifyResult(value, options) {
+		return stringifyToResult(value, options);
+	}
+	/**
+	* Stringify a plain JavaScript value as a canonical TOML document. Defined
+	* in terms of {@link Toml.stringifyResult} — synchronous callers can use
+	* that variant directly.
+	*
+	* @param value - The plain JavaScript value to stringify.
+	* @param options - Optional {@link TomlStringifyOptions}; `newline`
+	*   defaults to `"\n"`.
+	* @returns An `Effect` that succeeds with the TOML text, or fails with
+	*   {@link TomlStringifyError}.
 	*/
-	static stringify = Effect.fn("Toml.stringify")(function* (value, options) {
-		return yield* stringifyOrFail(value, options);
-	});
+	static stringify = Effect.fn("Toml.stringify")((value, options) => Effect.fromResult(Toml.stringifyResult(value, options)));
 	/**
 	* A `Schema<unknown, string>` decoding a TOML document and encoding values
 	* back to canonical TOML text.
@@ -147,7 +229,7 @@ var Toml = class Toml {
 	static fromString() {
 		return Schema.String.pipe(Schema.decodeTo(Schema.Unknown, SchemaTransformation.transformOrFail({
 			decode: (input) => Toml.parse(input).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue(Option.some(input), { message: error.message }))),
-			encode: (value) => stringifyOrFail(value).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue(Option.some(value), { message: error.message })))
+			encode: (value) => Effect.fromResult(Toml.stringifyResult(value)).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue(Option.some(value), { message: error.message })))
 		})));
 	}
 	/**

package/index.d.ts

@@ -1,4 +1,4 @@
-import { Data, Effect, Schema, Stream } from "effect";
+import { Data, Effect, Result, Schema, Stream } from "effect";
 //#region src/TomlDiagnostic.d.ts
 /**
  * Error codes emitted by the lexer stage.
@@ -186,26 +186,104 @@ interface TomlBoundCodec<T, RD = never, RE = never> {
 declare class Toml {
   private constructor();
   /**
-   * Parse a TOML 1.1.0 document into a plain JavaScript value: tables and
-   * inline tables become plain objects (`__proto__` lands as an own data
-   * property), arrays become plain arrays, integers become `number` (or
-   * `bigint` past 2^53) and date-times become the four `TomlDateTime`
-   * classes. Fails with {@link TomlParseError} at the first violation;
-   * returns `unknown`, never `any`.
+   * Parse a TOML 1.1.0 document into a plain JavaScript value, synchronously,
+   * returning a `Result` instead of an `Effect`: tables and inline tables
+   * become plain objects (`__proto__` lands as an own data property), arrays
+   * become plain arrays, integers become `number` (or `bigint` past 2^53) and
+   * date-times become the four `TomlDateTime` classes. Fails with
+   * {@link TomlParseError} at the first violation; returns `unknown`, never
+   * `any`.
    *
    * A nesting-depth bomb (arrays or inline tables past the engine cap) also
    * fails through {@link TomlParseError} with a `NestingDepthExceeded`
    * diagnostic, never as an unhandled defect.
+   *
+   * @remarks
+   * {@link Toml.parse} is defined in terms of this function; the two never
+   * diverge. Reach for the `Effect` variant inside Effect code — it carries
+   * the `Toml.parse` tracing span — and for this one at synchronous
+   * boundaries such as a lint-staged handler.
+   *
+   * @example
+   * ```ts
+   * import { Toml } from "@effected/toml";
+   * import { Result } from "effect";
+   *
+   * const ok = Toml.parseResult('name = "Alice"');
+   * if (Result.isSuccess(ok)) {
+   *   console.log(ok.success); // => { name: "Alice" }
+   * }
+   *
+   * const bad = Toml.parseResult("name = ");
+   * if (Result.isFailure(bad)) {
+   *   console.log(bad.failure._tag); // => "TomlParseError"
+   * }
+   * ```
+   *
+   * @param text - The TOML source to parse.
+   * @returns A `Result` succeeding with the decoded value (`unknown`, never
+   *   `any`), or failing with {@link TomlParseError}.
+   */
+  static parseResult(text: string): Result.Result<unknown, TomlParseError>;
+  /**
+   * Parse a TOML 1.1.0 document into a plain JavaScript value. Defined in
+   * terms of {@link Toml.parseResult} — synchronous callers can use that
+   * variant directly.
+   *
+   * @param text - The TOML source to parse.
+   * @returns An `Effect` that succeeds with the decoded value, or fails with
+   *   {@link TomlParseError}.
    */
   static readonly parse: (text: string) => Effect.Effect<unknown, TomlParseError, never>;
   /**
-   * Stringify a plain JavaScript value as a canonical TOML document: within
-   * a table, non-table pairs first, then sub-tables as `[dotted.header]`
+   * Stringify a plain JavaScript value as a canonical TOML document,
+   * synchronously, returning a `Result` instead of an `Effect`: within a
+   * table, non-table pairs first, then sub-tables as `[dotted.header]`
    * sections depth-first, then arrays of tables as `[[dotted.header]]`
    * sections, a blank line before every header except at document start.
    * Fails with {@link TomlStringifyError} on unsupported values (TOML has no
    * null), out-of-int64-range `bigint`s, circular references and
    * depth-guard trips — all on the typed channel.
+   *
+   * @remarks
+   * {@link Toml.stringify} is defined in terms of this function; the two
+   * never diverge. Reach for the `Effect` variant inside Effect code — it
+   * carries the `Toml.stringify` tracing span — and for this one at
+   * synchronous boundaries.
+   *
+   * @example
+   * ```ts
+   * import { Toml } from "@effected/toml";
+   * import { Result } from "effect";
+   *
+   * const ok = Toml.stringifyResult({ name: "Alice" });
+   * if (Result.isSuccess(ok)) {
+   *   console.log(ok.success); // => 'name = "Alice"\n'
+   * }
+   *
+   * const bad = Toml.stringifyResult({ nope: null });
+   * if (Result.isFailure(bad)) {
+   *   console.log(bad.failure._tag); // => "TomlStringifyError"
+   * }
+   * ```
+   *
+   * @param value - The plain JavaScript value to stringify.
+   * @param options - Optional {@link TomlStringifyOptions}; `newline`
+   *   defaults to `"\n"`.
+   * @returns A `Result` succeeding with the TOML text, or failing with
+   *   {@link TomlStringifyError}.
+   */
+  static stringifyResult(value: unknown, options?: TomlStringifyOptions): Result.Result<string, TomlStringifyError>;
+  /**
+   * Stringify a plain JavaScript value as a canonical TOML document. Defined
+   * in terms of {@link Toml.stringifyResult} — synchronous callers can use
+   * that variant directly.
+   *
+   * @param value - The plain JavaScript value to stringify.
+   * @param options - Optional {@link TomlStringifyOptions}; `newline`
+   *   defaults to `"\n"`.
+   * @returns An `Effect` that succeeds with the TOML text, or fails with
+   *   {@link TomlStringifyError}.
    */
   static readonly stringify: (value: unknown, options?: TomlStringifyOptions | undefined) => Effect.Effect<string, TomlStringifyError, never>;
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/toml",
-	"version": "0.2.0",
+	"version": "0.3.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": [