effect 4.0.0-beta.70 → 4.0.0-beta.71

package/dist/testing/TestConsole.js

@@ -1,13 +1,40 @@
 /**
- * The `TestConsole` module provides a test implementation of the `Console`
- * service that records console calls instead of writing them to the host
- * environment. It is useful when testing workflows that use `Console.log` or
- * `Console.error` and need to assert on the produced output.
- *
- * Use {@link layer} to provide the test console to an effect, then inspect
- * captured output with {@link logLines} and {@link errorLines}. Because console
- * operations are service-based effects, programs under test must be run with
- * this layer for their output to be captured.
+ * The `TestConsole` module provides a test implementation of the Effect
+ * `Console` service. When {@link layer} is provided, calls made through the
+ * Effect console APIs are captured in memory instead of being written to the
+ * host console, so tests can assert on logged values deterministically.
+ *
+ * This module is intentionally small: it gives tests a console layer, helpers
+ * for reading captured `Console.log` and `Console.error` arguments, and a way
+ * to access the provided test console service directly.
+ *
+ * **Mental model**
+ *
+ * - {@link layer} replaces the current `Console` service with a fresh
+ *   in-memory test console for the effect it is provided to
+ * - Code under test must call Effect's `Console` APIs; direct calls to
+ *   `globalThis.console` are outside the service and are not captured
+ * - {@link logLines} returns the values passed to `Console.log` in call order
+ * - {@link errorLines} returns the values passed to `Console.error` in call
+ *   order
+ * - {@link testConsoleWith} gives direct access to the current `TestConsole`
+ *   service when a test needs to inspect or call it manually
+ *
+ * **Common tasks**
+ *
+ * - Capture console output by providing {@link layer}
+ * - Assert on logged values with {@link logLines}
+ * - Assert on error output with {@link errorLines}
+ * - Construct a standalone test console service with {@link make}
+ * - Access the provided service with {@link testConsoleWith}
+ *
+ * **Gotchas**
+ *
+ * - Captured log and error values are the original arguments, not formatted
+ *   strings
+ * - `logLines` and `errorLines` expose `Console.log` and `Console.error`
+ *   output; other console methods are implemented for compatibility but do not
+ *   have dedicated accessor effects in this module
  *
  * @since 4.0.0
  */
@@ -20,6 +47,10 @@ import * as Layer from "../Layer.js";
  * The returned TestConsole implements the Console interface and provides
  * additional methods to retrieve logged messages.
  *
+ * **When to use**
+ *
+ * Use to construct a test console service value directly.
+ *
  * **Example** (Creating a test console)
  *
  * ```ts
@@ -38,6 +69,8 @@ import * as Layer from "../Layer.js";
  * }).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
+ * @see {@link layer} for providing a `TestConsole` as a `Layer`
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -81,6 +114,10 @@ export const make = /*#__PURE__*/Effect.gen(function* () {
  * Retrieves the `TestConsole` service for this test and uses it to run the
  * specified workflow.
  *
+ * **When to use**
+ *
+ * Use to access the provided test console service inside an effect.
+ *
  * **Example** (Accessing the test console service)
  *
  * ```ts
@@ -101,6 +138,10 @@ export const make = /*#__PURE__*/Effect.gen(function* () {
  * ).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
+ * @see {@link layer} for providing the test console service
+ * @see {@link logLines} for reading captured `Console.log` calls directly
+ * @see {@link errorLines} for reading captured `Console.error` calls directly
+ *
  * @category utils
  * @since 4.0.0
  */
@@ -110,6 +151,10 @@ export const testConsoleWith = f => Console.consoleWith(console => f(console));
  * This layer can be used to provide a TestConsole implementation
  * for testing purposes.
  *
+ * **When to use**
+ *
+ * Use to run an effect with console calls captured by `TestConsole`.
+ *
  * **Example** (Providing a test console layer)
  *
  * ```ts
@@ -128,6 +173,9 @@ export const testConsoleWith = f => Console.consoleWith(console => f(console));
  * }).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
+ * @see {@link make} for constructing the service value directly
+ * @see {@link testConsoleWith} for accessing the provided test console service
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -136,6 +184,11 @@ export const layer = /*#__PURE__*/Layer.effect(Console.Console)(make);
  * Returns an array of all items that have been logged by the program using
  * `Console.log` thus far.
  *
+ * **When to use**
+ *
+ * Use to assert on captured `Console.log` output from a program provided with
+ * `TestConsole.layer`.
+ *
  * **Example** (Reading captured log lines)
  *
  * ```ts
@@ -158,6 +211,9 @@ export const layer = /*#__PURE__*/Layer.effect(Console.Console)(make);
  * }).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
+ * @see {@link errorLines} for reading captured `Console.error` output
+ * @see {@link layer} for capturing console calls during a test
+ *
  * @category utils
  * @since 4.0.0
  */
@@ -166,6 +222,11 @@ export const logLines = /*#__PURE__*/testConsoleWith(console => console.logLines
  * Returns an array of all items that have been logged by the program using
  * `Console.error` thus far.
  *
+ * **When to use**
+ *
+ * Use to assert on captured `Console.error` output from a program provided
+ * with `TestConsole.layer`.
+ *
  * **Example** (Reading captured error lines)
  *
  * ```ts
@@ -186,6 +247,9 @@ export const logLines = /*#__PURE__*/testConsoleWith(console => console.logLines
  * }).pipe(Effect.provide(TestConsole.layer))
  * ```
  *
+ * @see {@link logLines} for reading captured `Console.log` output
+ * @see {@link layer} for capturing console calls during a test
+ *
  * @category utils
  * @since 4.0.0
  */

package/dist/testing/TestConsole.js.map

@@ -1 +1 @@
-{"version":3,"file":"TestConsole.js","names":["Array","Console","Effect","Layer","make","gen","entries","createEntryUnsafe","method","parameters","push","logLines","sync","flatMap","entry","errorLines","assert","clear","count","countReset","debug","dir","dirxml","error","group","groupCollapsed","groupEnd","info","log","table","time","timeEnd","timeLog","trace","warn","testConsoleWith","f","consoleWith","console","layer","effect"],"sources":["../../src/testing/TestConsole.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"TestConsole.js","names":["Array","Console","Effect","Layer","make","gen","entries","createEntryUnsafe","method","parameters","push","logLines","sync","flatMap","entry","errorLines","assert","clear","count","countReset","debug","dir","dirxml","error","group","groupCollapsed","groupEnd","info","log","table","time","timeEnd","timeLog","trace","warn","testConsoleWith","f","consoleWith","console","layer","effect"],"sources":["../../src/testing/TestConsole.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/testing/TestSchema.d.ts

@@ -9,7 +9,7 @@ import * as FastCheck from "../testing/FastCheck.ts";
  *
  * **When to use**
  *
- * Use `Asserts` when writing schema unit tests for decoding, encoding, construction, property-based round-trip, or generation behavior.
+ * Use when writing schema unit tests for decoding, encoding, construction, property-based round-trip, or generation behavior.
  *
  * **Example** (Decoding and encoding a struct)
  *
@@ -36,6 +36,11 @@ export declare class Asserts<S extends Schema.Top> {
     /**
      * Static helpers for comparing schema AST structures.
      *
+     * **When to use**
+     *
+     * Use to assert that two schema field or tuple element definitions produce
+     * the same AST structure.
+     *
      * **Details**
      *
      * `ast.fields.equals(a, b)` compares struct field ASTs via `assert.deepStrictEqual`. `ast.elements.equals(a, b)` compares tuple element ASTs via `assert.deepStrictEqual`.
@@ -64,6 +69,11 @@ export declare class Asserts<S extends Schema.Top> {
     /**
      * Returns an object with `succeed` and `fail` helpers for testing the schema's `make` operation.
      *
+     * **When to use**
+     *
+     * Use to assert how `Schema.make` accepts, transforms, or rejects
+     * construction input for this schema.
+     *
      * **Details**
      *
      * `succeed(input)` asserts make returns the input unchanged. `succeed(input, expected)` asserts make returns `expected`. `fail(input, message)` asserts make fails with `message`.
@@ -78,6 +88,9 @@ export declare class Asserts<S extends Schema.Top> {
      * const asserts = new TestSchema.Asserts(schema)
      * await asserts.make().succeed("hello")
      * ```
+     *
+     * @see {@link decoding} for assertions against decoded input
+     * @see {@link encoding} for assertions against encoded output
      */
     make(options?: Schema.MakeOptions): {
         succeed: {
@@ -89,6 +102,11 @@ export declare class Asserts<S extends Schema.Top> {
     /**
      * Runs a property-based test that encodes arbitrary values and then decodes them, asserting the decoded value equals the original.
      *
+     * **When to use**
+     *
+     * Use to verify that generated schema values survive an encode-then-decode
+     * round trip.
+     *
      * **Details**
      *
      * FastCheck generates arbitrary values matching the schema's `Type`. The assertion fails if any generated value does not round-trip. Pass `options.params` to control FastCheck parameters such as `numRuns`.
@@ -102,6 +120,8 @@ export declare class Asserts<S extends Schema.Top> {
      * const asserts = new TestSchema.Asserts(Schema.NumberFromString)
      * await asserts.verifyLosslessTransformation()
      * ```
+     *
+     * @see {@link arbitrary} for checking that generated values satisfy the schema
      */
     verifyLosslessTransformation<S extends Schema.Codec<unknown, unknown>>(this: Asserts<S>, options?: {
         readonly params?: FastCheck.Parameters<[S["Type"]]>;
@@ -109,6 +129,10 @@ export declare class Asserts<S extends Schema.Top> {
     /**
      * Returns a {@link Decoding} instance for this schema with helpers for decoding assertions.
      *
+     * **When to use**
+     *
+     * Use to test how unknown input is decoded into the schema's type.
+     *
      * **Details**
      *
      * Pass `parseOptions` to control error reporting, for example `{ errors: "all" }`.
@@ -126,6 +150,7 @@ export declare class Asserts<S extends Schema.Top> {
      * ```
      *
      * @see {@link Decoding}
+     * @see {@link encoding} for assertions in the opposite direction
      */
     decoding(options?: {
         readonly parseOptions?: AST.ParseOptions | undefined;
@@ -133,6 +158,10 @@ export declare class Asserts<S extends Schema.Top> {
     /**
      * Returns an {@link Encoding} instance for this schema with helpers for encoding assertions.
      *
+     * **When to use**
+     *
+     * Use to test how schema values are encoded into their external form.
+     *
      * **Details**
      *
      * Pass `parseOptions` to control error reporting, for example `{ errors: "all" }`.
@@ -149,6 +178,7 @@ export declare class Asserts<S extends Schema.Top> {
      * ```
      *
      * @see {@link Encoding}
+     * @see {@link decoding} for assertions in the opposite direction
      */
     encoding(options?: {
         readonly parseOptions?: AST.ParseOptions | undefined;
@@ -156,6 +186,11 @@ export declare class Asserts<S extends Schema.Top> {
     /**
      * Returns an object with property-based testing helpers for the schema's arbitrary generator.
      *
+     * **When to use**
+     *
+     * Use to verify that arbitrary values generated for this schema satisfy the
+     * schema's predicate.
+     *
      * **Details**
      *
      * `verifyGeneration()` generates arbitrary values and asserts each value satisfies the schema's `is` predicate. It defaults to 20 runs. Pass `options.params` to override FastCheck parameters.
@@ -169,6 +204,8 @@ export declare class Asserts<S extends Schema.Top> {
      * const asserts = new TestSchema.Asserts(Schema.String)
      * asserts.arbitrary().verifyGeneration()
      * ```
+     *
+     * @see {@link verifyLosslessTransformation} for property-based round-trip checks
      */
     arbitrary<S extends Schema.Codec<unknown, unknown, never, unknown>>(this: Asserts<S>): {
         verifyGeneration(options?: {
@@ -181,7 +218,7 @@ export declare class Asserts<S extends Schema.Top> {
  *
  * **When to use**
  *
- * Use `Decoding` when you want to assert that specific inputs decode to expected values, invalid inputs produce specific error messages, or schemas receive required decoding services.
+ * Use when you want to assert that specific inputs decode to expected values, invalid inputs produce specific error messages, or schemas receive required decoding services.
  *
  * **Details**
  *
@@ -217,6 +254,10 @@ export declare class Decoding<S extends Schema.Top> {
      * output equals the input. With two arguments, asserts the output equals
      * `expected`.
      *
+     * **When to use**
+     *
+     * Use to verify successful decoding for one input case.
+     *
      * **Example** (Identity and transformed decoding)
      *
      * ```ts
@@ -226,6 +267,8 @@ export declare class Decoding<S extends Schema.Top> {
      * const decoding = new TestSchema.Asserts(Schema.NumberFromString).decoding()
      * await decoding.succeed("1", 1) // transformed
      * ```
+     *
+     * @see {@link fail} for asserting decoding failures
      */
     succeed<S extends Schema.Decoder<unknown, never>>(this: Decoding<S>, input: unknown): Promise<void>;
     succeed<S extends Schema.Decoder<unknown, never>>(this: Decoding<S>, input: unknown, expected: S["Type"]): Promise<void>;
@@ -233,6 +276,10 @@ export declare class Decoding<S extends Schema.Top> {
      * Asserts that decoding `input` fails and the stringified issue equals
      * `message`.
      *
+     * **When to use**
+     *
+     * Use to verify that invalid decoding input produces the expected issue text.
+     *
      * **Example** (Asserting a decoding failure)
      *
      * ```ts
@@ -242,6 +289,8 @@ export declare class Decoding<S extends Schema.Top> {
      * const decoding = new TestSchema.Asserts(Schema.String).decoding()
      * await decoding.fail(42, "Expected string, got 42")
      * ```
+     *
+     * @see {@link succeed} for asserting successful decoding
      */
     fail<S extends Schema.Decoder<unknown, never>>(this: Decoding<S>, input: unknown, message: string): Promise<void>;
     /**
@@ -249,7 +298,7 @@ export declare class Decoding<S extends Schema.Top> {
      *
      * **When to use**
      *
-     * Use this when the schema's decoder requires a service dependency.
+     * Use when the schema's decoder requires a service dependency.
      *
      * **Details**
      *
@@ -260,23 +309,15 @@ export declare class Decoding<S extends Schema.Top> {
     provide<Id, Service>(service: Context.Key<Id, Service>, implementation: Service): Decoding<Schema.middlewareDecoding<S, Exclude<S["DecodingServices"], Id>>>;
 }
 /**
- * Encoding test helper. Mirrors {@link Decoding} but exercises the schema's
- * encoder direction.
+ * Encoding test helper that wraps a schema and exposes `succeed` and `fail` methods that run the schema's encoder and compare the result.
+ *
+ * **When to use**
+ *
+ * Use when you want to assert that specific values encode to expected outputs, invalid inputs produce specific error messages, or schemas receive required encoding services.
  *
- * When to use:
- * - You want to assert that specific values encode to expected outputs.
- * - You want to assert that invalid inputs produce specific error messages
- *   during encoding.
- * - You need to provide services required by the schema's encoding pipeline.
+ * **Details**
  *
- * Behavior:
- * - All assertions are async and use `assert.deepStrictEqual` internally.
- * - `succeed(input)` asserts the encoded output equals `input` (identity).
- * - `succeed(input, expected)` asserts the encoded output equals `expected`.
- * - `fail(input, message)` asserts encoding fails and the stringified issue
- *   equals `message`.
- * - `provide(key, impl)` returns a new `Encoding` with the service injected
- *   into the encoding context.
+ * All assertions are async and use `assert.deepStrictEqual` internally. `succeed(input)` asserts the encoded output equals `input`; `succeed(input, expected)` asserts it equals `expected`; `fail(input, message)` asserts encoding fails and the stringified issue equals `message`. `provide(key, impl)` returns a new `Encoding` with the service injected into the encoding context.
  *
  * **Example** (Encoding assertions)
  *
@@ -291,9 +332,10 @@ export declare class Decoding<S extends Schema.Top> {
  * @see {@link Asserts}
  * @see {@link Decoding}
  *
+ * @category testing
  * @since 4.0.0
  */
-declare class Encoding<S extends Schema.Top> {
+export declare class Encoding<S extends Schema.Top> {
     readonly schema: S;
     readonly encodeUnknownEffect: (input: unknown, options?: AST.ParseOptions) => Effect.Effect<S["Type"], Issue.Issue, S["EncodingServices"]>;
     readonly options?: {
@@ -307,6 +349,10 @@ declare class Encoding<S extends Schema.Top> {
      * output equals the input. With two arguments, asserts the output equals
      * `expected`.
      *
+     * **When to use**
+     *
+     * Use to verify successful encoding for one input case.
+     *
      * **Example** (Identity and transformed encoding)
      *
      * ```ts
@@ -316,6 +362,8 @@ declare class Encoding<S extends Schema.Top> {
      * const encoding = new TestSchema.Asserts(Schema.NumberFromString).encoding()
      * await encoding.succeed(1, "1") // transformed
      * ```
+     *
+     * @see {@link fail} for asserting encoding failures
      */
     succeed<S extends Schema.Encoder<unknown, never>>(this: Encoding<S>, input: unknown): Promise<void>;
     succeed<S extends Schema.Encoder<unknown, never>>(this: Encoding<S>, input: unknown, expected: S["Encoded"]): Promise<void>;
@@ -323,6 +371,10 @@ declare class Encoding<S extends Schema.Top> {
      * Asserts that encoding `input` fails and the stringified issue equals
      * `message`.
      *
+     * **When to use**
+     *
+     * Use to verify that invalid encoding input produces the expected issue text.
+     *
      * **Example** (Asserting an encoding failure)
      *
      * ```ts
@@ -332,18 +384,23 @@ declare class Encoding<S extends Schema.Top> {
      * const encoding = new TestSchema.Asserts(Schema.NumberFromString).encoding()
      * await encoding.fail("not-a-number", "Expected number, got \"not-a-number\"")
      * ```
+     *
+     * @see {@link succeed} for asserting successful encoding
      */
     fail<S extends Schema.Encoder<unknown, never>>(this: Encoding<S>, input: unknown, message: string): Promise<void>;
     /**
-     * Returns a new {@link Encoding} instance with the given service injected
-     * into the encoding effect context. Use this when the schema's encoder
-     * requires a service dependency.
+     * Returns a new {@link Encoding} instance with the given service injected into the encoding effect context.
      *
-     * - Does not mutate the current instance; returns a new one.
+     * **When to use**
+     *
+     * Use when the schema's encoder requires a service dependency.
+     *
+     * **Details**
+     *
+     * This method does not mutate the current instance.
      *
      * @see {@link Decoding.provide}
      */
     provide<Id, Service>(service: Context.Key<Id, Service>, implementation: Service): Encoding<Schema.middlewareEncoding<S, Exclude<S["EncodingServices"], Id>>>;
 }
-export {};
 //# sourceMappingURL=TestSchema.d.ts.map

package/dist/testing/TestSchema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TestSchema.d.ts","sourceRoot":"","sources":["../../src/testing/TestSchema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TestSchema.d.ts","sourceRoot":"","sources":["../../src/testing/TestSchema.ts"],"names":[],"mappings":"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"}