effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/process/ChildProcess.ts

@@ -4,7 +4,8 @@
  * 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"
@@ -40,11 +41,11 @@
  *
  * @since 4.0.0
  */
+import * as Context from "../../Context.ts"
 import type * as Duration from "../../Duration.ts"
 import type * as Effect from "../../Effect.ts"
+import * as Effectable from "../../Effectable.ts"
 import { dual } from "../../Function.ts"
-import { PipeInspectableProto, YieldableProto } from "../../internal/core.ts"
-import type { Pipeable } from "../../Pipeable.ts"
 import type * as PlatformError from "../../PlatformError.ts"
 import * as Predicate from "../../Predicate.ts"
 import type * as Scope from "../../Scope.ts"
@@ -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`.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export type Command =
   | StandardCommand
@@ -70,13 +71,11 @@ export type Command =
 /**
  * A standard command with pre-parsed command and arguments.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface StandardCommand extends
-  Pipeable,
-  Effect.Yieldable<
-    StandardCommand,
+  Effect.Effect<
     ChildProcessHandle,
     PlatformError.PlatformError,
     ChildProcessSpawner | Scope.Scope
@@ -92,13 +91,11 @@ export interface StandardCommand extends
  * A pipeline of commands where the output of one is piped to the input of the
  * next.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface PipedCommand extends
-  Pipeable,
-  Effect.Yieldable<
-    PipedCommand,
+  Effect.Effect<
     ChildProcessHandle,
     PlatformError.PlatformError,
     ChildProcessSpawner | Scope.Scope
@@ -118,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"`)
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export type PipeFromOption = "stdout" | "stderr" | "all" | `fd${number}`
 
@@ -129,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"`)
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 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"
  *
@@ -147,8 +145,8 @@ export type PipeToOption = "stdin" | `fd${number}`
  * )
  * ```
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface PipeOptions {
   /**
@@ -173,8 +171,8 @@ export interface PipeOptions {
 /**
  * Input type for child process stdin.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export type CommandInput =
   | "pipe"
@@ -186,8 +184,8 @@ export type CommandInput =
 /**
  * Output type for child process stdout/stderr.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export type CommandOutput =
   | "pipe"
@@ -199,8 +197,8 @@ export type CommandOutput =
 /**
  * A signal that can be sent to a child process.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export type Signal =
   | "SIGABRT"
@@ -244,8 +242,8 @@ export type Signal =
 /**
  * The encoding format to use for binary data.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export type Encoding =
   | "ascii"
@@ -264,8 +262,8 @@ export type Encoding =
 /**
  * Options that can be used to control how a child process is terminated.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface KillOptions {
   /**
@@ -288,8 +286,8 @@ export interface KillOptions {
 /**
  * Configuration for the child process standard input stream.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface StdinConfig {
   /**
@@ -322,8 +320,8 @@ export interface StdinConfig {
 /**
  * Configuration for the child process standard output stream.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface StdoutConfig {
   /**
@@ -343,8 +341,8 @@ export interface StdoutConfig {
 /**
  * Configuration for the child process standard error stream.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface StderrConfig {
   /**
@@ -364,8 +362,8 @@ export interface StderrConfig {
 /**
  * Configuration for additional file descriptors to expose to the child process.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export type AdditionalFdConfig =
   | {
@@ -398,8 +396,8 @@ export type AdditionalFdConfig =
 /**
  * Options for command execution.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface CommandOptions extends KillOptions {
   /**
@@ -467,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"
    *
@@ -492,16 +491,16 @@ export interface CommandOptions extends KillOptions {
 /**
  * Valid template expression item types.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export type TemplateExpressionItem = string | number | boolean
 
 /**
  * Template expression type for interpolated values.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export type TemplateExpression = TemplateExpressionItem | ReadonlyArray<TemplateExpressionItem>
 
@@ -510,35 +509,36 @@ export type TemplateExpression = TemplateExpressionItem | ReadonlyArray<Template
 // =============================================================================
 
 const Proto = {
-  ...PipeInspectableProto,
-  ...YieldableProto,
-  [TypeId]: TypeId,
-  asEffect(this: Command) {
-    return ChildProcessSpawner.use((_) => _.spawn(this))
-  }
+  ...Effectable.Prototype<Command>({
+    label: "Command",
+    evaluate(fiber) {
+      return Context.getUnsafe(fiber.context, ChildProcessSpawner).spawn(this)
+    }
+  }),
+  [TypeId]: TypeId
 }
 
 /**
  * Check if a value is a `Command`.
  *
- * @since 4.0.0
  * @category Guards
+ * @since 4.0.0
  */
 export const isCommand = (u: unknown): u is Command => Predicate.hasProperty(u, TypeId)
 
 /**
  * Check if a command is a `StandardCommand`.
  *
- * @since 4.0.0
  * @category Guards
+ * @since 4.0.0
  */
 export const isStandardCommand = (command: Command): command is StandardCommand => command._tag === "StandardCommand"
 
 /**
  * Check if a command is a `PipedCommand`.
  *
- * @since 4.0.0
  * @category Guards
+ * @since 4.0.0
  */
 export const isPipedCommand = (command: Command): command is PipedCommand => command._tag === "PipedCommand"
 
@@ -577,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"
  *
@@ -591,8 +592,8 @@ const makePipedCommand = (
  * const cmd3 = ChildProcess.make("git", ["status"])
  * ```
  *
- * @since 4.0.0
  * @category Constructors
+ * @since 4.0.0
  */
 export const make: {
   /**
@@ -606,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"
    *
@@ -620,8 +622,8 @@ export const make: {
    * const cmd3 = ChildProcess.make("git", ["status"])
    * ```
    *
-   * @since 4.0.0
    * @category Constructors
+   * @since 4.0.0
    */
   (command: string, options?: CommandOptions): StandardCommand
   /**
@@ -635,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"
    *
@@ -649,8 +652,8 @@ export const make: {
    * const cmd3 = ChildProcess.make("git", ["status"])
    * ```
    *
-   * @since 4.0.0
    * @category Constructors
+   * @since 4.0.0
    */
   (command: string, args: ReadonlyArray<string>, options?: CommandOptions): StandardCommand
   /**
@@ -664,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"
    *
@@ -678,8 +682,8 @@ export const make: {
    * const cmd3 = ChildProcess.make("git", ["status"])
    * ```
    *
-   * @since 4.0.0
    * @category Constructors
+   * @since 4.0.0
    */
   (options: CommandOptions): (
     templates: TemplateStringsArray,
@@ -696,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"
    *
@@ -710,8 +715,8 @@ export const make: {
    * const cmd3 = ChildProcess.make("git", ["status"])
    * ```
    *
-   * @since 4.0.0
    * @category Constructors
+   * @since 4.0.0
    */
   (
     templates: TemplateStringsArray,
@@ -758,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"
  *
@@ -778,8 +784,8 @@ export const make: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const pipeTo: {
   /**
@@ -788,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"
    *
@@ -808,8 +815,8 @@ export const pipeTo: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   (that: Command, options?: PipeOptions): (self: Command) => PipedCommand
   /**
@@ -818,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"
    *
@@ -838,8 +846,8 @@ export const pipeTo: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   (self: Command, that: Command, options?: PipeOptions): PipedCommand
 } = dual(
@@ -852,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"
  *
@@ -865,8 +874,8 @@ export const pipeTo: {
  * // now prefixed will execute `time echo "foo"`
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const prefix: {
   /**
@@ -874,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"
    *
@@ -887,8 +897,8 @@ export const prefix: {
    * // now prefixed will execute `time echo "foo"`
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   (command: string, args?: ReadonlyArray<string>): (self: Command) => Command
   /**
@@ -896,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"
    *
@@ -909,8 +920,8 @@ export const prefix: {
    * // now prefixed will execute `time echo "foo"`
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   (
     templates: TemplateStringsArray,
@@ -921,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"
    *
@@ -934,8 +946,8 @@ export const prefix: {
    * // now prefixed will execute `time echo "foo"`
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   (self: Command, command: string, args?: ReadonlyArray<string>): Command
 } = function prefix(...args: Array<unknown>): any {
@@ -983,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"
  *
@@ -992,8 +1005,8 @@ const applyPrefix = (self: Command, prefixSpec: PrefixSpec): Command => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const setCwd: {
   /**
@@ -1001,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"
    *
@@ -1010,8 +1024,8 @@ export const setCwd: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   (cwd: string): (self: Command) => Command
   /**
@@ -1019,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"
    *
@@ -1028,8 +1043,8 @@ export const setCwd: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   (self: Command, cwd: string): Command
 } = dual(
@@ -1047,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"
  *
@@ -1060,16 +1077,18 @@ export const setCwd: {
  * )
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 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"
    *
@@ -1078,16 +1097,18 @@ export const setEnv: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   (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"
    *
@@ -1096,8 +1117,8 @@ export const setEnv: {
    * )
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   (self: Command, env: Record<string, string>): Command
 } = dual(
@@ -1128,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.
  *
- * @since 4.0.0
  * @category Utilities
+ * @since 4.0.0
  */
 export const parseFdName = (name: string): number | undefined => {
   const match = /^fd(\d+)$/.exec(name)
@@ -1141,8 +1162,8 @@ export const parseFdName = (name: string): number | undefined => {
 /**
  * Create an fd name from its numeric index.
  *
- * @since 4.0.0
  * @category Utilities
+ * @since 4.0.0
  */
 export const fdName = (fd: number): string => `fd${fd}`