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

package/dist/Stdio.d.ts

@@ -1,19 +1,32 @@
 /**
- * The `Stdio` module defines the service interface used by Effect programs to
- * interact with process standard I/O. It models command-line arguments,
- * standard output, standard error, and standard input as Effects, Sinks, and
- * Streams so programs can depend on console I/O through `Context` instead of
- * directly coupling to a specific runtime.
- *
- * Use this module when building command-line programs, tests, or platform
- * integrations that need to read bytes from stdin, write text or bytes to
- * stdout/stderr, or provide deterministic replacements for those capabilities.
- * The `layerTest` helper is useful for tests because it supplies inert defaults
- * and lets individual fields be overridden.
- *
- * Standard I/O operations are platform capabilities and may fail with
- * `PlatformError`; handle those failures in the Effect error channel rather than
- * assuming writes or reads are infallible.
+ * Service contract for process standard input, output, error output, and
+ * command-line arguments.
+ *
+ * `Stdio` lets command-line programs depend on standard I/O through the Effect
+ * environment instead of reading from or writing to global process handles
+ * directly. The service exposes arguments as an `Effect`, stdout and stderr as
+ * `Sink`s that accept strings or bytes, and stdin as a byte `Stream`.
+ *
+ * **Mental model**
+ *
+ * Application code describes what it needs from standard I/O, and a runtime
+ * layer supplies the concrete streams. Platform packages provide real process
+ * implementations, while tests can use `Stdio.layerTest` to replace only the
+ * fields that matter for a scenario and keep the rest inert.
+ *
+ * **Common tasks**
+ *
+ * - Read command-line arguments from the service's `args` effect.
+ * - Write text or bytes by running values into the service's `stdout()` or
+ *   `stderr()` sinks.
+ * - Consume `stdin` as a stream of `Uint8Array` chunks.
+ * - Build deterministic tests with `Stdio.layerTest`.
+ *
+ * **Gotchas**
+ *
+ * Standard I/O is a platform capability. Reads and writes can fail with
+ * `PlatformError`, so handle failures in the Effect error channel instead of
+ * assuming the process streams are always available.
  *
  * @since 4.0.0
  */
@@ -26,6 +39,10 @@ import * as Stream from "./Stream.ts";
 /**
  * String literal type used as the unique brand for the `Stdio` service.
  *
+ * **When to use**
+ *
+ * Use to type the runtime identifier stored on `Stdio` service implementations.
+ *
  * @category type IDs
  * @since 4.0.0
  */
@@ -33,6 +50,10 @@ export type TypeId = "~effect/Stdio";
 /**
  * Runtime identifier stored on `Stdio` service implementations.
  *
+ * **When to use**
+ *
+ * Use to mark and recognize concrete `Stdio` service values at runtime.
+ *
  * @category type IDs
  * @since 4.0.0
  */
@@ -40,6 +61,11 @@ export declare const TypeId: TypeId;
 /**
  * Service interface for process standard I/O.
  *
+ * **When to use**
+ *
+ * Use to depend on command-line arguments and standard I/O through the Effect
+ * environment.
+ *
  * **Details**
  *
  * The service provides command-line arguments, sinks for standard output and
@@ -63,6 +89,14 @@ export interface Stdio {
 /**
  * Context service tag for the `Stdio` service.
  *
+ * **When to use**
+ *
+ * Use when an effect needs command-line arguments or standard I/O streams
+ * supplied by its environment.
+ *
+ * @see {@link make} for constructing a `Stdio` service directly
+ * @see {@link layerTest} for a test layer with defaults and overrides
+ *
  * @category services
  * @since 4.0.0
  */
@@ -71,6 +105,19 @@ export declare const Stdio: Context.Service<Stdio, Stdio>;
  * Creates a `Stdio` service implementation from the provided fields and
  * attaches the `Stdio` type identifier.
  *
+ * **When to use**
+ *
+ * Use to assemble a concrete `Stdio` service when you already have
+ * implementations for command-line arguments, standard output, standard error,
+ * and standard input.
+ *
+ * **Details**
+ *
+ * The returned service reuses the supplied fields unchanged and only adds the
+ * `Stdio` type identifier; it does not create a `Layer` or provide defaults.
+ *
+ * @see {@link layerTest} for a test layer with default fields that can be overridden
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -78,12 +125,19 @@ export declare const make: (options: Omit<Stdio, TypeId>) => Stdio;
 /**
  * Creates a test layer for `Stdio`.
  *
+ * **When to use**
+ *
+ * Use to provide deterministic standard I/O in tests while overriding only the
+ * command-line arguments, input stream, or output sinks relevant to the case.
+ *
  * **Details**
  *
  * Any provided fields override defaults. By default, arguments are empty,
  * standard output and error are draining sinks, and standard input is an empty
  * stream.
  *
+ * @see {@link make} for constructing a `Stdio` service directly without a `Layer` or defaults
+ *
  * @category layers
  * @since 4.0.0
  */

package/dist/Stdio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Stdio.d.ts","sourceRoot":"","sources":["../src/Stdio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AACjC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,eAAe,CAAA;AAEpC;;;;;GAKG;AACH,eAAO,MAAM,MAAM,EAAE,MAAwB,CAAA;AAE7C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IACnD,MAAM,CAAC,OAAO,CAAC,EAAE;QACf,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;KACzC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,KAAK,EAAE,aAAa,CAAC,CAAA;IAC9D,MAAM,CAAC,OAAO,CAAC,EAAE;QACf,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;KACzC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,KAAK,EAAE,aAAa,CAAC,CAAA;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,CAAA;CACzD;AACD;;;;;GAKG;AACH,eAAO,MAAM,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAkC,CAAA;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,KAAG,KAGlD,CAAA;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,OAAO,CAAC,KAAK,CAAC,KAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAU/D,CAAA"}
+{"version":3,"file":"Stdio.d.ts","sourceRoot":"","sources":["../src/Stdio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AACjC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;;;;;;;;GASG;AACH,MAAM,MAAM,MAAM,GAAG,eAAe,CAAA;AAEpC;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM,EAAE,MAAwB,CAAA;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IACnD,MAAM,CAAC,OAAO,CAAC,EAAE;QACf,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;KACzC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,KAAK,EAAE,aAAa,CAAC,CAAA;IAC9D,MAAM,CAAC,OAAO,CAAC,EAAE;QACf,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;KACzC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,KAAK,EAAE,aAAa,CAAC,CAAA;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,CAAA;CACzD;AACD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAkC,CAAA;AAElF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,KAAG,KAGlD,CAAA;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,OAAO,CAAC,KAAK,CAAC,KAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAU/D,CAAA"}

package/dist/Stdio.js

@@ -1,19 +1,32 @@
 /**
- * The `Stdio` module defines the service interface used by Effect programs to
- * interact with process standard I/O. It models command-line arguments,
- * standard output, standard error, and standard input as Effects, Sinks, and
- * Streams so programs can depend on console I/O through `Context` instead of
- * directly coupling to a specific runtime.
- *
- * Use this module when building command-line programs, tests, or platform
- * integrations that need to read bytes from stdin, write text or bytes to
- * stdout/stderr, or provide deterministic replacements for those capabilities.
- * The `layerTest` helper is useful for tests because it supplies inert defaults
- * and lets individual fields be overridden.
- *
- * Standard I/O operations are platform capabilities and may fail with
- * `PlatformError`; handle those failures in the Effect error channel rather than
- * assuming writes or reads are infallible.
+ * Service contract for process standard input, output, error output, and
+ * command-line arguments.
+ *
+ * `Stdio` lets command-line programs depend on standard I/O through the Effect
+ * environment instead of reading from or writing to global process handles
+ * directly. The service exposes arguments as an `Effect`, stdout and stderr as
+ * `Sink`s that accept strings or bytes, and stdin as a byte `Stream`.
+ *
+ * **Mental model**
+ *
+ * Application code describes what it needs from standard I/O, and a runtime
+ * layer supplies the concrete streams. Platform packages provide real process
+ * implementations, while tests can use `Stdio.layerTest` to replace only the
+ * fields that matter for a scenario and keep the rest inert.
+ *
+ * **Common tasks**
+ *
+ * - Read command-line arguments from the service's `args` effect.
+ * - Write text or bytes by running values into the service's `stdout()` or
+ *   `stderr()` sinks.
+ * - Consume `stdin` as a stream of `Uint8Array` chunks.
+ * - Build deterministic tests with `Stdio.layerTest`.
+ *
+ * **Gotchas**
+ *
+ * Standard I/O is a platform capability. Reads and writes can fail with
+ * `PlatformError`, so handle failures in the Effect error channel instead of
+ * assuming the process streams are always available.
  *
  * @since 4.0.0
  */
@@ -25,6 +38,10 @@ import * as Stream from "./Stream.js";
 /**
  * Runtime identifier stored on `Stdio` service implementations.
  *
+ * **When to use**
+ *
+ * Use to mark and recognize concrete `Stdio` service values at runtime.
+ *
  * @category type IDs
  * @since 4.0.0
  */
@@ -32,6 +49,14 @@ export const TypeId = "~effect/Stdio";
 /**
  * Context service tag for the `Stdio` service.
  *
+ * **When to use**
+ *
+ * Use when an effect needs command-line arguments or standard I/O streams
+ * supplied by its environment.
+ *
+ * @see {@link make} for constructing a `Stdio` service directly
+ * @see {@link layerTest} for a test layer with defaults and overrides
+ *
  * @category services
  * @since 4.0.0
  */
@@ -40,6 +65,19 @@ export const Stdio = /*#__PURE__*/Context.Service(TypeId);
  * Creates a `Stdio` service implementation from the provided fields and
  * attaches the `Stdio` type identifier.
  *
+ * **When to use**
+ *
+ * Use to assemble a concrete `Stdio` service when you already have
+ * implementations for command-line arguments, standard output, standard error,
+ * and standard input.
+ *
+ * **Details**
+ *
+ * The returned service reuses the supplied fields unchanged and only adds the
+ * `Stdio` type identifier; it does not create a `Layer` or provide defaults.
+ *
+ * @see {@link layerTest} for a test layer with default fields that can be overridden
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -50,12 +88,19 @@ export const make = options => ({
 /**
  * Creates a test layer for `Stdio`.
  *
+ * **When to use**
+ *
+ * Use to provide deterministic standard I/O in tests while overriding only the
+ * command-line arguments, input stream, or output sinks relevant to the case.
+ *
  * **Details**
  *
  * Any provided fields override defaults. By default, arguments are empty,
  * standard output and error are draining sinks, and standard input is an empty
  * stream.
  *
+ * @see {@link make} for constructing a `Stdio` service directly without a `Layer` or defaults
+ *
  * @category layers
  * @since 4.0.0
  */

package/dist/Stdio.js.map

@@ -1 +1 @@
-{"version":3,"file":"Stdio.js","names":["Context","Effect","Layer","Sink","Stream","TypeId","Stdio","Service","make","options","layerTest","impl","succeed","args","stdout","drain","stderr","stdin","empty"],"sources":["../src/Stdio.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,KAAKA,OAAO,MAAM,cAAc;AACvC,OAAO,KAAKC,MAAM,MAAM,aAAa;AACrC,OAAO,KAAKC,KAAK,MAAM,YAAY;AAEnC,OAAO,KAAKC,IAAI,MAAM,WAAW;AACjC,OAAO,KAAKC,MAAM,MAAM,aAAa;AAUrC;;;;;;AAMA,OAAO,MAAMC,MAAM,GAAW,eAAe;AAyB7C;;;;;;AAMA,OAAO,MAAMC,KAAK,gBAAkCN,OAAO,CAACO,OAAO,CAAQF,MAAM,CAAC;AAElF;;;;;;;AAOA,OAAO,MAAMG,IAAI,GAAIC,OAA4B,KAAa;EAC5D,CAACJ,MAAM,GAAGA,MAAM;EAChB,GAAGI;CACJ,CAAC;AAEF;;;;;;;;;;;;AAYA,OAAO,MAAMC,SAAS,GAAIC,IAAoB,IAC5CT,KAAK,CAACU,OAAO,CACXN,KAAK,EACLE,IAAI,CAAC;EACHK,IAAI,EAAEZ,MAAM,CAACW,OAAO,CAAC,EAAE,CAAC;EACxBE,MAAM,EAAEA,CAAA,KAAMX,IAAI,CAACY,KAAK;EACxBC,MAAM,EAAEA,CAAA,KAAMb,IAAI,CAACY,KAAK;EACxBE,KAAK,EAAEb,MAAM,CAACc,KAAK;EACnB,GAAGP;CACJ,CAAC,CACH","ignoreList":[]}
+{"version":3,"file":"Stdio.js","names":["Context","Effect","Layer","Sink","Stream","TypeId","Stdio","Service","make","options","layerTest","impl","succeed","args","stdout","drain","stderr","stdin","empty"],"sources":["../src/Stdio.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,OAAO,KAAKA,OAAO,MAAM,cAAc;AACvC,OAAO,KAAKC,MAAM,MAAM,aAAa;AACrC,OAAO,KAAKC,KAAK,MAAM,YAAY;AAEnC,OAAO,KAAKC,IAAI,MAAM,WAAW;AACjC,OAAO,KAAKC,MAAM,MAAM,aAAa;AAcrC;;;;;;;;;;AAUA,OAAO,MAAMC,MAAM,GAAW,eAAe;AA8B7C;;;;;;;;;;;;;;AAcA,OAAO,MAAMC,KAAK,gBAAkCN,OAAO,CAACO,OAAO,CAAQF,MAAM,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,MAAMG,IAAI,GAAIC,OAA4B,KAAa;EAC5D,CAACJ,MAAM,GAAGA,MAAM;EAChB,GAAGI;CACJ,CAAC;AAEF;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,MAAMC,SAAS,GAAIC,IAAoB,IAC5CT,KAAK,CAACU,OAAO,CACXN,KAAK,EACLE,IAAI,CAAC;EACHK,IAAI,EAAEZ,MAAM,CAACW,OAAO,CAAC,EAAE,CAAC;EACxBE,MAAM,EAAEA,CAAA,KAAMX,IAAI,CAACY,KAAK;EACxBC,MAAM,EAAEA,CAAA,KAAMb,IAAI,CAACY,KAAK;EACxBE,KAAK,EAAEb,MAAM,CAACc,KAAK;EACnB,GAAGP;CACJ,CAAC,CACH","ignoreList":[]}