effect 4.0.5 → 4.0.7

package/src/persistence/UserDirectories.ts

@@ -0,0 +1,273 @@
+/**
+ * Well-known directories for an application's persisted data.
+ *
+ * `UserDirectories` resolves where an application should keep its
+ * configuration, data, cache and state, following the conventions of the host
+ * platform. The resolved directories are what `KeyValueStore.layerFileSystem`
+ * expects.
+ *
+ * **Example** (Backing a key-value store with the config directory)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Layer } from "effect"
+ * import { KeyValueStore, UserDirectories } from "effect/persistence"
+ *
+ * const StoreLive = Layer.unwrap(
+ *   Effect.gen(function*() {
+ *     const dirs = yield* UserDirectories.UserDirectories
+ *     return KeyValueStore.layerFileSystem(yield* dirs.config("myapp"))
+ *   })
+ * ).pipe(Layer.provide(UserDirectories.layer))
+ * ```
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+import * as Config from "../Config.ts"
+import * as Context from "../Context.ts"
+import * as Effect from "../Effect.ts"
+import * as Layer from "../Layer.ts"
+import * as PlatformError from "../PlatformError.ts"
+
+/**
+ * Identifies a `UserDirectories` service.
+ *
+ * @stability unstable
+ * @category type ids
+ * @since 4.0.0
+ */
+export const TypeId: TypeId = "~effect/persistence/UserDirectories"
+
+/**
+ * Type of the `UserDirectories` type id.
+ *
+ * @stability unstable
+ * @category type ids
+ * @since 4.0.0
+ */
+export type TypeId = "~effect/persistence/UserDirectories"
+
+/**
+ * Resolves the directories where an application keeps its files.
+ *
+ * **Details**
+ *
+ * An absolute `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_CACHE_HOME` or
+ * `XDG_STATE_HOME` is used on every platform, with the application name
+ * appended. A relative one is ignored. Otherwise the native location is used:
+ *
+ * | kind   | Windows                                | macOS                          | other            |
+ * | ------ | -------------------------------------- | ------------------------------ | ---------------- |
+ * | config | `%APPDATA%`                            | `~/Library/Application Support` | `~/.config`      |
+ * | data   | `%APPDATA%`                            | `~/Library/Application Support` | `~/.local/share` |
+ * | cache  | `%LOCALAPPDATA%`, then `\Cache` suffix | `~/Library/Caches`             | `~/.cache`       |
+ * | state  | `%LOCALAPPDATA%`                       | `~/Library/Application Support` | `~/.local/state` |
+ *
+ * `APPDATA` and `LOCALAPPDATA` are used when absolute and otherwise replaced
+ * by `%USERPROFILE%\AppData\Roaming` and `%USERPROFILE%\AppData\Local`.
+ *
+ * **Gotchas**
+ *
+ * `config` and `data` resolve to the same directory on Windows and macOS, and
+ * `state` joins them on macOS. That is the native convention. Keep each kind
+ * in its own subdirectory when the same application uses more than one, since
+ * `KeyValueStore.layerFileSystem` clears a directory recursively.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface UserDirectories {
+  readonly [TypeId]: TypeId
+  /**
+   * The current user's home directory.
+   */
+  readonly home: Effect.Effect<string, PlatformError.PlatformError>
+  /**
+   * Where `appName` keeps its settings.
+   */
+  readonly config: (appName: string) => Effect.Effect<string, PlatformError.PlatformError>
+  /**
+   * Where `appName` keeps data it cannot regenerate.
+   */
+  readonly data: (appName: string) => Effect.Effect<string, PlatformError.PlatformError>
+  /**
+   * Where `appName` keeps data it can regenerate.
+   */
+  readonly cache: (appName: string) => Effect.Effect<string, PlatformError.PlatformError>
+  /**
+   * Where `appName` keeps logs, history and other state that is not user data.
+   */
+  readonly state: (appName: string) => Effect.Effect<string, PlatformError.PlatformError>
+}
+
+/**
+ * Service tag for the user directory resolver.
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export const UserDirectories: Context.Service<UserDirectories, UserDirectories> = Context.Service<UserDirectories>(
+  TypeId
+)
+
+type Kind = "config" | "data" | "cache" | "state"
+
+type Environment = {
+  readonly home: string | undefined
+  readonly xdg: string | undefined
+  readonly appData: string | undefined
+}
+
+const isAbsolute = (platform: string, path: string): boolean =>
+  platform === "win32" ? /^([a-zA-Z]:)?[\\/]/.test(path) : path.startsWith("/")
+
+const join = (platform: string, base: string, ...segments: ReadonlyArray<string>): string =>
+  platform === "win32"
+    ? [base.replace(/[\\/]+$/, ""), ...segments].join("\\")
+    : [base.replace(/\/+$/, ""), ...segments].join("/")
+
+const xdgVariable: Record<Kind, string> = {
+  config: "XDG_CONFIG_HOME",
+  data: "XDG_DATA_HOME",
+  cache: "XDG_CACHE_HOME",
+  state: "XDG_STATE_HOME"
+}
+
+const windowsBase = (kind: Kind, env: Environment): string | undefined => {
+  if (env.appData !== undefined && isAbsolute("win32", env.appData)) {
+    return env.appData
+  }
+  if (env.home === undefined) {
+    return undefined
+  }
+  return join("win32", env.home, "AppData", kind === "config" || kind === "data" ? "Roaming" : "Local")
+}
+
+const posixBase = (platform: string, kind: Kind, home: string): string => {
+  if (platform === "darwin") {
+    return join(platform, home, "Library", kind === "cache" ? "Caches" : "Application Support")
+  }
+  switch (kind) {
+    case "config":
+      return join(platform, home, ".config")
+    case "data":
+      return join(platform, home, ".local", "share")
+    case "cache":
+      return join(platform, home, ".cache")
+    case "state":
+      return join(platform, home, ".local", "state")
+  }
+}
+
+const resolve = (platform: string, kind: Kind, appName: string, env: Environment): string | undefined => {
+  if (env.xdg !== undefined && isAbsolute(platform, env.xdg)) {
+    return join(platform, env.xdg, appName)
+  }
+  if (platform === "win32") {
+    const base = windowsBase(kind, env)
+    if (base === undefined) {
+      return undefined
+    }
+    return kind === "cache" ? join(platform, base, appName, "Cache") : join(platform, base, appName)
+  }
+  if (env.home === undefined) {
+    return undefined
+  }
+  return join(platform, posixBase(platform, kind, env.home), appName)
+}
+
+/**
+ * Creates a resolver that reads the environment from the current
+ * `ConfigProvider` on every call, using the conventions of `platform`, which
+ * defaults to the host platform.
+ *
+ * **Example** (Resolving for another platform)
+ *
+ * ```ts import.meta.vitest
+ * import { ConfigProvider, Effect } from "effect"
+ * import { UserDirectories } from "effect/persistence"
+ *
+ * const dirs = UserDirectories.make({ platform: "darwin" })
+ *
+ * const program = dirs.cache("myapp").pipe(
+ *   Effect.provideService(
+ *     ConfigProvider.ConfigProvider,
+ *     ConfigProvider.fromEnv({ env: { HOME: "/Users/ada" } })
+ *   )
+ * )
+ *
+ * await Effect.runPromise(program) // => "/Users/ada/Library/Caches/myapp"
+ * ```
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const make = (options?: {
+  readonly platform?: string | undefined
+}): UserDirectories => {
+  const platform = options?.platform ?? (globalThis as any).process?.platform ?? "linux"
+  const homeVariable = platform === "win32" ? "USERPROFILE" : "HOME"
+  const optionalString = (name: string) => Config.String(name).pipe(Config.withDefault(undefined))
+  const read = <A>(method: string, config: Config.Config<A>): Effect.Effect<A, PlatformError.PlatformError> =>
+    Effect.mapError(config, (cause) =>
+      PlatformError.systemError({
+        _tag: "Unknown",
+        module: "UserDirectories",
+        method,
+        description: "Failed to read the environment",
+        cause
+      }))
+  const notFound = (method: string) =>
+    PlatformError.systemError({
+      _tag: "NotFound",
+      module: "UserDirectories",
+      method,
+      description: `${homeVariable} is not set`
+    })
+  const directory = (kind: Kind) => {
+    const environment = Config.all({
+      home: optionalString(homeVariable),
+      xdg: optionalString(xdgVariable[kind]),
+      appData: optionalString(kind === "config" || kind === "data" ? "APPDATA" : "LOCALAPPDATA")
+    })
+    return (appName: string) =>
+      Effect.flatMap(read(kind, environment), (env) => {
+        const resolved = resolve(platform, kind, appName, env)
+        return resolved === undefined ? Effect.fail(notFound(kind)) : Effect.succeed(resolved)
+      })
+  }
+  return {
+    [TypeId]: TypeId,
+    home: Effect.flatMap(
+      read("home", optionalString(homeVariable)),
+      (home) => home === undefined ? Effect.fail(notFound("home")) : Effect.succeed(home)
+    ),
+    config: directory("config"),
+    data: directory("data"),
+    cache: directory("cache"),
+    state: directory("state")
+  }
+}
+
+/**
+ * Layer that resolves directories for the host platform.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layer: Layer.Layer<UserDirectories> = Layer.sync(UserDirectories, () => make())
+
+/**
+ * Layer that resolves directories for the given platform, such as `"win32"`,
+ * `"darwin"` or `"linux"`.
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerPlatform = (platform: string): Layer.Layer<UserDirectories> =>
+  Layer.sync(UserDirectories, () => make({ platform }))

package/src/persistence/index.ts

@@ -5,6 +5,12 @@
 
 // @barrel: Auto-generated exports. Do not edit manually.
 
+/**
+ * @stability experimental
+ * @since 4.0.6
+ */
+export * as CircuitBreaker from "./CircuitBreaker.ts"
+
 /**
  * @stability unstable
  * @since 4.0.0
@@ -46,3 +52,9 @@ export * as RateLimiter from "./RateLimiter.ts"
  * @since 4.0.0
  */
 export * as Redis from "./Redis.ts"
+
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as UserDirectories from "./UserDirectories.ts"

package/src/process/ChildProcess.ts

@@ -259,7 +259,8 @@ export interface KillOptions {
   /**
    * 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`, so `"SIGKILL"` is never sent.
+   * signal. Defaults to `undefined`, so `"SIGKILL"` is never sent and termination
+   * waits for the process to exit with no time limit.
    *
    * **Details**
    *
@@ -318,10 +319,17 @@ export interface StdoutConfig {
    * Can be a string indicating how the operating system should configure the
    * pipe established between the child process `stdout` and the parent process.
    *
-   * A `Sink` can also be passed, which will receive all elements produced by
-   * the `stdout` of the child process.
+   * A `Sink` can also be passed. The output is transduced through the sink as
+   * `handle.stdout` is consumed, and `handle.stdout` emits the results produced by
+   * the sink instead of the raw output.
    *
    * Defaults to "pipe".
+   *
+   * **Gotchas**
+   *
+   * A `Sink` only receives data while `handle.stdout` is being consumed. If
+   * it is never consumed, the sink receives nothing and a child process that
+   * writes more than the pipe buffer can block before it exits.
    */
   readonly stream?: CommandOutput | undefined
 }
@@ -342,10 +350,17 @@ export interface StderrConfig {
    * Can be a string indicating how the operating system should configure the
    * pipe established between the child process `stderr` and the parent process.
    *
-   * A `Sink` can also be passed, which will receive all elements produced by
-   * the `stderr` of the child process.
+   * A `Sink` can also be passed. The output is transduced through the sink as
+   * `handle.stderr` is consumed, and `handle.stderr` emits the results produced by
+   * the sink instead of the raw output.
    *
    * Defaults to "pipe".
+   *
+   * **Gotchas**
+   *
+   * A `Sink` only receives data while `handle.stderr` is being consumed. If
+   * it is never consumed, the sink receives nothing and a child process that
+   * writes more than the pipe buffer can block before it exits.
    */
   readonly stream?: CommandOutput | undefined
 }
@@ -381,6 +396,18 @@ export type AdditionalFdConfig =
     /**
      * For output file descriptors, an optional sink which receives data from
      * the file descriptor.
+     *
+     * **Details**
+     *
+     * The data is transduced through the sink as `handle.getOutputFd(fd)` is
+     * consumed, and that stream emits the results produced by the sink
+     * instead of the raw output.
+     *
+     * **Gotchas**
+     *
+     * The sink only receives data while `handle.getOutputFd(fd)` is being
+     * consumed. If it is never consumed, the sink receives nothing and a child
+     * process that writes more than the pipe buffer can block before it exits.
      */
     readonly sink?: Sink.Sink<Uint8Array, Uint8Array, never, PlatformError.PlatformError> | undefined
   }

package/src/process/ChildProcessSpawner.ts

@@ -230,11 +230,13 @@ export const makeHandle = (params: Omit<ChildProcessHandle, typeof HandleTypeId>
  * @since 4.0.0
  */
 export const make = (spawn: ChildProcessSpawner["Service"]["spawn"]): ChildProcessSpawner["Service"] => {
+  // The helpers own the handle, so they drain any output they do not return
+  // to keep a full pipe from blocking the child.
   const streamString: ChildProcessSpawner["Service"]["streamLines"] = (command, options) =>
     spawn(command).pipe(
       Effect.map((handle) =>
         Stream.decodeText(
-          options?.includeStderr === true ? handle.all : handle.stdout
+          options?.includeStderr === true ? handle.all : Stream.drainFork(handle.stdout, handle.stderr)
         )
       ),
       Stream.unwrap
@@ -244,7 +246,14 @@ export const make = (spawn: ChildProcessSpawner["Service"]["spawn"]): ChildProce
 
   return ChildProcessSpawner.of({
     spawn,
-    exitCode: (command) => Effect.scoped(Effect.flatMap(spawn(command), (handle) => handle.exitCode)),
+    // Return once the process exits, even if descendants keep the pipes open.
+    exitCode: (command) =>
+      Effect.scoped(
+        Effect.flatMap(
+          spawn(command),
+          (handle) => Effect.raceFirst(handle.exitCode, Effect.andThen(Stream.runDrain(handle.all), Effect.never))
+        )
+      ),
     streamString,
     streamLines,
     lines: (command, options) => Stream.runCollect(streamLines(command, options)),
@@ -269,6 +278,12 @@ export class ChildProcessSpawner extends Context.Service<ChildProcessSpawner, {
 
   /**
    * Run a command and return its exit code.
+   *
+   * **Details**
+   *
+   * Piped `stdout` and `stderr` are read and discarded until the process
+   * exits. A read failure before then, such as from an output `Sink`, fails
+   * the effect.
    */
   exitCode(
     command: Command
@@ -277,6 +292,12 @@ export class ChildProcessSpawner extends Context.Service<ChildProcessSpawner, {
   /**
    * Stream the output of a command as strings. Optionally include stderr output
    * interleaved with stdout.
+   *
+   * **Details**
+   *
+   * Without `includeStderr`, piped `stderr` is read and discarded until
+   * `stdout` ends. A read failure before then, such as from an output `Sink`,
+   * fails the result.
    */
   streamString(command: Command, options?: {
     readonly includeStderr?: boolean | undefined
@@ -285,6 +306,12 @@ export class ChildProcessSpawner extends Context.Service<ChildProcessSpawner, {
   /**
    * Stream the output of a command as lines. Optionally include stderr output
    * interleaved with stdout.
+   *
+   * **Details**
+   *
+   * Without `includeStderr`, piped `stderr` is read and discarded until
+   * `stdout` ends. A read failure before then, such as from an output `Sink`,
+   * fails the result.
    */
   streamLines(command: Command, options?: {
     readonly includeStderr?: boolean | undefined
@@ -292,6 +319,12 @@ export class ChildProcessSpawner extends Context.Service<ChildProcessSpawner, {
 
   /**
    * Run a command and return the lines of its output as an array of strings.
+   *
+   * **Details**
+   *
+   * Without `includeStderr`, piped `stderr` is read and discarded until
+   * `stdout` ends. A read failure before then, such as from an output `Sink`,
+   * fails the result.
    */
   lines(command: Command, options?: {
     readonly includeStderr?: boolean | undefined
@@ -299,6 +332,12 @@ export class ChildProcessSpawner extends Context.Service<ChildProcessSpawner, {
 
   /**
    * Run a command and return its output as a string.
+   *
+   * **Details**
+   *
+   * Without `includeStderr`, piped `stderr` is read and discarded until
+   * `stdout` ends. A read failure before then, such as from an output `Sink`,
+   * fails the result.
    */
   string(command: Command, options?: {
     readonly includeStderr?: boolean | undefined

package/src/reactivity/AsyncResult.ts

@@ -127,8 +127,8 @@ const ResultProto = {
   pipe() {
     return pipeArguments(this, arguments)
   },
-  [Equal.symbol](this: AsyncResult<any, any>, that: AsyncResult<any, any>): boolean {
-    if (this._tag !== that._tag || this.waiting !== that.waiting) {
+  [Equal.symbol](this: AsyncResult<any, any>, that: Equal.Equal): boolean {
+    if (!isAsyncResult(that) || this._tag !== that._tag || this.waiting !== that.waiting) {
       return false
     }
     switch (this._tag) {
@@ -309,7 +309,7 @@ export const isFailure = <A, E>(result: AsyncResult<A, E>): result is Failure<A,
  * @category guards
  * @since 4.0.0
  */
-export const isInterrupted = <A, E>(result: AsyncResult<A, E>): result is Failure<A, E> =>
+export const isInterrupted = <A, E>(result: AsyncResult<A, E>): boolean =>
   result._tag === "Failure" && Cause.hasInterruptsOnly(result.cause)
 
 /**
@@ -676,47 +676,13 @@ export const flatMap: {
       case "Initial":
         return self as any as AsyncResult<B, E>
       case "Failure":
-        return failure</**
-         * Maps the success value of an `AsyncResult` and flattens the result.
-         *
-         * **When to use**
-         *
-         * Use to sequence computations that may return another `AsyncResult` while
-         * preserving initial and failure states.
-         *
-         * **Details**
-         *
-         * Initial results are left unchanged. Failures preserve their cause and remap
-         * the stored previous success when the mapping function returns a success.
-         *
-         * @stability unstable
-         * @category combinators
-         * @since 4.0.0
-         */
-        B, /**
-         * Maps the success value of an `AsyncResult` and flattens the result.
-         *
-         * **When to use**
-         *
-         * Use to sequence computations that may return another `AsyncResult` while
-         * preserving initial and failure states.
-         *
-         * **Details**
-         *
-         * Initial results are left unchanged. Failures preserve their cause and remap
-         * the stored previous success when the mapping function returns a success.
-         *
-         * @stability unstable
-         * @category combinators
-         * @since 4.0.0
-         */
-        E | E2>(self.cause, {
+        return failure<B, E | E2>(self.cause, {
           previousSuccess: Option.flatMap(self.previousSuccess, (s) => {
             const next = f(s.value, s)
             return isSuccess(next) ? Option.some(next) : Option.none()
           }),
           waiting: self.waiting
-        });
+        })
       case "Success":
         return f(self.value, self)
     }