effect 3.3.4 → 3.4.0

package/dist/esm/internal/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect",
-  "version": "3.3.4",
+  "version": "3.4.0",
   "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/Config.ts

@@ -70,13 +70,15 @@ export declare namespace Config {
    * @since 2.0.0
    * @category models
    */
-  export type Wrap<A> = [NonNullable<A>] extends [infer T] ?
-    [T] extends [Record<string, any>] ? [Exclude<keyof T, string>] extends [never] ?
-          | { readonly [K in keyof A]: Wrap<A[K]> }
-          | Config<A>
-      : Config<A>
+  export type Wrap<A> = [NonNullable<A>] extends [infer T] ? [IsPlainObject<T>] extends [true] ?
+        | { readonly [K in keyof A]: Wrap<A[K]> }
+        | Config<A>
     : Config<A>
     : Config<A>
+
+  type IsPlainObject<A> = [A] extends [Record<string, any>]
+    ? [keyof A] extends [never] ? false : [keyof A] extends [string] ? true : false
+    : false
 }
 
 /**

package/src/Effect.ts

@@ -266,8 +266,38 @@ export const isEffect: (u: unknown) => u is Effect<unknown, unknown, unknown> =
 // -------------------------------------------------------------------------------------
 
 /**
- * Returns an effect that, if evaluated, will return the cached result of this
- * effect. Cached results will expire after `timeToLive` duration.
+ * Returns an effect that caches its result for a specified duration, known as
+ * the `timeToLive`. When the cache expires after the duration, the effect will be
+ * recomputed upon next evaluation.
+ *
+ * @example
+ * import { Effect, Console } from "effect"
+ *
+ * let i = 1
+ * const expensiveTask = Effect.promise<string>(() => {
+ *   console.log("expensive task...")
+ *   return new Promise((resolve) => {
+ *     setTimeout(() => {
+ *       resolve(`result ${i++}`)
+ *     }, 100)
+ *   })
+ * })
+ *
+ * const program = Effect.gen(function* () {
+ *   const cached = yield* Effect.cachedWithTTL(expensiveTask, "150 millis")
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ *   yield* Effect.sleep("100 millis")
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ * })
+ *
+ * Effect.runFork(program)
+ * // Output:
+ * // expensive task...
+ * // result 1
+ * // result 1
+ * // expensive task...
+ * // result 2
  *
  * @since 2.0.0
  * @category caching
@@ -278,10 +308,41 @@ export const cachedWithTTL: {
 } = circular.cached
 
 /**
- * Returns an effect that, if evaluated, will return the cached result of this
- * effect. Cached results will expire after `timeToLive` duration. In
- * addition, returns an effect that can be used to invalidate the current
- * cached value before the `timeToLive` duration expires.
+ * Similar to {@link cachedWithTTL}, this function caches an effect's result for a
+ * specified duration. It also includes an additional effect for manually
+ * invalidating the cached value before it naturally expires.
+ *
+ * @example
+ * import { Effect, Console } from "effect"
+ *
+ * let i = 1
+ * const expensiveTask = Effect.promise<string>(() => {
+ *   console.log("expensive task...")
+ *   return new Promise((resolve) => {
+ *     setTimeout(() => {
+ *       resolve(`result ${i++}`)
+ *     }, 100)
+ *   })
+ * })
+ *
+ * const program = Effect.gen(function* () {
+ *   const [cached, invalidate] = yield* Effect.cachedInvalidateWithTTL(
+ *     expensiveTask,
+ *     "1 hour"
+ *   )
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ *   yield* invalidate
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ * })
+ *
+ * Effect.runFork(program)
+ * // Output:
+ * // expensive task...
+ * // result 1
+ * // result 1
+ * // expensive task...
+ * // result 2
  *
  * @since 2.0.0
  * @category caching
@@ -297,8 +358,44 @@ export const cachedInvalidateWithTTL: {
 } = circular.cachedInvalidateWithTTL
 
 /**
- * Returns an effect that, if evaluated, will return the lazily computed
- * result of this effect.
+ * Returns an effect that computes a result lazily and caches it. Subsequent
+ * evaluations of this effect will return the cached result without re-executing
+ * the logic.
+ *
+ * @example
+ * import { Effect, Console } from "effect"
+ *
+ * let i = 1
+ * const expensiveTask = Effect.promise<string>(() => {
+ *   console.log("expensive task...")
+ *   return new Promise((resolve) => {
+ *     setTimeout(() => {
+ *       resolve(`result ${i++}`)
+ *     }, 100)
+ *   })
+ * })
+ *
+ * const program = Effect.gen(function* () {
+ *   console.log("non-cached version:")
+ *   yield* expensiveTask.pipe(Effect.andThen(Console.log))
+ *   yield* expensiveTask.pipe(Effect.andThen(Console.log))
+ *   console.log("cached version:")
+ *   const cached = yield* Effect.cached(expensiveTask)
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ *   yield* cached.pipe(Effect.andThen(Console.log))
+ * })
+ *
+ * Effect.runFork(program)
+ * // Output:
+ * // non-cached version:
+ * // expensive task...
+ * // result 1
+ * // expensive task...
+ * // result 2
+ * // cached version:
+ * // expensive task...
+ * // result 3
+ * // result 3
  *
  * @since 2.0.0
  * @category caching
@@ -306,7 +403,33 @@ export const cachedInvalidateWithTTL: {
 export const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>> = effect.memoize
 
 /**
- * Returns a memoized version of the specified effectual function.
+ * Returns a memoized version of a function with effects. Memoization ensures
+ * that results are stored and reused for the same inputs, reducing the need to
+ * recompute them.
+ *
+ * @example
+ * import { Effect, Random } from "effect"
+ *
+ * const program = Effect.gen(function* () {
+ *   const randomNumber = (n: number) => Random.nextIntBetween(1, n)
+ *   console.log("non-memoized version:")
+ *   console.log(yield* randomNumber(10))
+ *   console.log(yield* randomNumber(10))
+ *
+ *   console.log("memoized version:")
+ *   const memoized = yield* Effect.cachedFunction(randomNumber)
+ *   console.log(yield* memoized(10))
+ *   console.log(yield* memoized(10))
+ * })
+ *
+ * Effect.runFork(program)
+ * // Example Output:
+ * // non-memoized version:
+ * // 2
+ * // 8
+ * // memoized version:
+ * // 5
+ * // 5
  *
  * @since 2.0.0
  * @category caching
@@ -317,24 +440,25 @@ export const cachedFunction: <A, B, E, R>(
 ) => Effect<(a: A) => Effect<B, E, R>> = circular.cachedFunction
 
 /**
- * Returns an effect that will be executed at most once, even if it is
- * evaluated multiple times.
+ * Returns an effect that executes only once, regardless of how many times it's
+ * called.
  *
  * @example
  * import { Effect, Console } from "effect"
  *
- * const program = Effect.gen(function* (_) {
- *   const twice = Console.log("twice")
- *   yield* _(twice, Effect.repeatN(1))
- *   const once = yield* _(Console.log("once"), Effect.once)
- *   yield* _(once, Effect.repeatN(1))
+ * const program = Effect.gen(function* () {
+ *   const task1 = Console.log("task1")
+ *   yield* Effect.repeatN(task1, 2)
+ *   const task2 = yield* Effect.once(Console.log("task2"))
+ *   yield* Effect.repeatN(task2, 2)
  * })
  *
  * Effect.runFork(program)
  * // Output:
- * // twice
- * // twice
- * // once
+ * // task1
+ * // task1
+ * // task1
+ * // task2
  *
  * @since 2.0.0
  * @category caching
@@ -2035,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
 // -------------------------------------------------------------------------------------
@@ -2457,7 +2615,7 @@ export const scopeWith: <A, E, R>(f: (scope: Scope.Scope) => Effect<A, E, R>) =>
   fiberRuntime.scopeWith
 
 /**
- * Scopes all resources uses in this workflow to the lifetime of the workflow,
+ * Scopes all resources used in this workflow to the lifetime of the workflow,
  * ensuring that their finalizers are run as soon as this workflow completes
  * execution, whether by success, failure, or interruption.
  *
@@ -5028,6 +5186,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
  */
@@ -5122,6 +5329,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