effect 3.10.19 → 3.11.1

package/src/STM.ts

@@ -106,6 +106,8 @@ export interface STMTypeLambda extends TypeLambda {
  */
 declare module "./Context.js" {
   interface Tag<Id, Value> extends STM<Value, never, Id> {}
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface Reference<Id, Value> extends STM<Value> {}
 }
 
 /**

package/src/Schema.ts

@@ -5041,6 +5041,10 @@ export class UUID extends String$.pipe(
     schemaId: UUIDSchemaId,
     identifier: "UUID",
     title: "UUID",
+    jsonSchema: {
+      format: "uuid",
+      pattern: uuidRegexp.source
+    },
     description: "a Universally Unique Identifier",
     arbitrary: (): LazyArbitrary<string> => (fc) => fc.uuid()
   })
@@ -5073,6 +5077,49 @@ export class ULID extends String$.pipe(
   })
 ) {}
 
+/**
+ * Defines a schema that represents a `URL` object.
+ *
+ * @category URL constructors
+ * @since 3.11.0
+ */
+export class URLFromSelf extends instanceOf(URL, {
+  identifier: "URLFromSelf",
+  title: "URLFromSelf",
+  arbitrary: (): LazyArbitrary<URL> => (fc) => fc.webUrl().map((s) => new URL(s)),
+  pretty: () => (url) => url.toString()
+}) {}
+
+/** @ignore */
+class URL$ extends transformOrFail(
+  String$.annotations({ description: "a string that will be parsed into a URL" }),
+  URLFromSelf,
+  {
+    strict: true,
+    decode: (str, _, ast) =>
+      ParseResult.try({
+        try: () => new URL(str),
+        catch: () => new ParseResult.Type(ast, str)
+      }),
+    encode: (url) => ParseResult.succeed(url.toString())
+  }
+).annotations({
+  identifier: "URL",
+  title: "URL",
+  pretty: () => (url) => url.toString()
+}) {}
+
+export {
+  /**
+   * Defines a schema that attempts to convert a `string` to a `URL` object using
+   * the `new URL` constructor.
+   *
+   * @category URL transformations
+   * @since 3.11.0
+   */
+  URL$ as URL
+}
+
 /**
  * @category schema id
  * @since 3.10.0
@@ -9793,6 +9840,19 @@ export class BooleanFromUnknown extends transform(
   { strict: true, decode: Predicate.isTruthy, encode: identity }
 ).annotations({ identifier: "BooleanFromUnknown" }) {}
 
+/**
+ * Converts an `string` value into its corresponding `boolean`
+ * ("true" as `true` and "false" as `false`).
+ *
+ * @category boolean transformations
+ * @since 3.11.0
+ */
+export class BooleanFromString extends transform(
+  Literal("true", "false"),
+  Boolean$,
+  { strict: true, decode: (value) => value === "true", encode: (value) => value ? "true" : "false" }
+).annotations({ identifier: "BooleanFromString" }) {}
+
 /**
  * @category Config validations
  * @since 3.10.0

package/src/Sink.ts

@@ -1765,6 +1765,17 @@ export const unwrapScoped: <A, In, L, E, R>(
   effect: Effect.Effect<Sink<A, In, L, E, R>, E, R>
 ) => Sink<A, In, L, E, Exclude<R, Scope.Scope>> = internal.unwrapScoped
 
+/**
+ * Constructs a `Sink` from a function which receives a `Scope` and returns
+ * an effect that will result in a `Sink` if successful.
+ *
+ * @since 3.11.0
+ * @category constructors
+ */
+export const unwrapScopedWith: <A, In, L, E, R>(
+  f: (scope: Scope.Scope) => Effect.Effect<Sink<A, In, L, E, R>, E, R>
+) => Sink<A, In, L, E, R> = internal.unwrapScopedWith
+
 /**
  * Returns the sink that executes this one and times its execution.
  *

package/src/Stream.ts

@@ -6161,30 +6161,40 @@ export const paginateEffect: <S, A, E, R>(
 ) => Stream<A, E, R> = internal.paginateEffect
 
 /**
- * Partition a stream using a predicate. The first stream will contain all
- * element evaluated to true and the second one will contain all element
- * evaluated to false. The faster stream may advance by up to buffer elements
- * further than the slower one.
+ * Splits a stream into two substreams based on a predicate.
+ *
+ * **Details**
+ *
+ * The `Stream.partition` function splits a stream into two parts: one for
+ * elements that satisfy the predicate (evaluated to `true`) and another for
+ * those that do not (evaluated to `false`).
+ *
+ * The faster stream may advance up to `bufferSize` elements ahead of the slower
+ * one.
+ *
+ * @see {@link partitionEither} for partitioning a stream based on effectful
+ * conditions.
  *
  * @example
  * ```ts
+ * // Title: Partitioning a Stream into Even and Odd Numbers
  * import { Effect, Stream } from "effect"
  *
- * const partition = Stream.range(1, 10).pipe(
+ * const partition = Stream.range(1, 9).pipe(
  *   Stream.partition((n) => n % 2 === 0, { bufferSize: 5 })
  * )
  *
  * const program = Effect.scoped(
  *   Effect.gen(function*() {
- *     const [evens, odds] = yield* partition
- *     console.log(yield* Stream.runCollect(evens))
+ *     const [odds, evens] = yield* partition
  *     console.log(yield* Stream.runCollect(odds))
+ *     console.log(yield* Stream.runCollect(evens))
  *   })
  * )
  *
  * // Effect.runPromise(program)
- * // { _id: 'Chunk', values: [ 2, 4, 6, 8, 10 ] }
  * // { _id: 'Chunk', values: [ 1, 3, 5, 7, 9 ] }
+ * // { _id: 'Chunk', values: [ 2, 4, 6, 8 ] }
  * ```
  *
  * @since 2.0.0
@@ -6192,30 +6202,40 @@ export const paginateEffect: <S, A, E, R>(
  */
 export const partition: {
   /**
-   * Partition a stream using a predicate. The first stream will contain all
-   * element evaluated to true and the second one will contain all element
-   * evaluated to false. The faster stream may advance by up to buffer elements
-   * further than the slower one.
+   * Splits a stream into two substreams based on a predicate.
+   *
+   * **Details**
+   *
+   * The `Stream.partition` function splits a stream into two parts: one for
+   * elements that satisfy the predicate (evaluated to `true`) and another for
+   * those that do not (evaluated to `false`).
+   *
+   * The faster stream may advance up to `bufferSize` elements ahead of the slower
+   * one.
+   *
+   * @see {@link partitionEither} for partitioning a stream based on effectful
+   * conditions.
    *
    * @example
    * ```ts
+   * // Title: Partitioning a Stream into Even and Odd Numbers
    * import { Effect, Stream } from "effect"
    *
-   * const partition = Stream.range(1, 10).pipe(
+   * const partition = Stream.range(1, 9).pipe(
    *   Stream.partition((n) => n % 2 === 0, { bufferSize: 5 })
    * )
    *
    * const program = Effect.scoped(
    *   Effect.gen(function*() {
-   *     const [evens, odds] = yield* partition
-   *     console.log(yield* Stream.runCollect(evens))
+   *     const [odds, evens] = yield* partition
    *     console.log(yield* Stream.runCollect(odds))
+   *     console.log(yield* Stream.runCollect(evens))
    *   })
    * )
    *
    * // Effect.runPromise(program)
-   * // { _id: 'Chunk', values: [ 2, 4, 6, 8, 10 ] }
    * // { _id: 'Chunk', values: [ 1, 3, 5, 7, 9 ] }
+   * // { _id: 'Chunk', values: [ 2, 4, 6, 8 ] }
    * ```
    *
    * @since 2.0.0
@@ -6228,30 +6248,40 @@ export const partition: {
     self: Stream<C, E, R>
   ) => Effect.Effect<[excluded: Stream<Exclude<C, B>, E, never>, satisfying: Stream<B, E, never>], E, R | Scope.Scope>
   /**
-   * Partition a stream using a predicate. The first stream will contain all
-   * element evaluated to true and the second one will contain all element
-   * evaluated to false. The faster stream may advance by up to buffer elements
-   * further than the slower one.
+   * Splits a stream into two substreams based on a predicate.
+   *
+   * **Details**
+   *
+   * The `Stream.partition` function splits a stream into two parts: one for
+   * elements that satisfy the predicate (evaluated to `true`) and another for
+   * those that do not (evaluated to `false`).
+   *
+   * The faster stream may advance up to `bufferSize` elements ahead of the slower
+   * one.
+   *
+   * @see {@link partitionEither} for partitioning a stream based on effectful
+   * conditions.
    *
    * @example
    * ```ts
+   * // Title: Partitioning a Stream into Even and Odd Numbers
    * import { Effect, Stream } from "effect"
    *
-   * const partition = Stream.range(1, 10).pipe(
+   * const partition = Stream.range(1, 9).pipe(
    *   Stream.partition((n) => n % 2 === 0, { bufferSize: 5 })
    * )
    *
    * const program = Effect.scoped(
    *   Effect.gen(function*() {
-   *     const [evens, odds] = yield* partition
-   *     console.log(yield* Stream.runCollect(evens))
+   *     const [odds, evens] = yield* partition
    *     console.log(yield* Stream.runCollect(odds))
+   *     console.log(yield* Stream.runCollect(evens))
    *   })
    * )
    *
    * // Effect.runPromise(program)
-   * // { _id: 'Chunk', values: [ 2, 4, 6, 8, 10 ] }
    * // { _id: 'Chunk', values: [ 1, 3, 5, 7, 9 ] }
+   * // { _id: 'Chunk', values: [ 2, 4, 6, 8 ] }
    * ```
    *
    * @since 2.0.0
@@ -6264,30 +6294,40 @@ export const partition: {
     self: Stream<A, E, R>
   ) => Effect.Effect<[excluded: Stream<A, E, never>, satisfying: Stream<A, E, never>], E, Scope.Scope | R>
   /**
-   * Partition a stream using a predicate. The first stream will contain all
-   * element evaluated to true and the second one will contain all element
-   * evaluated to false. The faster stream may advance by up to buffer elements
-   * further than the slower one.
+   * Splits a stream into two substreams based on a predicate.
+   *
+   * **Details**
+   *
+   * The `Stream.partition` function splits a stream into two parts: one for
+   * elements that satisfy the predicate (evaluated to `true`) and another for
+   * those that do not (evaluated to `false`).
+   *
+   * The faster stream may advance up to `bufferSize` elements ahead of the slower
+   * one.
+   *
+   * @see {@link partitionEither} for partitioning a stream based on effectful
+   * conditions.
    *
    * @example
    * ```ts
+   * // Title: Partitioning a Stream into Even and Odd Numbers
    * import { Effect, Stream } from "effect"
    *
-   * const partition = Stream.range(1, 10).pipe(
+   * const partition = Stream.range(1, 9).pipe(
    *   Stream.partition((n) => n % 2 === 0, { bufferSize: 5 })
    * )
    *
    * const program = Effect.scoped(
    *   Effect.gen(function*() {
-   *     const [evens, odds] = yield* partition
-   *     console.log(yield* Stream.runCollect(evens))
+   *     const [odds, evens] = yield* partition
    *     console.log(yield* Stream.runCollect(odds))
+   *     console.log(yield* Stream.runCollect(evens))
    *   })
    * )
    *
    * // Effect.runPromise(program)
-   * // { _id: 'Chunk', values: [ 2, 4, 6, 8, 10 ] }
    * // { _id: 'Chunk', values: [ 1, 3, 5, 7, 9 ] }
+   * // { _id: 'Chunk', values: [ 2, 4, 6, 8 ] }
    * ```
    *
    * @since 2.0.0
@@ -6299,30 +6339,40 @@ export const partition: {
     options?: { bufferSize?: number | undefined } | undefined
   ): Effect.Effect<[excluded: Stream<Exclude<C, B>, E, never>, satisfying: Stream<B, E, never>], E, R | Scope.Scope>
   /**
-   * Partition a stream using a predicate. The first stream will contain all
-   * element evaluated to true and the second one will contain all element
-   * evaluated to false. The faster stream may advance by up to buffer elements
-   * further than the slower one.
+   * Splits a stream into two substreams based on a predicate.
+   *
+   * **Details**
+   *
+   * The `Stream.partition` function splits a stream into two parts: one for
+   * elements that satisfy the predicate (evaluated to `true`) and another for
+   * those that do not (evaluated to `false`).
+   *
+   * The faster stream may advance up to `bufferSize` elements ahead of the slower
+   * one.
+   *
+   * @see {@link partitionEither} for partitioning a stream based on effectful
+   * conditions.
    *
    * @example
    * ```ts
+   * // Title: Partitioning a Stream into Even and Odd Numbers
    * import { Effect, Stream } from "effect"
    *
-   * const partition = Stream.range(1, 10).pipe(
+   * const partition = Stream.range(1, 9).pipe(
    *   Stream.partition((n) => n % 2 === 0, { bufferSize: 5 })
    * )
    *
    * const program = Effect.scoped(
    *   Effect.gen(function*() {
-   *     const [evens, odds] = yield* partition
-   *     console.log(yield* Stream.runCollect(evens))
+   *     const [odds, evens] = yield* partition
    *     console.log(yield* Stream.runCollect(odds))
+   *     console.log(yield* Stream.runCollect(evens))
    *   })
    * )
    *
    * // Effect.runPromise(program)
-   * // { _id: 'Chunk', values: [ 2, 4, 6, 8, 10 ] }
    * // { _id: 'Chunk', values: [ 1, 3, 5, 7, 9 ] }
+   * // { _id: 'Chunk', values: [ 2, 4, 6, 8 ] }
    * ```
    *
    * @since 2.0.0
@@ -6336,16 +6386,29 @@ export const partition: {
 } = internal.partition
 
 /**
- * Split a stream by an effectful predicate. The faster stream may advance by
- * up to buffer elements further than the slower one.
+ * Splits a stream into two substreams based on an effectful condition.
+ *
+ * **Details**
+ *
+ * The `Stream.partitionEither` function is used to divide a stream into two
+ * parts: one for elements that satisfy a condition producing `Either.left`
+ * values, and another for those that produce `Either.right` values. This
+ * function applies an effectful predicate to each element in the stream to
+ * determine which substream it belongs to.
+ *
+ * The faster stream may advance up to `bufferSize` elements ahead of the slower
+ * one.
+ *
+ * @see {@link partition} for partitioning a stream based on simple conditions.
  *
  * @example
  * ```ts
+ * // Title: Partitioning a Stream with an Effectful Predicate
  * import { Effect, Either, Stream } from "effect"
  *
  * const partition = Stream.range(1, 9).pipe(
  *   Stream.partitionEither(
- *     (n) => Effect.succeed(n % 2 === 0 ? Either.left(n) : Either.right(n)),
+ *     (n) => Effect.succeed(n % 2 === 0 ? Either.right(n) : Either.left(n)),
  *     { bufferSize: 5 }
  *   )
  * )
@@ -6359,8 +6422,8 @@ export const partition: {
  * )
  *
  * // Effect.runPromise(program)
- * // { _id: 'Chunk', values: [ 2, 4, 6, 8 ] }
  * // { _id: 'Chunk', values: [ 1, 3, 5, 7, 9 ] }
+ * // { _id: 'Chunk', values: [ 2, 4, 6, 8 ] }
  * ```
  *
  * @since 2.0.0
@@ -6368,16 +6431,29 @@ export const partition: {
  */
 export const partitionEither: {
   /**
-   * Split a stream by an effectful predicate. The faster stream may advance by
-   * up to buffer elements further than the slower one.
+   * Splits a stream into two substreams based on an effectful condition.
+   *
+   * **Details**
+   *
+   * The `Stream.partitionEither` function is used to divide a stream into two
+   * parts: one for elements that satisfy a condition producing `Either.left`
+   * values, and another for those that produce `Either.right` values. This
+   * function applies an effectful predicate to each element in the stream to
+   * determine which substream it belongs to.
+   *
+   * The faster stream may advance up to `bufferSize` elements ahead of the slower
+   * one.
+   *
+   * @see {@link partition} for partitioning a stream based on simple conditions.
    *
    * @example
    * ```ts
+   * // Title: Partitioning a Stream with an Effectful Predicate
    * import { Effect, Either, Stream } from "effect"
    *
    * const partition = Stream.range(1, 9).pipe(
    *   Stream.partitionEither(
-   *     (n) => Effect.succeed(n % 2 === 0 ? Either.left(n) : Either.right(n)),
+   *     (n) => Effect.succeed(n % 2 === 0 ? Either.right(n) : Either.left(n)),
    *     { bufferSize: 5 }
    *   )
    * )
@@ -6391,8 +6467,8 @@ export const partitionEither: {
    * )
    *
    * // Effect.runPromise(program)
-   * // { _id: 'Chunk', values: [ 2, 4, 6, 8 ] }
    * // { _id: 'Chunk', values: [ 1, 3, 5, 7, 9 ] }
+   * // { _id: 'Chunk', values: [ 2, 4, 6, 8 ] }
    * ```
    *
    * @since 2.0.0
@@ -6405,16 +6481,29 @@ export const partitionEither: {
     self: Stream<A, E, R>
   ) => Effect.Effect<[left: Stream<A2, E2 | E, never>, right: Stream<A3, E2 | E, never>], E2 | E, Scope.Scope | R2 | R>
   /**
-   * Split a stream by an effectful predicate. The faster stream may advance by
-   * up to buffer elements further than the slower one.
+   * Splits a stream into two substreams based on an effectful condition.
+   *
+   * **Details**
+   *
+   * The `Stream.partitionEither` function is used to divide a stream into two
+   * parts: one for elements that satisfy a condition producing `Either.left`
+   * values, and another for those that produce `Either.right` values. This
+   * function applies an effectful predicate to each element in the stream to
+   * determine which substream it belongs to.
+   *
+   * The faster stream may advance up to `bufferSize` elements ahead of the slower
+   * one.
+   *
+   * @see {@link partition} for partitioning a stream based on simple conditions.
    *
    * @example
    * ```ts
+   * // Title: Partitioning a Stream with an Effectful Predicate
    * import { Effect, Either, Stream } from "effect"
    *
    * const partition = Stream.range(1, 9).pipe(
    *   Stream.partitionEither(
-   *     (n) => Effect.succeed(n % 2 === 0 ? Either.left(n) : Either.right(n)),
+   *     (n) => Effect.succeed(n % 2 === 0 ? Either.right(n) : Either.left(n)),
    *     { bufferSize: 5 }
    *   )
    * )
@@ -6428,8 +6517,8 @@ export const partitionEither: {
    * )
    *
    * // Effect.runPromise(program)
-   * // { _id: 'Chunk', values: [ 2, 4, 6, 8 ] }
    * // { _id: 'Chunk', values: [ 1, 3, 5, 7, 9 ] }
+   * // { _id: 'Chunk', values: [ 2, 4, 6, 8 ] }
    * ```
    *
    * @since 2.0.0
@@ -7420,8 +7509,7 @@ export const run: {
  * @since 2.0.0
  * @category destructors
  */
-export const runCollect: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<Chunk.Chunk<A>, E, Exclude<R, Scope.Scope>> =
-  internal.runCollect
+export const runCollect: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<Chunk.Chunk<A>, E, R> = internal.runCollect
 
 /**
  * Runs the stream and emits the number of elements processed
@@ -7429,8 +7517,7 @@ export const runCollect: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<Chunk
  * @since 2.0.0
  * @category destructors
  */
-export const runCount: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<number, E, Exclude<R, Scope.Scope>> =
-  internal.runCount
+export const runCount: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<number, E, R> = internal.runCount
 
 /**
  * Runs the stream only for its effects. The emitted elements are discarded.
@@ -7438,8 +7525,7 @@ export const runCount: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<number,
  * @since 2.0.0
  * @category destructors
  */
-export const runDrain: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<void, E, Exclude<R, Scope.Scope>> =
-  internal.runDrain
+export const runDrain: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<void, E, R> = internal.runDrain
 
 /**
  * Executes a pure fold over the stream of values - reduces all elements in
@@ -7456,7 +7542,7 @@ export const runFold: {
    * @since 2.0.0
    * @category destructors
    */
-  <S, A>(s: S, f: (s: S, a: A) => S): <E, R>(self: Stream<A, E, R>) => Effect.Effect<S, E, Exclude<R, Scope.Scope>>
+  <S, A>(s: S, f: (s: S, a: A) => S): <E, R>(self: Stream<A, E, R>) => Effect.Effect<S, E, R>
   /**
    * Executes a pure fold over the stream of values - reduces all elements in
    * the stream to a value of type `S`.
@@ -7464,7 +7550,7 @@ export const runFold: {
    * @since 2.0.0
    * @category destructors
    */
-  <A, E, R, S>(self: Stream<A, E, R>, s: S, f: (s: S, a: A) => S): Effect.Effect<S, E, Exclude<R, Scope.Scope>>
+  <A, E, R, S>(self: Stream<A, E, R>, s: S, f: (s: S, a: A) => S): Effect.Effect<S, E, R>
 } = internal.runFold
 
 /**
@@ -7571,11 +7657,7 @@ export const runFoldWhile: {
    * @since 2.0.0
    * @category destructors
    */
-  <S, A>(
-    s: S,
-    cont: Predicate<S>,
-    f: (s: S, a: A) => S
-  ): <E, R>(self: Stream<A, E, R>) => Effect.Effect<S, E, Exclude<R, Scope.Scope>>
+  <S, A>(s: S, cont: Predicate<S>, f: (s: S, a: A) => S): <E, R>(self: Stream<A, E, R>) => Effect.Effect<S, E, R>
   /**
    * Reduces the elements in the stream to a value of type `S`. Stops the fold
    * early when the condition is not fulfilled. Example:
@@ -7583,12 +7665,7 @@ export const runFoldWhile: {
    * @since 2.0.0
    * @category destructors
    */
-  <A, E, R, S>(
-    self: Stream<A, E, R>,
-    s: S,
-    cont: Predicate<S>,
-    f: (s: S, a: A) => S
-  ): Effect.Effect<S, E, Exclude<R, Scope.Scope>>
+  <A, E, R, S>(self: Stream<A, E, R>, s: S, cont: Predicate<S>, f: (s: S, a: A) => S): Effect.Effect<S, E, R>
 } = internal.runFoldWhile
 
 /**
@@ -8323,6 +8400,17 @@ export const scheduleWith: {
 export const scoped: <A, E, R>(effect: Effect.Effect<A, E, R>) => Stream<A, E, Exclude<R, Scope.Scope>> =
   internal.scoped
 
+/**
+ * Use a function that receives a scope and returns an effect to emit an output
+ * element. The output element will be the result of the returned effect, if
+ * successful.
+ *
+ * @since 3.11.0
+ * @category constructors
+ */
+export const scopedWith: <A, E, R>(f: (scope: Scope.Scope) => Effect.Effect<A, E, R>) => Stream<A, E, R> =
+  internal.scopedWith
+
 /**
  * Emits a sliding window of `n` elements.
  *
@@ -9914,6 +10002,18 @@ export const unwrapScoped: <A, E2, R2, E, R>(
   effect: Effect.Effect<Stream<A, E2, R2>, E, R>
 ) => Stream<A, E | E2, R2 | Exclude<R, Scope.Scope>> = internal.unwrapScoped
 
+/**
+ * Creates a stream produced from a function which receives a `Scope` and
+ * returns an `Effect`. The resulting stream will emit a single element, which
+ * will be the result of the returned effect, if successful.
+ *
+ * @since 3.11.0
+ * @category constructors
+ */
+export const unwrapScopedWith: <A, E2, R2, E, R>(
+  f: (scope: Scope.Scope) => Effect.Effect<Stream<A, E2, R2>, E, R>
+) => Stream<A, E | E2, R | R2> = internal.unwrapScopedWith
+
 /**
  * Updates the specified service within the context of the `Stream`.
  *

package/src/Utils.ts

@@ -791,3 +791,11 @@ const tracingFunction = (name: string) => {
  * @category tracing
  */
 export const internalCall = tracingFunction("effect_internal_function")
+
+const genConstructor = (function*() {}).constructor
+
+/**
+ * @since 3.11.0
+ */
+export const isGeneratorFunction = (u: unknown): u is (...args: Array<any>) => Generator<any, any, any> =>
+  isObject(u) && u.constructor === genConstructor