effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/unstable/process/ChildProcess.ts

@@ -105,13 +105,14 @@ export type PipeToOption = "stdin" | `fd${number}`
  *
  * **Example** (Piping stderr between commands)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { ChildProcess } from "effect/unstable/process"
  *
  * // Pipe stderr instead of stdout
  * const pipeline = ChildProcess.make`my-program`.pipe(
  *   ChildProcess.pipeTo(ChildProcess.make`grep error`, { from: "stderr" })
  * )
+ * const result = [pipeline._tag, pipeline.options.from] // => ["PipedCommand", "stderr"]
  * ```
  *
  * @category options
@@ -383,6 +384,11 @@ export interface CommandOptions extends KillOptions {
    * 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.
+   *
+   * **Gotchas**
+   *
+   * Without `extendEnv: true`, providing `env` replaces the inherited child
+   * environment. The child will not receive `PATH` unless `env` includes it.
    */
   readonly env?: Record<string, string | undefined> | undefined
   /**
@@ -392,7 +398,9 @@ export interface CommandOptions extends KillOptions {
    *
    * **Details**
    *
-   * If set to `false`, only the value of `env` is used.
+   * If set to `false` and `env` is provided, only the value of `env` is used.
+   *
+   * @default false
    */
   readonly extendEnv?: boolean | undefined
   /**
@@ -450,7 +458,7 @@ export interface CommandOptions extends KillOptions {
    *
    * **Example** (Configuring additional file descriptors)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { ChildProcess } from "effect/unstable/process"
    *
    * // Output fd3 - read data from child
@@ -466,6 +474,8 @@ export interface CommandOptions extends KillOptions {
    *     fd3: { type: "input" }
    *   }
    * })
+   * const result = [cmd1.options.additionalFds?.fd3?.type, cmd2.options.additionalFds?.fd3?.type]
+   * result // => ["output", "input"]
    * ```
    */
   readonly additionalFds?: Record<`fd${number}`, AdditionalFdConfig> | undefined
@@ -564,7 +574,7 @@ const makePipedCommand = (
  *
  * **Example** (Creating commands)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { ChildProcess } from "effect/unstable/process"
  *
  * // Template literal form
@@ -575,6 +585,8 @@ const makePipedCommand = (
  *
  * // Array form
  * const cmd3 = ChildProcess.make("git", ["status"])
+ *
+ * const result = [cmd1.command, cmd2.options.cwd, cmd3.args[0]] // => ["echo", "/tmp", "status"]
  * ```
  *
  * @category constructors
@@ -596,7 +608,7 @@ export const make: {
    *
    * **Example** (Creating commands)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { ChildProcess } from "effect/unstable/process"
    *
    * // Template literal form
@@ -607,6 +619,8 @@ export const make: {
    *
    * // Array form
    * const cmd3 = ChildProcess.make("git", ["status"])
+   *
+   * const result = [cmd1.command, cmd2.options.cwd, cmd3.args[0]] // => ["echo", "/tmp", "status"]
    * ```
    *
    * @category constructors
@@ -628,7 +642,7 @@ export const make: {
    *
    * **Example** (Creating commands)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { ChildProcess } from "effect/unstable/process"
    *
    * // Template literal form
@@ -639,6 +653,8 @@ export const make: {
    *
    * // Array form
    * const cmd3 = ChildProcess.make("git", ["status"])
+   *
+   * const result = [cmd1.command, cmd2.options.cwd, cmd3.args[0]] // => ["echo", "/tmp", "status"]
    * ```
    *
    * @category constructors
@@ -660,7 +676,7 @@ export const make: {
    *
    * **Example** (Creating commands)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { ChildProcess } from "effect/unstable/process"
    *
    * // Template literal form
@@ -671,6 +687,8 @@ export const make: {
    *
    * // Array form
    * const cmd3 = ChildProcess.make("git", ["status"])
+   *
+   * const result = [cmd1.command, cmd2.options.cwd, cmd3.args[0]] // => ["echo", "/tmp", "status"]
    * ```
    *
    * @category constructors
@@ -695,7 +713,7 @@ export const make: {
    *
    * **Example** (Creating commands)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { ChildProcess } from "effect/unstable/process"
    *
    * // Template literal form
@@ -706,6 +724,8 @@ export const make: {
    *
    * // Array form
    * const cmd3 = ChildProcess.make("git", ["status"])
+   *
+   * const result = [cmd1.command, cmd2.options.cwd, cmd3.args[0]] // => ["echo", "/tmp", "status"]
    * ```
    *
    * @category constructors
@@ -760,7 +780,7 @@ export const make: {
  *
  * **Example** (Piping command output)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { ChildProcess } from "effect/unstable/process"
  *
  * // Pipe stdout (default)
@@ -777,6 +797,9 @@ export const make: {
  * const pipeline3 = ChildProcess.make`my-program`.pipe(
  *   ChildProcess.pipeTo(ChildProcess.make`tee output.log`, { from: "all" })
  * )
+ *
+ * const result = [pipeline1._tag, pipeline2.options.from, pipeline3.options.from]
+ * result // => ["PipedCommand", "stderr", "all"]
  * ```
  *
  * @category combinators
@@ -793,7 +816,7 @@ export const pipeTo: {
    *
    * **Example** (Piping command output)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { ChildProcess } from "effect/unstable/process"
    *
    * // Pipe stdout (default)
@@ -810,6 +833,9 @@ export const pipeTo: {
    * const pipeline3 = ChildProcess.make`my-program`.pipe(
    *   ChildProcess.pipeTo(ChildProcess.make`tee output.log`, { from: "all" })
    * )
+   *
+   * const result = [pipeline1._tag, pipeline2.options.from, pipeline3.options.from]
+   * result // => ["PipedCommand", "stderr", "all"]
    * ```
    *
    * @category combinators
@@ -826,7 +852,7 @@ export const pipeTo: {
    *
    * **Example** (Piping command output)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { ChildProcess } from "effect/unstable/process"
    *
    * // Pipe stdout (default)
@@ -843,6 +869,9 @@ export const pipeTo: {
    * const pipeline3 = ChildProcess.make`my-program`.pipe(
    *   ChildProcess.pipeTo(ChildProcess.make`tee output.log`, { from: "all" })
    * )
+   *
+   * const result = [pipeline1._tag, pipeline2.options.from, pipeline3.options.from]
+   * result // => ["PipedCommand", "stderr", "all"]
    * ```
    *
    * @category combinators
@@ -863,7 +892,7 @@ export const pipeTo: {
  *
  * **Example** (Prefixing commands)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { ChildProcess } from "effect/unstable/process"
  *
  * const command = ChildProcess.make`echo "foo"`
@@ -873,6 +902,8 @@ export const pipeTo: {
  * )
  *
  * // now prefixed will execute `time echo "foo"`
+ * const result = prefixed._tag === "StandardCommand" ? `${prefixed.command} ${prefixed.args[0]}` : prefixed._tag
+ * result // => "time echo"
  * ```
  *
  * @category combinators
@@ -888,7 +919,7 @@ export const prefix: {
    *
    * **Example** (Prefixing commands)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { ChildProcess } from "effect/unstable/process"
    *
    * const command = ChildProcess.make`echo "foo"`
@@ -898,6 +929,8 @@ export const prefix: {
    * )
    *
    * // now prefixed will execute `time echo "foo"`
+   * const result = prefixed._tag === "StandardCommand" ? `${prefixed.command} ${prefixed.args[0]}` : prefixed._tag
+   * result // => "time echo"
    * ```
    *
    * @category combinators
@@ -913,7 +946,7 @@ export const prefix: {
    *
    * **Example** (Prefixing commands)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { ChildProcess } from "effect/unstable/process"
    *
    * const command = ChildProcess.make`echo "foo"`
@@ -923,6 +956,8 @@ export const prefix: {
    * )
    *
    * // now prefixed will execute `time echo "foo"`
+   * const result = prefixed._tag === "StandardCommand" ? `${prefixed.command} ${prefixed.args[0]}` : prefixed._tag
+   * result // => "time echo"
    * ```
    *
    * @category combinators
@@ -941,7 +976,7 @@ export const prefix: {
    *
    * **Example** (Prefixing commands)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { ChildProcess } from "effect/unstable/process"
    *
    * const command = ChildProcess.make`echo "foo"`
@@ -951,6 +986,8 @@ export const prefix: {
    * )
    *
    * // now prefixed will execute `time echo "foo"`
+   * const result = prefixed._tag === "StandardCommand" ? `${prefixed.command} ${prefixed.args[0]}` : prefixed._tag
+   * result // => "time echo"
    * ```
    *
    * @category combinators
@@ -1006,12 +1043,13 @@ const applyPrefix = (self: Command, prefixSpec: PrefixSpec): Command => {
  *
  * **Example** (Setting command working directories)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { ChildProcess } from "effect/unstable/process"
  *
  * const cmd = ChildProcess.make`ls -la`.pipe(
  *   ChildProcess.setCwd("/tmp")
  * )
+ * const result = cmd._tag === "StandardCommand" && cmd.options.cwd // => "/tmp"
  * ```
  *
  * @category combinators
@@ -1027,12 +1065,13 @@ export const setCwd: {
    *
    * **Example** (Setting command working directories)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { ChildProcess } from "effect/unstable/process"
    *
    * const cmd = ChildProcess.make`ls -la`.pipe(
    *   ChildProcess.setCwd("/tmp")
    * )
+   * const result = cmd._tag === "StandardCommand" && cmd.options.cwd // => "/tmp"
    * ```
    *
    * @category combinators
@@ -1048,12 +1087,13 @@ export const setCwd: {
    *
    * **Example** (Setting command working directories)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { ChildProcess } from "effect/unstable/process"
    *
    * const cmd = ChildProcess.make`ls -la`.pipe(
    *   ChildProcess.setCwd("/tmp")
    * )
+   * const result = cmd._tag === "StandardCommand" && cmd.options.cwd // => "/tmp"
    * ```
    *
    * @category combinators
@@ -1084,12 +1124,13 @@ export const setCwd: {
  *
  * **Example** (Setting command environment variables)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { ChildProcess } from "effect/unstable/process"
  *
  * const cmd = ChildProcess.make`node script.js`.pipe(
  *   ChildProcess.setEnv({ NODE_ENV: "test" })
  * )
+ * const result = cmd._tag === "StandardCommand" && cmd.options.env?.NODE_ENV // => "test"
  * ```
  *
  * @category combinators
@@ -1106,12 +1147,13 @@ export const setEnv: {
    *
    * **Example** (Setting command environment variables)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { ChildProcess } from "effect/unstable/process"
    *
    * const cmd = ChildProcess.make`node script.js`.pipe(
    *   ChildProcess.setEnv({ NODE_ENV: "test" })
    * )
+   * const result = cmd._tag === "StandardCommand" && cmd.options.env?.NODE_ENV // => "test"
    * ```
    *
    * @category combinators
@@ -1128,12 +1170,13 @@ export const setEnv: {
    *
    * **Example** (Setting command environment variables)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { ChildProcess } from "effect/unstable/process"
    *
    * const cmd = ChildProcess.make`node script.js`.pipe(
    *   ChildProcess.setEnv({ NODE_ENV: "test" })
    * )
+   * const result = cmd._tag === "StandardCommand" && cmd.options.env?.NODE_ENV // => "test"
    * ```
    *
    * @category combinators

package/src/unstable/process/ChildProcessSpawner.ts

@@ -166,20 +166,31 @@ export interface ChildProcessHandle {
    *
    * **Example** (Temporarily unreferencing a child process)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect } from "effect"
-   * import { NodeServices } from "@effect/platform-node"
-   * import { ChildProcess } from "effect/unstable/process"
+   * import type { ChildProcessSpawner } from "effect/unstable/process"
    *
-   * const program = Effect.gen(function*() {
-   *   const handle = yield* ChildProcess.make`./server`
-   *   const reref = yield* handle.unref
+   * let referenced = true
+   *
+   * const unref: ChildProcessSpawner.ChildProcessHandle["unref"] = Effect.sync(() => {
+   *   referenced = false
+   *   const reref: ChildProcessSpawner.Reref = Effect.sync(() => {
+   *     referenced = true
+   *   })
+   *   return reref
+   * })
    *
-   *   yield* Effect.sleep("1 second")
+   * const program = Effect.gen(function*() {
+   *   const states = [] as Array<boolean>
+   *   const reref = yield* unref
+   *   states.push(referenced)
    *
    *   yield* reref
-   *   return yield* handle.exitCode
-   * }).pipe(Effect.scoped, Effect.provide(NodeServices.layer))
+   *   states.push(referenced)
+   *   return states
+   * })
+   *
+   * Effect.runSync(program) // => [false, true]
    * ```
    */
   readonly unref: Effect.Effect<Reref, PlatformError.PlatformError>
@@ -206,7 +217,7 @@ export const makeHandle = (params: Omit<ChildProcessHandle, typeof HandleTypeId>
  * Creates a `ChildProcessSpawner` service from a `spawn` function, deriving
  * helpers for exit codes and output collection from that implementation.
  *
- * @category models
+ * @category constructors
  * @since 4.0.0
  */
 export const make = (spawn: ChildProcessSpawner["Service"]["spawn"]): ChildProcessSpawner["Service"] => {

package/src/unstable/reactivity/AsyncResult.ts

@@ -142,7 +142,7 @@ const ResultProto = {
 /**
  * Returns whether an `AsyncResult` is currently waiting for an asynchronous computation or refresh to finish.
  *
- * @category refinements
+ * @category predicates
  * @since 4.0.0
  */
 export const isWaiting = <A, E>(result: AsyncResult<A, E>): boolean => result.waiting
@@ -194,7 +194,7 @@ export const waitingFrom = <A, E>(previous: Option.Option<AsyncResult<A, E>>): A
 /**
  * Returns `true` when an `AsyncResult` is in the `Initial` state.
  *
- * @category refinements
+ * @category guards
  * @since 4.0.0
  */
 export const isInitial = <A, E>(result: AsyncResult<A, E>): result is Initial<A, E> => result._tag === "Initial"
@@ -202,7 +202,7 @@ export const isInitial = <A, E>(result: AsyncResult<A, E>): result is Initial<A,
 /**
  * Returns `true` when an `AsyncResult` is either `Success` or `Failure`.
  *
- * @category refinements
+ * @category guards
  * @since 4.0.0
  */
 export const isNotInitial = <A, E>(result: AsyncResult<A, E>): result is Success<A, E> | Failure<A, E> =>
@@ -236,7 +236,7 @@ export interface Success<A, E = never> extends AsyncResult.Proto<A, E> {
 /**
  * Returns `true` when an `AsyncResult` is a `Success`.
  *
- * @category refinements
+ * @category guards
  * @since 4.0.0
  */
 export const isSuccess = <A, E>(result: AsyncResult<A, E>): result is Success<A, E> => result._tag === "Success"
@@ -274,7 +274,7 @@ export interface Failure<A, E = never> extends AsyncResult.Proto<A, E> {
 /**
  * Returns `true` when an `AsyncResult` is a `Failure`.
  *
- * @category refinements
+ * @category guards
  * @since 4.0.0
  */
 export const isFailure = <A, E>(result: AsyncResult<A, E>): result is Failure<A, E> => result._tag === "Failure"
@@ -282,7 +282,7 @@ export const isFailure = <A, E>(result: AsyncResult<A, E>): result is Failure<A,
 /**
  * Returns `true` when an `AsyncResult` is a `Failure` whose cause contains only interruptions.
  *
- * @category refinements
+ * @category guards
  * @since 4.0.0
  */
 export const isInterrupted = <A, E>(result: AsyncResult<A, E>): result is Failure<A, E> =>
@@ -865,7 +865,7 @@ export const builder = <A extends AsyncResult<any, any>>(self: A): Builder<
 /**
  * Type marker used by `Builder` to track whether defect failures still need to be handled.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export interface Defect {
@@ -875,7 +875,7 @@ export interface Defect {
 /**
  * Type marker used by `Builder` to track whether interrupt failures still need to be handled.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export interface Interrupt {
@@ -1101,7 +1101,7 @@ export const Schema = <
     [success_, Schema_.Cause(error, Schema_.Defect())],
     ([value, cause]) => (input, ast, options) => {
       if (!isAsyncResult(input)) {
-        return Effect.fail(new SchemaIssue.InvalidType(ast, Option.some(input)))
+        return Effect.fail(new SchemaIssue.InvalidType(ast))
       }
       switch (input._tag) {
         case "Initial":
@@ -1111,8 +1111,7 @@ export const Schema = <
             SchemaParser.decodeUnknownEffect(value)(input.value, options),
             {
               onSuccess: (value) => success(value, input),
-              onFailure: (issue) =>
-                new SchemaIssue.Composite(ast, Option.some(input), [new SchemaIssue.Pointer(["value"], issue)])
+              onFailure: (issue) => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["value"], issue)])
             }
           )
         case "Failure": {
@@ -1123,7 +1122,7 @@ export const Schema = <
                 {
                   onSuccess: (value) => Option.some(success<A["Type"], E["Type"]>(value, ps)),
                   onFailure: (issue) =>
-                    new SchemaIssue.Composite(ast, Option.some(input), [
+                    new SchemaIssue.Composite(ast, [
                       new SchemaIssue.Pointer(["previousSuccess", "value"], issue)
                     ])
                 }
@@ -1133,7 +1132,7 @@ export const Schema = <
           )
           const causeEffect = Effect.mapErrorEager(
             SchemaParser.decodeUnknownEffect(cause)(input.cause, options),
-            (issue) => new SchemaIssue.Composite(ast, Option.some(input), [new SchemaIssue.Pointer(["cause"], issue)])
+            (issue) => new SchemaIssue.Composite(ast, [new SchemaIssue.Pointer(["cause"], issue)])
           )
           return Effect.flatMapEager(
             prevSuccessEffect,