effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/unstable/process/ChildProcess.ts

@@ -4,10 +4,11 @@
  * This module uses an AST-based approach where commands are built first
  * using `make` and `pipeTo`, then executed using `spawn`.
  *
- * @example
+ * **Example** (Spawning and piping commands)
+ *
  * ```ts
- * import { NodeServices } from "@effect/platform-node"
  * import { Effect, Stream } from "effect"
+ * import { NodeServices } from "@effect/platform-node"
  * import { ChildProcess } from "effect/unstable/process"
  *
  * // Build a command
@@ -60,8 +61,8 @@ const TypeId = "~effect/unstable/process/ChildProcess"
  * Commands are built using `make` and can be combined using `pipeTo`.
  * They are executed using `exec` or `spawn`.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type Command =
   | StandardCommand
@@ -70,8 +71,8 @@ export type Command =
 /**
  * A standard command with pre-parsed command and arguments.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface StandardCommand extends
   Effect.Effect<
@@ -90,8 +91,8 @@ export interface StandardCommand extends
  * A pipeline of commands where the output of one is piped to the input of the
  * next.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface PipedCommand extends
   Effect.Effect<
@@ -114,8 +115,8 @@ export interface PipedCommand extends
  * - `"all"`: Pipe both stdout and stderr interleaved
  * - `` `fd${number}` ``: Pipe from a custom file descriptor (e.g., `"fd3"`)
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type PipeFromOption = "stdout" | "stderr" | "all" | `fd${number}`
 
@@ -125,15 +126,16 @@ export type PipeFromOption = "stdout" | "stderr" | "all" | `fd${number}`
  * - `"stdin"`: Pipe to stdin of the destination (default)
  * - `` `fd${number}` ``: Pipe to a custom file descriptor (e.g., `"fd3"`)
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type PipeToOption = "stdin" | `fd${number}`
 
 /**
  * Options for controlling how commands are piped together.
  *
- * @example
+ * **Example** (Piping stderr between commands)
+ *
  * ```ts
  * import { ChildProcess } from "effect/unstable/process"
  *
@@ -143,8 +145,8 @@ export type PipeToOption = "stdin" | `fd${number}`
  * )
  * ```
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface PipeOptions {
   /**
@@ -169,8 +171,8 @@ export interface PipeOptions {
 /**
  * Input type for child process stdin.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type CommandInput =
   | "pipe"
@@ -182,8 +184,8 @@ export type CommandInput =
 /**
  * Output type for child process stdout/stderr.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type CommandOutput =
   | "pipe"
@@ -195,8 +197,8 @@ export type CommandOutput =
 /**
  * A signal that can be sent to a child process.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type Signal =
   | "SIGABRT"
@@ -240,8 +242,8 @@ export type Signal =
 /**
  * The encoding format to use for binary data.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type Encoding =
   | "ascii"
@@ -260,8 +262,8 @@ export type Encoding =
 /**
  * Options that can be used to control how a child process is terminated.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface KillOptions {
   /**
@@ -284,8 +286,8 @@ export interface KillOptions {
 /**
  * Configuration for the child process standard input stream.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface StdinConfig {
   /**
@@ -318,8 +320,8 @@ export interface StdinConfig {
 /**
  * Configuration for the child process standard output stream.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface StdoutConfig {
   /**
@@ -339,8 +341,8 @@ export interface StdoutConfig {
 /**
  * Configuration for the child process standard error stream.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface StderrConfig {
   /**
@@ -360,8 +362,8 @@ export interface StderrConfig {
 /**
  * Configuration for additional file descriptors to expose to the child process.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type AdditionalFdConfig =
   | {
@@ -394,8 +396,8 @@ export type AdditionalFdConfig =
 /**
  * Options for command execution.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface CommandOptions extends KillOptions {
   /**
@@ -463,7 +465,8 @@ export interface CommandOptions extends KillOptions {
    * The file descriptor index is determined by the numeric suffix (i.e. `fd3`
    * has a file descriptor index of 3).
    *
-   * @example
+   * **Example** (Configuring additional file descriptors)
+   *
    * ```ts
    * import { ChildProcess } from "effect/unstable/process"
    *
@@ -488,16 +491,16 @@ export interface CommandOptions extends KillOptions {
 /**
  * Valid template expression item types.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type TemplateExpressionItem = string | number | boolean
 
 /**
  * Template expression type for interpolated values.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type TemplateExpression = TemplateExpressionItem | ReadonlyArray<TemplateExpressionItem>
 
@@ -518,24 +521,24 @@ const Proto = {
 /**
  * Check if a value is a `Command`.
  *
+ * @category guards
  * @since 4.0.0
- * @category Guards
  */
 export const isCommand = (u: unknown): u is Command => Predicate.hasProperty(u, TypeId)
 
 /**
  * Check if a command is a `StandardCommand`.
  *
+ * @category guards
  * @since 4.0.0
- * @category Guards
  */
 export const isStandardCommand = (command: Command): command is StandardCommand => command._tag === "StandardCommand"
 
 /**
  * Check if a command is a `PipedCommand`.
  *
+ * @category guards
  * @since 4.0.0
- * @category Guards
  */
 export const isPipedCommand = (command: Command): command is PipedCommand => command._tag === "PipedCommand"
 
@@ -574,7 +577,8 @@ const makePipedCommand = (
  * Template literals are not parsed until execution time, allowing parsing
  * errors to flow through Effect's error channel.
  *
- * @example
+ * **Example** (Creating commands)
+ *
  * ```ts
  * import { ChildProcess } from "effect/unstable/process"
  *
@@ -588,8 +592,8 @@ const makePipedCommand = (
  * const cmd3 = ChildProcess.make("git", ["status"])
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const make: {
   /**
@@ -603,7 +607,8 @@ export const make: {
    * Template literals are not parsed until execution time, allowing parsing
    * errors to flow through Effect's error channel.
    *
-   * @example
+   * **Example** (Creating commands)
+   *
    * ```ts
    * import { ChildProcess } from "effect/unstable/process"
    *
@@ -617,8 +622,8 @@ export const make: {
    * const cmd3 = ChildProcess.make("git", ["status"])
    * ```
    *
+   * @category constructors
    * @since 4.0.0
-   * @category Constructors
    */
   (command: string, options?: CommandOptions): StandardCommand
   /**
@@ -632,7 +637,8 @@ export const make: {
    * Template literals are not parsed until execution time, allowing parsing
    * errors to flow through Effect's error channel.
    *
-   * @example
+   * **Example** (Creating commands)
+   *
    * ```ts
    * import { ChildProcess } from "effect/unstable/process"
    *
@@ -646,8 +652,8 @@ export const make: {
    * const cmd3 = ChildProcess.make("git", ["status"])
    * ```
    *
+   * @category constructors
    * @since 4.0.0
-   * @category Constructors
    */
   (command: string, args: ReadonlyArray<string>, options?: CommandOptions): StandardCommand
   /**
@@ -661,7 +667,8 @@ export const make: {
    * Template literals are not parsed until execution time, allowing parsing
    * errors to flow through Effect's error channel.
    *
-   * @example
+   * **Example** (Creating commands)
+   *
    * ```ts
    * import { ChildProcess } from "effect/unstable/process"
    *
@@ -675,8 +682,8 @@ export const make: {
    * const cmd3 = ChildProcess.make("git", ["status"])
    * ```
    *
+   * @category constructors
    * @since 4.0.0
-   * @category Constructors
    */
   (options: CommandOptions): (
     templates: TemplateStringsArray,
@@ -693,7 +700,8 @@ export const make: {
    * Template literals are not parsed until execution time, allowing parsing
    * errors to flow through Effect's error channel.
    *
-   * @example
+   * **Example** (Creating commands)
+   *
    * ```ts
    * import { ChildProcess } from "effect/unstable/process"
    *
@@ -707,8 +715,8 @@ export const make: {
    * const cmd3 = ChildProcess.make("git", ["status"])
    * ```
    *
+   * @category constructors
    * @since 4.0.0
-   * @category Constructors
    */
   (
     templates: TemplateStringsArray,
@@ -755,7 +763,8 @@ export const make: {
  * By default, pipes `stdout` from the source to `stdin` of the destination.
  * Use the `options` parameter to customize which streams are connected.
  *
- * @example
+ * **Example** (Piping command output)
+ *
  * ```ts
  * import { ChildProcess } from "effect/unstable/process"
  *
@@ -775,8 +784,8 @@ export const make: {
  * )
  * ```
  *
+ * @category combinators
  * @since 4.0.0
- * @category Combinators
  */
 export const pipeTo: {
   /**
@@ -785,7 +794,8 @@ export const pipeTo: {
    * By default, pipes `stdout` from the source to `stdin` of the destination.
    * Use the `options` parameter to customize which streams are connected.
    *
-   * @example
+   * **Example** (Piping command output)
+   *
    * ```ts
    * import { ChildProcess } from "effect/unstable/process"
    *
@@ -805,8 +815,8 @@ export const pipeTo: {
    * )
    * ```
    *
+   * @category combinators
    * @since 4.0.0
-   * @category Combinators
    */
   (that: Command, options?: PipeOptions): (self: Command) => PipedCommand
   /**
@@ -815,7 +825,8 @@ export const pipeTo: {
    * By default, pipes `stdout` from the source to `stdin` of the destination.
    * Use the `options` parameter to customize which streams are connected.
    *
-   * @example
+   * **Example** (Piping command output)
+   *
    * ```ts
    * import { ChildProcess } from "effect/unstable/process"
    *
@@ -835,8 +846,8 @@ export const pipeTo: {
    * )
    * ```
    *
+   * @category combinators
    * @since 4.0.0
-   * @category Combinators
    */
   (self: Command, that: Command, options?: PipeOptions): PipedCommand
 } = dual(
@@ -849,7 +860,8 @@ export const pipeTo: {
  *
  * For pipelines, only the leftmost command is prefixed.
  *
- * @example
+ * **Example** (Prefixing commands)
+ *
  * ```ts
  * import { ChildProcess } from "effect/unstable/process"
  *
@@ -862,8 +874,8 @@ export const pipeTo: {
  * // now prefixed will execute `time echo "foo"`
  * ```
  *
+ * @category combinators
  * @since 4.0.0
- * @category Combinators
  */
 export const prefix: {
   /**
@@ -871,7 +883,8 @@ export const prefix: {
    *
    * For pipelines, only the leftmost command is prefixed.
    *
-   * @example
+   * **Example** (Prefixing commands)
+   *
    * ```ts
    * import { ChildProcess } from "effect/unstable/process"
    *
@@ -884,8 +897,8 @@ export const prefix: {
    * // now prefixed will execute `time echo "foo"`
    * ```
    *
+   * @category combinators
    * @since 4.0.0
-   * @category Combinators
    */
   (command: string, args?: ReadonlyArray<string>): (self: Command) => Command
   /**
@@ -893,7 +906,8 @@ export const prefix: {
    *
    * For pipelines, only the leftmost command is prefixed.
    *
-   * @example
+   * **Example** (Prefixing commands)
+   *
    * ```ts
    * import { ChildProcess } from "effect/unstable/process"
    *
@@ -906,8 +920,8 @@ export const prefix: {
    * // now prefixed will execute `time echo "foo"`
    * ```
    *
+   * @category combinators
    * @since 4.0.0
-   * @category Combinators
    */
   (
     templates: TemplateStringsArray,
@@ -918,7 +932,8 @@ export const prefix: {
    *
    * For pipelines, only the leftmost command is prefixed.
    *
-   * @example
+   * **Example** (Prefixing commands)
+   *
    * ```ts
    * import { ChildProcess } from "effect/unstable/process"
    *
@@ -931,8 +946,8 @@ export const prefix: {
    * // now prefixed will execute `time echo "foo"`
    * ```
    *
+   * @category combinators
    * @since 4.0.0
-   * @category Combinators
    */
   (self: Command, command: string, args?: ReadonlyArray<string>): Command
 } = function prefix(...args: Array<unknown>): any {
@@ -980,7 +995,8 @@ const applyPrefix = (self: Command, prefixSpec: PrefixSpec): Command => {
  *
  * For pipelines, applies to each command in the pipeline.
  *
- * @example
+ * **Example** (Setting command working directories)
+ *
  * ```ts
  * import { ChildProcess } from "effect/unstable/process"
  *
@@ -989,8 +1005,8 @@ const applyPrefix = (self: Command, prefixSpec: PrefixSpec): Command => {
  * )
  * ```
  *
+ * @category combinators
  * @since 4.0.0
- * @category Combinators
  */
 export const setCwd: {
   /**
@@ -998,7 +1014,8 @@ export const setCwd: {
    *
    * For pipelines, applies to each command in the pipeline.
    *
-   * @example
+   * **Example** (Setting command working directories)
+   *
    * ```ts
    * import { ChildProcess } from "effect/unstable/process"
    *
@@ -1007,8 +1024,8 @@ export const setCwd: {
    * )
    * ```
    *
+   * @category combinators
    * @since 4.0.0
-   * @category Combinators
    */
   (cwd: string): (self: Command) => Command
   /**
@@ -1016,7 +1033,8 @@ export const setCwd: {
    *
    * For pipelines, applies to each command in the pipeline.
    *
-   * @example
+   * **Example** (Setting command working directories)
+   *
    * ```ts
    * import { ChildProcess } from "effect/unstable/process"
    *
@@ -1025,8 +1043,8 @@ export const setCwd: {
    * )
    * ```
    *
+   * @category combinators
    * @since 4.0.0
-   * @category Combinators
    */
   (self: Command, cwd: string): Command
 } = dual(
@@ -1044,11 +1062,13 @@ export const setCwd: {
 )
 
 /**
- * Set environment variables for a command.
+ * Adds environment variables to a command, merging them with any existing
+ * command environment and overriding duplicate keys.
  *
  * For pipelines, applies to each command in the pipeline.
  *
- * @example
+ * **Example** (Setting command environment variables)
+ *
  * ```ts
  * import { ChildProcess } from "effect/unstable/process"
  *
@@ -1057,16 +1077,18 @@ export const setCwd: {
  * )
  * ```
  *
+ * @category combinators
  * @since 4.0.0
- * @category Combinators
  */
 export const setEnv: {
   /**
-   * Set environment variables for a command.
+   * Adds environment variables to a command, merging them with any existing
+   * command environment and overriding duplicate keys.
    *
    * For pipelines, applies to each command in the pipeline.
    *
-   * @example
+   * **Example** (Setting command environment variables)
+   *
    * ```ts
    * import { ChildProcess } from "effect/unstable/process"
    *
@@ -1075,16 +1097,18 @@ export const setEnv: {
    * )
    * ```
    *
+   * @category combinators
    * @since 4.0.0
-   * @category Combinators
    */
   (env: Record<string, string>): (self: Command) => Command
   /**
-   * Set environment variables for a command.
+   * Adds environment variables to a command, merging them with any existing
+   * command environment and overriding duplicate keys.
    *
    * For pipelines, applies to each command in the pipeline.
    *
-   * @example
+   * **Example** (Setting command environment variables)
+   *
    * ```ts
    * import { ChildProcess } from "effect/unstable/process"
    *
@@ -1093,8 +1117,8 @@ export const setEnv: {
    * )
    * ```
    *
+   * @category combinators
    * @since 4.0.0
-   * @category Combinators
    */
   (self: Command, env: Record<string, string>): Command
 } = dual(
@@ -1125,8 +1149,8 @@ const isTemplateString = (u: unknown): u is TemplateStringsArray =>
  * Parse an fd name like "fd3" to its numeric index.
  * Returns undefined if the name is invalid.
  *
+ * @category utils
  * @since 4.0.0
- * @category Utilities
  */
 export const parseFdName = (name: string): number | undefined => {
   const match = /^fd(\d+)$/.exec(name)
@@ -1138,8 +1162,8 @@ export const parseFdName = (name: string): number | undefined => {
 /**
  * Create an fd name from its numeric index.
  *
+ * @category utils
  * @since 4.0.0
- * @category Utilities
  */
 export const fdName = (fd: number): string => `fd${fd}`
 

package/src/unstable/process/ChildProcessSpawner.ts

@@ -17,26 +17,35 @@ import * as Stream from "../../Stream.ts"
 import type { Command, KillOptions } from "./ChildProcess.ts"
 
 /**
+ * Branded number representing the exit code reported by a child process.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type ExitCode = Brand.Branded<number, "ExitCode">
 
 /**
+ * Brand constructor for child process `ExitCode` values.
+ *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const ExitCode: Brand.Constructor<ExitCode> = Brand.nominal<ExitCode>()
 
 /**
+ * Branded number representing the operating system process identifier of a
+ * child process.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type ProcessId = Brand.Branded<number, "ProcessId">
 
 /**
+ * Brand constructor for child process `ProcessId` values.
+ *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const ProcessId: Brand.Constructor<ProcessId> = Brand.nominal<ProcessId>()
 
@@ -48,8 +57,8 @@ export const ProcessId: Brand.Constructor<ProcessId> = Brand.nominal<ProcessId>(
  * restore the default behavior where the child process keeps the parent
  * process alive.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type Reref = Effect.Effect<void, PlatformError.PlatformError>
 
@@ -58,8 +67,8 @@ const HandleTypeId = "~effect/ChildProcessSpawner/ChildProcessHandle"
 /**
  * A handle to a running child process.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface ChildProcessHandle {
   readonly [HandleTypeId]: typeof HandleTypeId
@@ -135,10 +144,11 @@ export interface ChildProcessHandle {
    * This is the only supported way to re-reference a child process after it
    * has been unrefed.
    *
-   * @example
+   * **Example** (Temporarily unreferencing a child process)
+   *
    * ```ts
-   * import { NodeServices } from "@effect/platform-node"
    * import { Effect } from "effect"
+   * import { NodeServices } from "@effect/platform-node"
    * import { ChildProcess } from "effect/unstable/process"
    *
    * const program = Effect.gen(function*() {
@@ -166,17 +176,18 @@ const HandleProto = {
 /**
  * Constructs a new `ChildProcessHandle`.
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const makeHandle = (params: Omit<ChildProcessHandle, typeof HandleTypeId>): ChildProcessHandle =>
   Object.assign(Object.create(HandleProto), params)
 
 /**
- * Create a new `ChildProcessSpawner` service from a `spawn` funciton
+ * Creates a `ChildProcessSpawner` service from a `spawn` function, deriving
+ * helpers for exit codes and output collection from that implementation.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export const make = (spawn: ChildProcessSpawner["Service"]["spawn"]): ChildProcessSpawner["Service"] => {
   const streamString: ChildProcessSpawner["Service"]["streamLines"] = (command, options) =>
@@ -204,8 +215,8 @@ export const make = (spawn: ChildProcessSpawner["Service"]["spawn"]): ChildProce
 /**
  * Service tag for child process spawning.
  *
+ * @category services
  * @since 4.0.0
- * @category Service
  */
 export class ChildProcessSpawner extends Context.Service<ChildProcessSpawner, {
   /**