effect 4.0.4 → 4.0.6

package/src/Optic.ts

@@ -1352,49 +1352,7 @@ export const get: {
    */
   <S, A>(self: NoInfer<S>, optic: Lens<S, A>): A
 } = dual<
-  // ---------------------------------------------
-  // Derived APIs
-  // ---------------------------------------------
-
-  /**
-   * Reads the focused value from a `Lens`.
-   *
-   * **When to use**
-   *
-   * Use when the optic always focuses exactly one value.
-   *
-   * **Details**
-   *
-   * Supports both data-first and data-last forms.
-   *
-   * @see {@link getResult} for optics whose focus may be absent
-   *
-   * @stability stable
-   * @category getters
-   * @since 4.0.0
-   */
   <S, A>(optic: Lens<S, A>) => (self: NoInfer<S>) => A,
-  // ---------------------------------------------
-  // Derived APIs
-  // ---------------------------------------------
-
-  /**
-   * Reads the focused value from a `Lens`.
-   *
-   * **When to use**
-   *
-   * Use when the optic always focuses exactly one value.
-   *
-   * **Details**
-   *
-   * Supports both data-first and data-last forms.
-   *
-   * @see {@link getResult} for optics whose focus may be absent
-   *
-   * @stability stable
-   * @category getters
-   * @since 4.0.0
-   */
   <S, A>(self: NoInfer<S>, optic: Lens<S, A>) => A
 >(2, (self, optic) => optic.get(self))
 
@@ -1453,41 +1411,7 @@ export const getResult: {
    */
   <S, A>(self: NoInfer<S>, optic: Optional<S, A>): Result.Result<A, SchemaIssue.Issue>
 } = dual<
-  /**
-   * Attempts to read the focused value from an `Optional`.
-   *
-   * **When to use**
-   *
-   * Use when the optic may not focus and you need the failure as a `Result`.
-   *
-   * **Details**
-   *
-   * Supports both data-first and data-last forms.
-   *
-   * @see {@link get} for optics that always focus
-   *
-   * @stability stable
-   * @category getters
-   * @since 4.0.0
-   */
   <S, A>(optic: Optional<S, A>) => (self: NoInfer<S>) => Result.Result<A, SchemaIssue.Issue>,
-  /**
-   * Attempts to read the focused value from an `Optional`.
-   *
-   * **When to use**
-   *
-   * Use when the optic may not focus and you need the failure as a `Result`.
-   *
-   * **Details**
-   *
-   * Supports both data-first and data-last forms.
-   *
-   * @see {@link get} for optics that always focus
-   *
-   * @stability stable
-   * @category getters
-   * @since 4.0.0
-   */
   <S, A>(self: NoInfer<S>, optic: Optional<S, A>) => Result.Result<A, SchemaIssue.Issue>
 >(2, (self, optic) => optic.getResult(self))
 
@@ -1546,41 +1470,7 @@ export const set: {
    */
   <S, A>(self: NoInfer<A>, optic: Prism<S, A>): S
 } = dual<
-  /**
-   * Builds a source value from a focused value using a `Prism`.
-   *
-   * **When to use**
-   *
-   * Use when the optic can construct the source without an existing source value.
-   *
-   * **Details**
-   *
-   * Supports both data-first and data-last forms. The focused value is `self`.
-   *
-   * @see {@link replace} for updates that use an existing source
-   *
-   * @stability stable
-   * @category transforming
-   * @since 4.0.0
-   */
   <S, A>(optic: Prism<S, A>) => (self: NoInfer<A>) => S,
-  /**
-   * Builds a source value from a focused value using a `Prism`.
-   *
-   * **When to use**
-   *
-   * Use when the optic can construct the source without an existing source value.
-   *
-   * **Details**
-   *
-   * Supports both data-first and data-last forms. The focused value is `self`.
-   *
-   * @see {@link replace} for updates that use an existing source
-   *
-   * @stability stable
-   * @category transforming
-   * @since 4.0.0
-   */
   <S, A>(self: NoInfer<A>, optic: Prism<S, A>) => S
 >(2, (self, optic) => optic.set(self))
 
@@ -1639,41 +1529,7 @@ export const replace: {
    */
   <S, A>(self: NoInfer<S>, optic: Optional<S, A>, value: NoInfer<A>): S
 } = dual<
-  /**
-   * Replaces the focused value in a source.
-   *
-   * **When to use**
-   *
-   * Use when a failed focus should leave the source unchanged.
-   *
-   * **Details**
-   *
-   * Supports both data-first and data-last forms.
-   *
-   * @see {@link replaceResult} for an explicit replacement failure
-   *
-   * @stability stable
-   * @category transforming
-   * @since 4.0.0
-   */
   <S, A>(optic: Optional<S, A>, value: NoInfer<A>) => (self: NoInfer<S>) => S,
-  /**
-   * Replaces the focused value in a source.
-   *
-   * **When to use**
-   *
-   * Use when a failed focus should leave the source unchanged.
-   *
-   * **Details**
-   *
-   * Supports both data-first and data-last forms.
-   *
-   * @see {@link replaceResult} for an explicit replacement failure
-   *
-   * @stability stable
-   * @category transforming
-   * @since 4.0.0
-   */
   <S, A>(self: NoInfer<S>, optic: Optional<S, A>, value: NoInfer<A>) => S
 >(3, (self, optic, value) => optic.replace(value, self))
 
@@ -1732,42 +1588,15 @@ export const replaceResult: {
    */
   <S, A>(self: NoInfer<S>, optic: Optional<S, A>, value: NoInfer<A>): Result.Result<S, SchemaIssue.Issue>
 } = dual<
-  /**
-   * Attempts to replace the focused value in a source.
-   *
-   * **When to use**
-   *
-   * Use when you need an explicit `Result` for a replacement failure.
-   *
-   * **Details**
-   *
-   * Supports both data-first and data-last forms.
-   *
-   * @see {@link replace} for returning the original source on failure
-   *
-   * @stability stable
-   * @category transforming
-   * @since 4.0.0
-   */
-  <S, A>(optic: Optional<S, A>, value: NoInfer<A>) => (self: NoInfer<S>) => Result.Result<S, SchemaIssue.Issue>,
-  /**
-   * Attempts to replace the focused value in a source.
-   *
-   * **When to use**
-   *
-   * Use when you need an explicit `Result` for a replacement failure.
-   *
-   * **Details**
-   *
-   * Supports both data-first and data-last forms.
-   *
-   * @see {@link replace} for returning the original source on failure
-   *
-   * @stability stable
-   * @category transforming
-   * @since 4.0.0
-   */
-  <S, A>(self: NoInfer<S>, optic: Optional<S, A>, value: NoInfer<A>) => Result.Result<S, SchemaIssue.Issue>
+  <S, A>(
+    optic: Optional<S, A>,
+    value: NoInfer<A>
+  ) => (self: NoInfer<S>) => Result.Result<S, SchemaIssue.Issue>,
+  <S, A>(
+    self: NoInfer<S>,
+    optic: Optional<S, A>,
+    value: NoInfer<A>
+  ) => Result.Result<S, SchemaIssue.Issue>
 >(3, (self, optic, value) => optic.replaceResult(value, self))
 
 /**
@@ -1832,43 +1661,10 @@ export const modify: {
     f: (value: NoInfer<A>) => NoInfer<A>
   ): S
 } = dual<
-  /**
-   * Transforms the focused value in a source.
-   *
-   * **When to use**
-   *
-   * Use when you want to update a focus with a function.
-   *
-   * **Details**
-   *
-   * Supports both data-first and data-last forms. A failed focus leaves the
-   * source unchanged.
-   *
-   * @see {@link modifyAll} for transforming every value in a traversal
-   *
-   * @stability stable
-   * @category transforming
-   * @since 4.0.0
-   */
-  <S, A>(optic: Optional<S, A>, f: (value: NoInfer<A>) => NoInfer<A>) => (self: NoInfer<S>) => S,
-  /**
-   * Transforms the focused value in a source.
-   *
-   * **When to use**
-   *
-   * Use when you want to update a focus with a function.
-   *
-   * **Details**
-   *
-   * Supports both data-first and data-last forms. A failed focus leaves the
-   * source unchanged.
-   *
-   * @see {@link modifyAll} for transforming every value in a traversal
-   *
-   * @stability stable
-   * @category transforming
-   * @since 4.0.0
-   */
+  <S, A>(
+    optic: Optional<S, A>,
+    f: (value: NoInfer<A>) => NoInfer<A>
+  ) => (self: NoInfer<S>) => S,
   <S, A>(
     self: NoInfer<S>,
     optic: Optional<S, A>,
@@ -1994,83 +1790,7 @@ export const getAll: {
    */
   <S, A>(self: NoInfer<S>, traversal: Traversal<S, A>): Array<A>
 } = dual<
-  /**
-   * Extracts all values focused by a `Traversal` as a plain mutable array.
-   *
-   * **When to use**
-   *
-   * Use when you need the focused values as a simple `Array<A>` for further
-   *   processing.
-   *
-   * **Details**
-   *
-   * - Returns an empty array when the traversal cannot focus.
-   * - Always returns a fresh array (safe to mutate).
-   * - Supports both data-first and data-last forms.
-   *
-   * **Example** (Collecting positive numbers)
-   *
-   * ```ts import.meta.vitest
-   * import { Optic, Schema } from "effect"
-   *
-   * type S = { readonly values: ReadonlyArray<number> }
-   *
-   * const _pos = Optic.id<S>()
-   *   .key("values")
-   *   .forEach((n) => n.check(Schema.isGreaterThan(0)))
-   *
-   * const getPositive = Optic.getAll(_pos)
-   *
-   * getPositive({ values: [3, -1, 5] }) // => [3, 5]
-   *
-   * getPositive({ values: [-1, -2] }) // => []
-   * ```
-   *
-   * @see {@link Traversal} — the optic type this operates on
-   *
-   * @stability stable
-   * @category getters
-   * @since 4.0.0
-   */
   <S, A>(traversal: Traversal<S, A>) => (self: NoInfer<S>) => Array<A>,
-  /**
-   * Extracts all values focused by a `Traversal` as a plain mutable array.
-   *
-   * **When to use**
-   *
-   * Use when you need the focused values as a simple `Array<A>` for further
-   *   processing.
-   *
-   * **Details**
-   *
-   * - Returns an empty array when the traversal cannot focus.
-   * - Always returns a fresh array (safe to mutate).
-   * - Supports both data-first and data-last forms.
-   *
-   * **Example** (Collecting positive numbers)
-   *
-   * ```ts import.meta.vitest
-   * import { Optic, Schema } from "effect"
-   *
-   * type S = { readonly values: ReadonlyArray<number> }
-   *
-   * const _pos = Optic.id<S>()
-   *   .key("values")
-   *   .forEach((n) => n.check(Schema.isGreaterThan(0)))
-   *
-   * const getPositive = Optic.getAll(_pos)
-   *
-   * getPositive({ values: [3, -1, 5] }) // => [3, 5]
-   *
-   * getPositive({ values: [-1, -2] }) // => []
-   * ```
-   *
-   * @see {@link Traversal} — the optic type this operates on
-   *
-   * @stability stable
-   * @category getters
-   * @since 4.0.0
-   */
   <S, A>(self: NoInfer<S>, traversal: Traversal<S, A>) => Array<A>
 >(2, (self, traversal) =>
   Result.match(traversal.getResult(self), {
@@ -2143,45 +1863,10 @@ export const modifyAll: {
     f: (value: NoInfer<A>) => NoInfer<A>
   ): S
 } = dual<
-  /**
-   * Transforms every value focused by a `Traversal`.
-   *
-   * **When to use**
-   *
-   * Use when you want to update each value selected by a traversal.
-   *
-   * **Details**
-   *
-   * Supports both data-first and data-last forms. A failed traversal leaves the
-   * source unchanged.
-   *
-   * @see {@link modify} for transforming the focus as a whole
-   * @see {@link getAll} for reading every focused value
-   *
-   * @stability stable
-   * @category transforming
-   * @since 4.0.0
-   */
-  <S, A>(traversal: Traversal<S, A>, f: (value: NoInfer<A>) => NoInfer<A>) => (self: NoInfer<S>) => S,
-  /**
-   * Transforms every value focused by a `Traversal`.
-   *
-   * **When to use**
-   *
-   * Use when you want to update each value selected by a traversal.
-   *
-   * **Details**
-   *
-   * Supports both data-first and data-last forms. A failed traversal leaves the
-   * source unchanged.
-   *
-   * @see {@link modify} for transforming the focus as a whole
-   * @see {@link getAll} for reading every focused value
-   *
-   * @stability stable
-   * @category transforming
-   * @since 4.0.0
-   */
+  <S, A>(
+    traversal: Traversal<S, A>,
+    f: (value: NoInfer<A>) => NoInfer<A>
+  ) => (self: NoInfer<S>) => S,
   <S, A>(
     self: NoInfer<S>,
     traversal: Traversal<S, A>,

package/src/Path.ts

@@ -14,6 +14,7 @@ import * as Context from "./Context.ts"
 import * as Effect from "./Effect.ts"
 import { identity } from "./Function.ts"
 import * as Layer from "./Layer.ts"
+import * as Option from "./Option.ts"
 import { BadArgument } from "./PlatformError.ts"
 
 /**
@@ -47,10 +48,17 @@ export const TypeId = "~effect/Path"
  * formatting, and converting file system paths. URL conversion methods return
  * `Effect`s because invalid file URLs or paths can fail with `BadArgument`.
  *
+ * `resolveWithin(root, input)` resolves a relative `input` beneath `root` and
+ * returns `Option.none()` when the result would leave the root or when `input`
+ * has its own root (an absolute path, or a Windows drive or UNC prefix). The
+ * root itself is allowed. The check is lexical: it does not follow symlinks,
+ * so it is not a sandbox on its own. A relative `root` is resolved against the
+ * current working directory, as with `resolve`.
+ *
  * **Example** (Using path operations)
  *
  * ```ts import.meta.vitest
- * import { Effect, Path } from "effect"
+ * import { Effect, Option, Path } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const path = yield* Path.Path
@@ -64,7 +72,8 @@ export const TypeId = "~effect/Path"
  *     isAbsolute: path.isAbsolute("/absolute/path"),
  *     name: path.parse("/path/to/file.txt").name,
  *     relative: path.relative("/from/path", "/to/path"),
- *     resolved: path.resolve("/base", "relative", "path")
+ *     resolved: path.resolve("/base", "relative", "path"),
+ *     within: path.resolveWithin("/base", "../outside")
  *   }
  * })
  *
@@ -78,6 +87,7 @@ export const TypeId = "~effect/Path"
  * result.name // => "file"
  * result.relative // => "../../to/path"
  * result.resolved // => "/base/relative/path"
+ * result.within // => Option.none()
  * ```
  *
  * @stability unstable
@@ -98,6 +108,7 @@ export interface Path {
   readonly parse: (path: string) => Path.Parsed
   readonly relative: (from: string, to: string) => string
   readonly resolve: (...pathSegments: ReadonlyArray<string>) => string
+  readonly resolveWithin: (root: string, input: string) => Option.Option<string>
   readonly toFileUrl: (path: string) => Effect.Effect<URL, BadArgument>
   readonly toNamespacedPath: (path: string) => string
 }
@@ -204,8 +215,7 @@ export declare namespace Path {
  * import { Effect, Layer, Path } from "effect"
  *
  * // Create a custom path implementation
- * const customPath: Path.Path = {
- *   [Path.TypeId]: Path.TypeId,
+ * const customPath = Path.make({
  *   sep: "/",
  *   basename: (path: string, suffix?: string) => {
  *     const base = path.split("/").pop() || ""
@@ -239,7 +249,7 @@ export declare namespace Path {
  *   resolve: (...pathSegments: ReadonlyArray<string>) => pathSegments.join("/"),
  *   toFileUrl: (path: string) => Effect.succeed(new URL(`file://${path}`)),
  *   toNamespacedPath: (path: string) => path
- * }
+ * })
  *
  * // Provide the path service
  * const customPathLayer = Layer.succeed(Path.Path)(customPath)
@@ -259,6 +269,42 @@ export declare namespace Path {
  */
 export const Path: Context.Service<Path, Path> = Context.Service("effect/Path")
 
+/**
+ * Creates a `Path` service from platform path operations.
+ *
+ * **When to use**
+ *
+ * Use to build a `Path` implementation, such as a platform layer or a test
+ * double, without implementing the operations that can be derived from the
+ * others.
+ *
+ * **Details**
+ *
+ * Adds the `Path` type marker and derives `resolveWithin` from the provided
+ * `parse`, `resolve`, `relative`, `isAbsolute`, and `sep`, so containment
+ * follows the same platform rules as those operations.
+ *
+ * @see {@link layer} for the built-in POSIX `Path` service layer
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const make = (impl: Omit<Path, typeof TypeId | "resolveWithin">): Path =>
+  Path.of({
+    ...impl,
+    [TypeId]: TypeId,
+    resolveWithin(root, input) {
+      if (impl.parse(input).root !== "") return Option.none()
+      const base = impl.resolve(root)
+      const candidate = impl.resolve(base, input)
+      const relative = impl.relative(base, candidate)
+      return relative === ".." || relative.startsWith(`..${impl.sep}`) || impl.isAbsolute(relative)
+        ? Option.none()
+        : Option.some(candidate)
+    }
+  })
+
 /**
  * The following functions are adapted from the Node.js source code:
  * https://github.com/nodejs/node/blob/main/lib/internal/url.js
@@ -384,7 +430,15 @@ function fromFileUrl(url: URL): Effect.Effect<string, BadArgument> {
       }
     }
   }
-  return Effect.succeed(decodeURIComponent(pathname))
+  return Effect.try({
+    try: () => decodeURIComponent(pathname),
+    catch: (cause) =>
+      new BadArgument({
+        module: "Path",
+        method: "fromFileUrl",
+        cause
+      })
+  })
 }
 
 const resolve: Path["resolve"] = function resolve() {
@@ -479,8 +533,7 @@ function encodePathChars(filepath: string) {
   return filepath
 }
 
-const posixImpl = Path.of({
-  [TypeId]: TypeId,
+const posixImpl = make({
   resolve,
   normalize(path) {
     if (path.length === 0) return "."

package/src/PubSub.ts

@@ -1915,16 +1915,16 @@ export const takeUpTo: {
 } = dual(2, <A>(self: Subscription<A>, max: number): Effect.Effect<Array<A>> =>
   Effect.suspend(() => {
     if (self.shutdownFlag.current) return Effect.interrupt
-    max = Count.normalize(max)
+    let limit = Count.normalize(max)
     let replay: Array<A> | undefined = undefined
-    if (self.replayWindow.remaining >= max) {
-      return Effect.succeed(self.replayWindow.takeN(max))
+    if (self.replayWindow.remaining >= limit) {
+      return Effect.succeed(self.replayWindow.takeN(limit))
     } else if (self.replayWindow.remaining > 0) {
       replay = self.replayWindow.takeAll()
-      max = max - replay.length
+      limit = limit - replay.length
     }
     const as = self.pollers.length === 0
-      ? self.subscription.pollUpTo(max)
+      ? self.subscription.pollUpTo(limit)
       : []
     self.strategy.onPubSubEmptySpaceUnsafe(self.pubsub, self.subscribers)
     return replay ? Effect.succeed(replay.concat(as)) : Effect.succeed(as)
@@ -2051,7 +2051,9 @@ const takeRemainderLoop = <A>(
     return Effect.succeed(acc)
   }
   return Effect.flatMap(takeUpTo(self, max), (bs) => {
-    acc.push(...bs)
+    for (let i = 0; i < bs.length; i++) {
+      acc.push(bs[i])
+    }
     const remaining = min - bs.length
     if (remaining === 1) {
       return Effect.map(take(self), (b) => {
@@ -3449,7 +3451,10 @@ class ReplayBuffer<A> {
     }
     this.tail = this.tail.next
     if (this.size === this.capacity) {
-      this.head = this.head.next!
+      const dropped = this.head
+      this.head = dropped.next!
+      dropped.next = null
+      dropped.value = AbsentValue
     } else {
       this.size += 1
     }

package/src/Queue.ts

@@ -761,7 +761,10 @@ export const offer: {
 )
 
 /**
- * Adds a message to the queue synchronously. Returns `false` if the queue is done.
+ * Adds a message to the queue synchronously. Returns `false` without adding the
+ * message if the queue is closing or done, or if it is full with a non-sliding
+ * strategy (`"suspend"` or `"dropping"`). A queue with non-positive capacity can
+ * still accept a message when a taker is waiting.
  *
  * **When to use**
  *
@@ -929,42 +932,7 @@ export const offerAll: {
 } = dual(2, <A, E>(self: Enqueue<A, E>, messages: Iterable<A>): Effect<Array<A>> =>
   // Admitting what fits and registering the rest are one step, so no take can
   // free capacity between them
-  internalEffect.callback</**
-   * Adds multiple messages to the queue. Returns the remaining messages that
-   * were not added.
-   *
-   * **When to use**
-   *
-   * Use when producers can submit a batch at once and need to know which messages
-   * did not fit under the queue's capacity strategy.
-   *
-   * **Details**
-   *
-   * For bounded queues, this operation may suspend if the queue doesn't have
-   * enough capacity. The operation returns an array of messages that couldn't
-   * be added (empty array means all messages were successfully added).
-   *
-   * **Example** (Offering multiple values)
-   *
-   * ```ts import.meta.vitest
-   * import { Effect, Queue } from "effect"
-   *
-   * const program = Effect.gen(function*() {
-   *   const queue = yield* Queue.dropping<number>(3)
-   *
-   *   // Try to add more messages than capacity without suspending
-   *   const remaining1 = yield* Queue.offerAll(queue, [1, 2, 3, 4, 5])
-   *   return remaining1
-   * })
-   *
-   * await Effect.runPromise(program) // => [4, 5]
-   * ```
-   *
-   * @stability stable
-   * @category offering
-   * @since 2.0.0
-   */
-  Array<A>>((resume) => {
+  internalEffect.callback<Array<A>>((resume) => {
     const remaining = offerAllUnsafe(self, messages)
     if (remaining.length === 0 || self.strategy === "dropping") {
       return resume(core.exitSucceed(remaining))

package/src/Random.ts

@@ -392,7 +392,7 @@ export const withSeed: {
 } = dual(2, <A, E, R>(
   self: Effect.Effect<A, E, R>,
   seed: string | number
-) => Effect.provideService(self, Random, ISAAC_CSPRNG(seed)))
+) => Effect.suspend(() => Effect.provideService(self, Random, ISAAC_CSPRNG(seed))))
 
 /*///////////////////////////////////////////////////////////////////////////////////////////////////
 This is a derivative work copyright (c) 2025 Effectful Technologies Inc, under MIT license.