effect 3.3.5 → 3.4.1

package/dist/esm/internal/version.js

@@ -1,4 +1,4 @@
-let moduleVersion = "3.3.5";
+let moduleVersion = "3.4.1";
 export const getCurrentVersion = () => moduleVersion;
 export const setCurrentVersion = version => {
   moduleVersion = version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect",
-  "version": "3.3.5",
+  "version": "3.4.1",
   "description": "The missing standard library for TypeScript, for writing production-grade software.",
   "license": "MIT",
   "repository": {
@@ -372,6 +372,11 @@
       "import": "./dist/esm/MetricState.js",
       "default": "./dist/cjs/MetricState.js"
     },
+    "./Micro": {
+      "types": "./dist/dts/Micro.d.ts",
+      "import": "./dist/esm/Micro.js",
+      "default": "./dist/cjs/Micro.js"
+    },
     "./ModuleVersion": {
       "types": "./dist/dts/ModuleVersion.d.ts",
       "import": "./dist/esm/ModuleVersion.js",
@@ -1020,6 +1025,9 @@
       "MetricState": [
         "./dist/dts/MetricState.d.ts"
       ],
+      "Micro": [
+        "./dist/dts/Micro.d.ts"
+      ],
       "ModuleVersion": [
         "./dist/dts/ModuleVersion.d.ts"
       ],

package/src/Array.ts

@@ -145,6 +145,21 @@ export const replicate: {
 export const fromIterable = <A>(collection: Iterable<A>): Array<A> =>
   Array.isArray(collection) ? collection : Array.from(collection)
 
+/**
+ * Creates a new `Array` from a value that might not be an iterable.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * assert.deepStrictEqual(Array.ensure("a"), ["a"])
+ * assert.deepStrictEqual(Array.ensure(["a"]), ["a"])
+ * assert.deepStrictEqual(Array.ensure(["a", "b", "c"]), ["a", "b", "c"])
+ *
+ * @category constructors
+ * @since 3.3.0
+ */
+export const ensure = <A>(self: ReadonlyArray<A> | A): Array<A> => Array.isArray(self) ? self : [self as A]
+
 /**
  * Takes a record and returns an array of tuples containing its keys and values.
  *

package/src/Cause.ts

@@ -192,7 +192,7 @@ export interface CauseReducer<in C, in E, in out Z> {
  */
 export interface YieldableError extends Pipeable, Inspectable, Readonly<Error> {
   readonly [Effect.EffectTypeId]: Effect.Effect.VarianceStruct<never, this, never>
-  readonly [Stream.StreamTypeId]: Effect.Effect.VarianceStruct<never, this, never>
+  readonly [Stream.StreamTypeId]: Stream.Stream.VarianceStruct<never, this, never>
   readonly [Sink.SinkTypeId]: Sink.Sink.VarianceStruct<never, unknown, never, this, never>
   readonly [Channel.ChannelTypeId]: Channel.Channel.VarianceStruct<never, unknown, this, unknown, never, unknown, never>
   [Symbol.iterator](): Effect.EffectGenerator<Effect.Effect<never, this, never>>

package/src/Chunk.ts

@@ -819,6 +819,8 @@ export const head: <A>(self: Chunk<A>) => Option<A> = get(0)
 /**
  * Returns the first element of this chunk.
  *
+ * It will throw an error if the chunk is empty.
+ *
  * @since 2.0.0
  * @category unsafe
  */
@@ -843,11 +845,21 @@ export const last = <A>(self: Chunk<A>): Option<A> => get(self, self.length - 1)
 /**
  * Returns the last element of this chunk.
  *
+ * It will throw an error if the chunk is empty.
+ *
  * @since 2.0.0
  * @category unsafe
  */
 export const unsafeLast = <A>(self: Chunk<A>): A => unsafeGet(self, self.length - 1)
 
+/**
+ * Returns the last element of this non empty chunk.
+ *
+ * @since 3.4.0
+ * @category elements
+ */
+export const lastNonEmpty: <A>(self: NonEmptyChunk<A>) => A = unsafeLast
+
 /**
  * @since 2.0.0
  */

package/src/Effect.ts

@@ -291,7 +291,7 @@ export const isEffect: (u: unknown) => u is Effect<unknown, unknown, unknown> =
  *   yield* cached.pipe(Effect.andThen(Console.log))
  * })
  *
- * // Effect.runFork(program)
+ * Effect.runFork(program)
  * // Output:
  * // expensive task...
  * // result 1
@@ -336,7 +336,7 @@ export const cachedWithTTL: {
  *   yield* cached.pipe(Effect.andThen(Console.log))
  * })
  *
- * // Effect.runFork(program)
+ * Effect.runFork(program)
  * // Output:
  * // expensive task...
  * // result 1
@@ -385,7 +385,7 @@ export const cachedInvalidateWithTTL: {
  *   yield* cached.pipe(Effect.andThen(Console.log))
  * })
  *
- * // Effect.runFork(program)
+ * Effect.runFork(program)
  * // Output:
  * // non-cached version:
  * // expensive task...
@@ -422,7 +422,7 @@ export const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
  *   console.log(yield* memoized(10))
  * })
  *
- * // Effect.runFork(program)
+ * Effect.runFork(program)
  * // Example Output:
  * // non-memoized version:
  * // 2
@@ -453,7 +453,7 @@ export const cachedFunction: <A, B, E, R>(
  *   yield* Effect.repeatN(task2, 2)
  * })
  *
- * // Effect.runFork(program)
+ * Effect.runFork(program)
  * // Output:
  * // task1
  * // task1
@@ -2159,6 +2159,40 @@ export const uninterruptibleMask: <A, E, R>(
   f: (restore: <AX, EX, RX>(effect: Effect<AX, EX, RX>) => Effect<AX, EX, RX>) => Effect<A, E, R>
 ) => Effect<A, E, R> = core.uninterruptibleMask
 
+// -------------------------------------------------------------------------------------
+// lifting
+// -------------------------------------------------------------------------------------
+
+/**
+ * Transforms a `Predicate` function into an `Effect` returning the input value if the predicate returns `true`
+ * or failing with specified error if the predicate fails
+ *
+ * @param predicate - A `Predicate` function that takes in a value of type `A` and returns a boolean.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * const isPositive = (n: number): boolean => n > 0
+ *
+ * // succeeds with `1`
+ * Effect.liftPredicate(1, isPositive, n => `${n} is not positive`)
+ *
+ * // fails with `"0 is not positive"`
+ * Effect.liftPredicate(0, isPositive, n => `${n} is not positive`)
+ *
+ * @category lifting
+ * @since 3.4.0
+ */
+export const liftPredicate: {
+  <A, B extends A, E>(
+    refinement: Refinement<NoInfer<A>, B>,
+    orFailWith: (a: NoInfer<A>) => E
+  ): (a: A) => Effect<B, E>
+  <A, E>(predicate: Predicate<NoInfer<A>>, orFailWith: (a: NoInfer<A>) => E): (a: A) => Effect<A, E>
+  <A, E, B extends A>(self: A, refinement: Refinement<A, B>, orFailWith: (a: A) => E): Effect<B, E>
+  <A, E>(self: A, predicate: Predicate<NoInfer<A>>, orFailWith: (a: NoInfer<A>) => E): Effect<A, E>
+} = effect.liftPredicate
+
 // -------------------------------------------------------------------------------------
 // mapping
 // -------------------------------------------------------------------------------------
@@ -4017,8 +4051,27 @@ export const tap: {
 } = core.tap
 
 /**
- * Returns an effect that effectfully "peeks" at the failure or success of
- * this effect.
+ * Inspects both success and failure outcomes of an effect, performing different actions based on the result.
+ *
+ * @example
+ * import { Effect, Random, Console } from "effect"
+ *
+ * // Simulate an effect that might fail
+ * const task = Effect.filterOrFail(
+ *   Random.nextRange(-1, 1),
+ *   (n) => n >= 0,
+ *   () => "random number is negative"
+ * )
+ *
+ * // Define an effect that logs both success and failure outcomes of the 'task'
+ * const tapping = Effect.tapBoth(task, {
+ *   onFailure: (error) => Console.log(`failure: ${error}`),
+ *   onSuccess: (randomNumber) => Console.log(`random number: ${randomNumber}`)
+ * })
+ *
+ * Effect.runFork(tapping)
+ * // Example Output:
+ * // failure: random number is negative
  *
  * @since 2.0.0
  * @category sequencing
@@ -4040,7 +4093,36 @@ export const tapBoth: {
 } = effect.tapBoth
 
 /**
- * Returns an effect that effectually "peeks" at the defect of this effect.
+ * Specifically inspects non-recoverable failures or defects in an effect (i.e., one or more `Die` causes).
+ *
+ * @example
+ * import { Effect, Console } from "effect"
+ *
+ * // Create an effect that is designed to fail, simulating an occurrence of a network error
+ * const task1: Effect.Effect<number, string> = Effect.fail("NetworkError")
+ *
+ * // this won't log anything because is not a defect
+ * const tapping1 = Effect.tapDefect(task1, (cause) =>
+ *   Console.log(`defect: ${cause}`)
+ * )
+ *
+ * Effect.runFork(tapping1)
+ * // No Output
+ *
+ * // Simulate a severe failure in the system by causing a defect with a specific message.
+ * const task2: Effect.Effect<number, string> = Effect.dieMessage(
+ *   "Something went wrong"
+ * )
+ *
+ * // This will only log defects, not errors
+ * const tapping2 = Effect.tapDefect(task2, (cause) =>
+ *   Console.log(`defect: ${cause}`)
+ * )
+ *
+ * Effect.runFork(tapping2)
+ * // Output:
+ * // defect: RuntimeException: Something went wrong
+ * //   ... stack trace ...
  *
  * @since 2.0.0
  * @category sequencing
@@ -4056,7 +4138,23 @@ export const tapDefect: {
 } = effect.tapDefect
 
 /**
- * Returns an effect that effectfully "peeks" at the failure of this effect.
+ * Executes an effectful operation to inspect the failure of an effect without altering it.
+ *
+ * @example
+ * import { Effect, Console } from "effect"
+ *
+ * // Create an effect that is designed to fail, simulating an occurrence of a network error
+ * const task: Effect.Effect<number, string> = Effect.fail("NetworkError")
+ *
+ * // Log the error message if the task fails. This function only executes if there is an error,
+ * // providing a method to handle or inspect errors without altering the outcome of the original effect.
+ * const tapping = Effect.tapError(task, (error) =>
+ *   Console.log(`expected error: ${error}`)
+ * )
+ *
+ * Effect.runFork(tapping)
+ * // Output:
+ * // expected error: NetworkError
  *
  * @since 2.0.0
  * @category sequencing
@@ -4069,7 +4167,33 @@ export const tapError: {
 } = effect.tapError
 
 /**
- * Returns an effect that effectfully "peeks" at the specific tagged failure of this effect.
+ * Specifically inspects a failure with a particular tag, allowing focused error handling.
+ *
+ * @example
+ * import { Effect, Console } from "effect"
+ *
+ * class NetworkError {
+ *   readonly _tag = "NetworkError"
+ *   constructor(readonly statusCode: number) {}
+ * }
+ * class ValidationError {
+ *   readonly _tag = "ValidationError"
+ *   constructor(readonly field: string) {}
+ * }
+ *
+ * // Create an effect that is designed to fail, simulating an occurrence of a network error
+ * const task: Effect.Effect<number, NetworkError | ValidationError> =
+ *   Effect.fail(new NetworkError(504))
+ *
+ * // Apply an error handling function only to errors tagged as "NetworkError",
+ * // and log the corresponding status code of the error.
+ * const tapping = Effect.tapErrorTag(task, "NetworkError", (error) =>
+ *   Console.log(`expected error: ${error.statusCode}`)
+ * )
+ *
+ * Effect.runFork(tapping)
+ * // Output:
+ * // expected error: 504
  *
  * @since 2.0.0
  * @category sequencing
@@ -4087,8 +4211,37 @@ export const tapErrorTag: {
 } = effect.tapErrorTag
 
 /**
- * Returns an effect that effectually "peeks" at the cause of the failure of
- * this effect.
+ * Inspects the underlying cause of an effect's failure.
+ *
+ * @example
+ * import { Effect, Console } from "effect"
+ *
+ * // Create an effect that is designed to fail, simulating an occurrence of a network error
+ * const task1: Effect.Effect<number, string> = Effect.fail("NetworkError")
+ *
+ * // This will log the cause of any expected error or defect
+ * const tapping1 = Effect.tapErrorCause(task1, (cause) =>
+ *   Console.log(`error cause: ${cause}`)
+ * )
+ *
+ * Effect.runFork(tapping1)
+ * // Output:
+ * // error cause: Error: NetworkError
+ *
+ * // Simulate a severe failure in the system by causing a defect with a specific message.
+ * const task2: Effect.Effect<number, string> = Effect.dieMessage(
+ *   "Something went wrong"
+ * )
+ *
+ * // This will log the cause of any expected error or defect
+ * const tapping2 = Effect.tapErrorCause(task2, (cause) =>
+ *   Console.log(`error cause: ${cause}`)
+ * )
+ *
+ * Effect.runFork(tapping2)
+ * // Output:
+ * // error cause: RuntimeException: Something went wrong
+ * //   ... stack trace ...
  *
  * @since 2.0.0
  * @category sequencing
@@ -5152,6 +5305,55 @@ export const validateWith: {
 } = fiberRuntime.validateWith
 
 /**
+ * The `Effect.zip` function allows you to combine two effects into a single
+ * effect. This combined effect yields a tuple containing the results of both
+ * input effects once they succeed.
+ *
+ * Note that `Effect.zip` processes effects sequentially: it first completes the
+ * effect on the left and then the effect on the right.
+ *
+ * If you want to run the effects concurrently, you can use the `concurrent` option.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * const task1 = Effect.succeed(1).pipe(
+ *   Effect.delay("200 millis"),
+ *   Effect.tap(Effect.log("task1 done"))
+ * )
+ * const task2 = Effect.succeed("hello").pipe(
+ *   Effect.delay("100 millis"),
+ *   Effect.tap(Effect.log("task2 done"))
+ * )
+ *
+ * const task3 = Effect.zip(task1, task2)
+ *
+ * Effect.runPromise(task3).then(console.log)
+ * // Output:
+ * // timestamp=... level=INFO fiber=#0 message="task1 done"
+ * // timestamp=... level=INFO fiber=#0 message="task2 done"
+ * // [ 1, 'hello' ]
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * const task1 = Effect.succeed(1).pipe(
+ *   Effect.delay("200 millis"),
+ *   Effect.tap(Effect.log("task1 done"))
+ * )
+ * const task2 = Effect.succeed("hello").pipe(
+ *   Effect.delay("100 millis"),
+ *   Effect.tap(Effect.log("task2 done"))
+ * )
+ *
+ * const task3 = Effect.zip(task1, task2, { concurrent: true })
+ *
+ * Effect.runPromise(task3).then(console.log)
+ * // Output:
+ * // timestamp=... level=INFO fiber=#0 message="task2 done"
+ * // timestamp=... level=INFO fiber=#0 message="task1 done"
+ * // [ 1, 'hello' ]
+ *
  * @since 2.0.0
  * @category zipping
  */
@@ -5246,6 +5448,35 @@ export const zipRight: {
 } = fiberRuntime.zipRightOptions
 
 /**
+ * The `Effect.zipWith` function operates similarly to {@link zip} by combining
+ * two effects. However, instead of returning a tuple, it allows you to apply a
+ * function to the results of the combined effects, transforming them into a
+ * single value
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * const task1 = Effect.succeed(1).pipe(
+ *   Effect.delay("200 millis"),
+ *   Effect.tap(Effect.log("task1 done"))
+ * )
+ * const task2 = Effect.succeed("hello").pipe(
+ *   Effect.delay("100 millis"),
+ *   Effect.tap(Effect.log("task2 done"))
+ * )
+ *
+ * const task3 = Effect.zipWith(
+ *   task1,
+ *   task2,
+ *   (number, string) => number + string.length
+ * )
+ *
+ * Effect.runPromise(task3).then(console.log)
+ * // Output:
+ * // timestamp=... level=INFO fiber=#3 message="task1 done"
+ * // timestamp=... level=INFO fiber=#2 message="task2 done"
+ * // 6
+ *
  * @since 2.0.0
  * @category zipping
  */

package/src/Either.ts

@@ -389,6 +389,57 @@ export const match: {
   }): B | C => isLeft(self) ? onLeft(self.left) : onRight(self.right)
 )
 
+/**
+ * Transforms a `Predicate` function into a `Right` of the input value if the predicate returns `true`
+ * or `Left` of the result of the provided function if the predicate returns false
+ *
+ * @param predicate - A `Predicate` function that takes in a value of type `A` and returns a boolean.
+ *
+ * @example
+ * import { pipe, Either } from "effect"
+ *
+ * const isPositive = (n: number): boolean => n > 0
+ *
+ * assert.deepStrictEqual(
+ *   pipe(
+ *     1,
+ *     Either.liftPredicate(isPositive, n => `${n} is not positive`)
+ *   ),
+ *   Either.right(1)
+ * )
+ * assert.deepStrictEqual(
+ *   pipe(
+ *     0,
+ *     Either.liftPredicate(isPositive, n => `${n} is not positive`)
+ *   ),
+ *   Either.left("0 is not positive")
+ * )
+ *
+ * @category lifting
+ * @since 3.4.0
+ */
+export const liftPredicate: {
+  <A, B extends A, E>(refinement: Refinement<NoInfer<A>, B>, orLeftWith: (a: NoInfer<A>) => E): (a: A) => Either<B, E>
+  <A, E>(
+    predicate: Predicate<NoInfer<A>>,
+    orLeftWith: (a: NoInfer<A>) => E
+  ): (a: A) => Either<A, E>
+  <A, E, B extends A>(
+    self: A,
+    refinement: Refinement<A, B>,
+    orLeftWith: (a: A) => E
+  ): Either<B, E>
+  <A, E>(
+    self: A,
+    predicate: Predicate<NoInfer<A>>,
+    orLeftWith: (a: NoInfer<A>) => E
+  ): Either<A, E>
+} = dual(
+  3,
+  <A, E>(a: A, predicate: Predicate<A>, orLeftWith: (a: A) => E): Either<A, E> =>
+    predicate(a) ? right(a) : left(orLeftWith(a))
+)
+
 /**
  * Filter the right value with the provided function.
  * If the predicate fails, set the left value with the result of the provided function.

package/src/ManagedRuntime.ts

@@ -9,6 +9,22 @@ import type * as Layer from "./Layer.js"
 import type { Pipeable } from "./Pipeable.js"
 import type * as Runtime from "./Runtime.js"
 
+/**
+ * @since 3.4.0
+ */
+export declare namespace ManagedRuntime {
+  /**
+   * @category type-level
+   * @since 3.4.0
+   */
+  export type Context<T extends ManagedRuntime<any, any>> = [T] extends [ManagedRuntime<infer R, infer _E>] ? R : never
+  /**
+   * @category type-level
+   * @since 3.4.0
+   */
+  export type Error<T extends ManagedRuntime<any, any>> = [T] extends [ManagedRuntime<infer _R, infer E>] ? E : never
+}
+
 /**
  * @since 2.0.0
  * @category models