effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/unstable/process/ChildProcess.ts

@@ -56,10 +56,7 @@ import { type ChildProcessHandle, ChildProcessSpawner } from "./ChildProcessSpaw
 const TypeId = "~effect/unstable/process/ChildProcess"
 
 /**
- * A command that can be executed as a child process.
- *
- * Commands are built using `make` and can be combined using `pipeTo`.
- * They are executed using `exec` or `spawn`.
+ * A command that can be built using `make`, combined using `pipeTo`, and executed using `exec` or `spawn`.
  *
  * @category models
  * @since 4.0.0
@@ -110,6 +107,8 @@ export interface PipedCommand extends
 /**
  * Specifies which stream to pipe from the source subprocess.
  *
+ * **Details**
+ *
  * - `"stdout"`: Pipe stdout from the source (default)
  * - `"stderr"`: Pipe stderr from the source
  * - `"all"`: Pipe both stdout and stderr interleaved
@@ -123,6 +122,8 @@ export type PipeFromOption = "stdout" | "stderr" | "all" | `fd${number}`
 /**
  * Specifies which input to pipe to on the destination subprocess.
  *
+ * **Details**
+ *
  * - `"stdin"`: Pipe to stdin of the destination (default)
  * - `` `fd${number}` ``: Pipe to a custom file descriptor (e.g., `"fd3"`)
  *
@@ -152,6 +153,8 @@ export interface PipeOptions {
   /**
    * Which stream to pipe from the source subprocess.
    *
+   * **Details**
+   *
    * - `"stdout"` (default): Pipe stdout from the source
    * - `"stderr"`: Pipe stderr from the source
    * - `"all"`: Pipe both stdout and stderr interleaved
@@ -162,6 +165,8 @@ export interface PipeOptions {
   /**
    * Which input to pipe to on the destination subprocess.
    *
+   * **Details**
+   *
    * - `"stdin"` (default): Pipe to stdin of the destination
    * - `"fd3"`, `"fd4"`, etc.: Pipe to a custom file descriptor
    */
@@ -267,18 +272,14 @@ export type Encoding =
  */
 export interface KillOptions {
   /**
-   * The default signal used to terminate the child process.
-   *
-   * Defaults to `"SIGTERM"`.
+   * The default signal used to terminate the child process. Defaults to `"SIGTERM"`.
    */
   readonly killSignal?: Signal | undefined
   /**
    * The duration of time to wait after the child process has been terminated
    * before forcefully killing the child process by sending it the `"SIGKILL"`
-   * signal.
-   *
-   * Defaults to `undefined`, which means that no timeout will be enforced by
-   * default.
+   * signal. Defaults to `undefined`, which means that no timeout will be
+   * enforced by default.
    */
   readonly forceKillAfter?: Duration.Input | undefined
 }
@@ -293,6 +294,8 @@ export interface StdinConfig {
   /**
    * The configuration for the standard input stream of the child process.
    *
+   * **Details**
+   *
    * Can be a string indicating how the operating system should configure the
    * pipe established between the child process `stdin` and the parent process.
    *
@@ -304,15 +307,11 @@ export interface StdinConfig {
   readonly stream: CommandInput
   /**
    * Whether or not the child process `stdin` should be closed after the input
-   * stream is finished.
-   *
-   * Defaults to `true`.
+   * stream is finished. Defaults to `true`.
    */
   readonly endOnDone?: boolean | undefined
   /**
-   * The buffer encoding to use to decode string chunks.
-   *
-   * Defaults to `utf-8`.
+   * The buffer encoding to use to decode string chunks. Defaults to `utf-8`.
    */
   readonly encoding?: Encoding | undefined
 }
@@ -325,7 +324,9 @@ export interface StdinConfig {
  */
 export interface StdoutConfig {
   /**
-   * The configuration for the standard ouput stream of the child process.
+   * The configuration for the standard output stream of the child process.
+   *
+   * **Details**
    *
    * Can be a string indicating how the operating system should configure the
    * pipe established between the child process `stdout` and the parent process.
@@ -346,7 +347,9 @@ export interface StdoutConfig {
  */
 export interface StderrConfig {
   /**
-   * The configuration for the standard ouput stream of the child process.
+   * The configuration for the standard error stream of the child process.
+   *
+   * **Details**
    *
    * Can be a string indicating how the operating system should configure the
    * pipe established between the child process `stderr` and the parent process.
@@ -407,6 +410,8 @@ export interface CommandOptions extends KillOptions {
   /**
    * The environment of the child process.
    *
+   * **Details**
+   *
    * If `extendEnv` is set to `true`, the value of `env` will be merged with
    * the value of `globalThis.process.env`, prioritizing the values in `env`
    * when conflicts exist.
@@ -417,6 +422,8 @@ export interface CommandOptions extends KillOptions {
    * as the values in `globalThis.process.env`, prioritizing the values in `env`
    * when conflicts exist.
    *
+   * **Details**
+   *
    * If set to `false`, only the value of `env` is used.
    */
   readonly extendEnv?: boolean | undefined
@@ -424,9 +431,13 @@ export interface CommandOptions extends KillOptions {
    * If set to `true`, runs the command inside of a shell, defaulting to `/bin/sh`
    * on UNIX systems and `cmd.exe` on Windows.
    *
+   * **Details**
+   *
    * Can also be set to a string representing the absolute path to a shell to
    * use on the system.
    *
+   * **Gotchas**
+   *
    * It is generally disadvised to use this option.
    */
   readonly shell?: boolean | string | undefined
@@ -434,6 +445,8 @@ export interface CommandOptions extends KillOptions {
    * If set to `true`, the child process will run independently of the parent
    * process.
    *
+   * **Details**
+   *
    * The specific behavior of this option depends upon the platform. For
    * example, the NodeJS documentation outlines the differences between Windows
    * and non-Windows platforms.
@@ -459,6 +472,8 @@ export interface CommandOptions extends KillOptions {
    * Additional file descriptors to expose to the child process beyond `stdin` /
    * `stdout` / `stderr`.
    *
+   * **Details**
+   *
    * Keys must be in the format `"fd3"`, `"fd4"`, etc. with a file descriptor
    * index >= 3.
    *
@@ -569,6 +584,8 @@ const makePipedCommand = (
 /**
  * Create a command from a template literal, options + template, or array form.
  *
+ * **Details**
+ *
  * This function supports three calling conventions:
  * 1. Template literal: `make\`npm run build\``
  * 2. Options + template literal: `make({ cwd: "/app" })\`npm run build\``
@@ -599,6 +616,8 @@ export const make: {
   /**
    * Create a command from a template literal, options + template, or array form.
    *
+   * **Details**
+   *
    * This function supports three calling conventions:
    * 1. Template literal: `make\`npm run build\``
    * 2. Options + template literal: `make({ cwd: "/app" })\`npm run build\``
@@ -629,6 +648,8 @@ export const make: {
   /**
    * Create a command from a template literal, options + template, or array form.
    *
+   * **Details**
+   *
    * This function supports three calling conventions:
    * 1. Template literal: `make\`npm run build\``
    * 2. Options + template literal: `make({ cwd: "/app" })\`npm run build\``
@@ -659,6 +680,8 @@ export const make: {
   /**
    * Create a command from a template literal, options + template, or array form.
    *
+   * **Details**
+   *
    * This function supports three calling conventions:
    * 1. Template literal: `make\`npm run build\``
    * 2. Options + template literal: `make({ cwd: "/app" })\`npm run build\``
@@ -692,6 +715,8 @@ export const make: {
   /**
    * Create a command from a template literal, options + template, or array form.
    *
+   * **Details**
+   *
    * This function supports three calling conventions:
    * 1. Template literal: `make\`npm run build\``
    * 2. Options + template literal: `make({ cwd: "/app" })\`npm run build\``
@@ -760,6 +785,8 @@ export const make: {
 /**
  * Pipe the output of one command to the input of another.
  *
+ * **Details**
+ *
  * By default, pipes `stdout` from the source to `stdin` of the destination.
  * Use the `options` parameter to customize which streams are connected.
  *
@@ -791,6 +818,8 @@ export const pipeTo: {
   /**
    * Pipe the output of one command to the input of another.
    *
+   * **Details**
+   *
    * By default, pipes `stdout` from the source to `stdin` of the destination.
    * Use the `options` parameter to customize which streams are connected.
    *
@@ -822,6 +851,8 @@ export const pipeTo: {
   /**
    * Pipe the output of one command to the input of another.
    *
+   * **Details**
+   *
    * By default, pipes `stdout` from the source to `stdin` of the destination.
    * Use the `options` parameter to customize which streams are connected.
    *
@@ -858,6 +889,8 @@ export const pipeTo: {
 /**
  * Prefix a command with another command.
  *
+ * **Details**
+ *
  * For pipelines, only the leftmost command is prefixed.
  *
  * **Example** (Prefixing commands)
@@ -881,6 +914,8 @@ export const prefix: {
   /**
    * Prefix a command with another command.
    *
+   * **Details**
+   *
    * For pipelines, only the leftmost command is prefixed.
    *
    * **Example** (Prefixing commands)
@@ -904,6 +939,8 @@ export const prefix: {
   /**
    * Prefix a command with another command.
    *
+   * **Details**
+   *
    * For pipelines, only the leftmost command is prefixed.
    *
    * **Example** (Prefixing commands)
@@ -930,6 +967,8 @@ export const prefix: {
   /**
    * Prefix a command with another command.
    *
+   * **Details**
+   *
    * For pipelines, only the leftmost command is prefixed.
    *
    * **Example** (Prefixing commands)
@@ -993,6 +1032,8 @@ const applyPrefix = (self: Command, prefixSpec: PrefixSpec): Command => {
 /**
  * Set the current working directory for a command.
  *
+ * **Details**
+ *
  * For pipelines, applies to each command in the pipeline.
  *
  * **Example** (Setting command working directories)
@@ -1012,6 +1053,8 @@ export const setCwd: {
   /**
    * Set the current working directory for a command.
    *
+   * **Details**
+   *
    * For pipelines, applies to each command in the pipeline.
    *
    * **Example** (Setting command working directories)
@@ -1031,6 +1074,8 @@ export const setCwd: {
   /**
    * Set the current working directory for a command.
    *
+   * **Details**
+   *
    * For pipelines, applies to each command in the pipeline.
    *
    * **Example** (Setting command working directories)
@@ -1065,6 +1110,8 @@ export const setCwd: {
  * Adds environment variables to a command, merging them with any existing
  * command environment and overriding duplicate keys.
  *
+ * **Details**
+ *
  * For pipelines, applies to each command in the pipeline.
  *
  * **Example** (Setting command environment variables)
@@ -1085,6 +1132,8 @@ export const setEnv: {
    * Adds environment variables to a command, merging them with any existing
    * command environment and overriding duplicate keys.
    *
+   * **Details**
+   *
    * For pipelines, applies to each command in the pipeline.
    *
    * **Example** (Setting command environment variables)
@@ -1105,6 +1154,8 @@ export const setEnv: {
    * Adds environment variables to a command, merging them with any existing
    * command environment and overriding duplicate keys.
    *
+   * **Details**
+   *
    * For pipelines, applies to each command in the pipeline.
    *
    * **Example** (Setting command environment variables)

package/src/unstable/process/ChildProcessSpawner.ts

@@ -53,6 +53,8 @@ export const ProcessId: Brand.Constructor<ProcessId> = Brand.nominal<ProcessId>(
  * An `Effect` that adds an unrefed child process back into the parent
  * process's reference count.
  *
+ * **Details**
+ *
  * This value is returned by `ChildProcessHandle.unref` and can be run later to
  * restore the default behavior where the child process keeps the parent
  * process alive.
@@ -89,6 +91,8 @@ export interface ChildProcessHandle {
   /**
    * Kills the child process with the provided signal.
    *
+   * **Details**
+   *
    * If no signal option is provided, the signal defaults to `SIGTERM`.
    */
   readonly kill: (options?: KillOptions | undefined) => Effect.Effect<void, PlatformError.PlatformError>
@@ -99,15 +103,19 @@ export interface ChildProcessHandle {
   /**
    * The standard output stream for the child process.
    *
-   * Note: Using alongside `all` may cause interleaving of output and unexpected
-   * results.
+   * **Gotchas**
+   *
+   * Using this stream alongside `all` may cause interleaving of output and
+   * unexpected results.
    */
   readonly stdout: Stream.Stream<Uint8Array, PlatformError.PlatformError>
   /**
    * The standard error stream for the child process.
    *
-   * Note: Using alongside `all` may cause interleaving of output and unexpected
-   * results.
+   * **Gotchas**
+   *
+   * Using this stream alongside `all` may cause interleaving of output and
+   * unexpected results.
    */
   readonly stderr: Stream.Stream<Uint8Array, PlatformError.PlatformError>
   /**
@@ -119,6 +127,8 @@ export interface ChildProcessHandle {
    * Get an input `Sink` for writing to a file descriptor configured via
    * `ChildProcessOptions.additionalFds`.
    *
+   * **Details**
+   *
    * If a file descriptor is accessed that was not configured, returns a drain
    * `Sink`.
    */
@@ -127,6 +137,8 @@ export interface ChildProcessHandle {
    * Get an output `Stream` for reading from a file descriptor configured via
    * `ChildProcessOptions.additionalFds`.
    *
+   * **Details**
+   *
    * If a file descriptor is accessed that was not configured, returns an empty
    * `Stream`.
    */
@@ -134,6 +146,8 @@ export interface ChildProcessHandle {
   /**
    * Allows the parent process to exit independently of this child process.
    *
+   * **Details**
+   *
    * Running this `Effect` removes this child process from the parent process's
    * reference count, so the parent process is allowed to exit without waiting
    * for the child process to finish.
@@ -141,6 +155,8 @@ export interface ChildProcessHandle {
    * The returned `Reref` effect adds the child process back into the parent
    * process's reference count when run, restoring the default behavior.
    *
+   * **Gotchas**
+   *
    * This is the only supported way to re-reference a child process after it
    * has been unrefed.
    *