effect 3.8.4 → 3.9.0

package/src/Request.ts

@@ -172,7 +172,19 @@ export const TaggedClass: <Tag extends string>(
  * @category request completion
  */
 export const complete: {
+  /**
+   * Complete a `Request` with the specified result.
+   *
+   * @since 2.0.0
+   * @category request completion
+   */
   <A extends Request<any, any>>(result: Request.Result<A>): (self: A) => Effect.Effect<void>
+  /**
+   * Complete a `Request` with the specified result.
+   *
+   * @since 2.0.0
+   * @category request completion
+   */
   <A extends Request<any, any>>(self: A, result: Request.Result<A>): Effect.Effect<void>
 } = internal.complete
 
@@ -183,7 +195,19 @@ export const complete: {
  * @category request completion
  */
 export const interruptWhenPossible: {
+  /**
+   * Interrupts the child effect when requests are no longer needed
+   *
+   * @since 2.0.0
+   * @category request completion
+   */
   (all: Iterable<Request<any, any>>): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<void, E, R>
+  /**
+   * Interrupts the child effect when requests are no longer needed
+   *
+   * @since 2.0.0
+   * @category request completion
+   */
   <A, E, R>(self: Effect.Effect<A, E, R>, all: Iterable<Request<any, any>>): Effect.Effect<void, E, R>
 } = fiberRuntime.interruptWhenPossible
 
@@ -196,9 +220,25 @@ export const interruptWhenPossible: {
  * @category request completion
  */
 export const completeEffect: {
+  /**
+   * Complete a `Request` with the specified effectful computation, failing the
+   * request with the error from the effect workflow if it fails, and completing
+   * the request with the value of the effect workflow if it succeeds.
+   *
+   * @since 2.0.0
+   * @category request completion
+   */
   <A extends Request<any, any>, R>(
     effect: Effect.Effect<Request.Success<A>, Request.Error<A>, R>
   ): (self: A) => Effect.Effect<void, never, R>
+  /**
+   * Complete a `Request` with the specified effectful computation, failing the
+   * request with the error from the effect workflow if it fails, and completing
+   * the request with the value of the effect workflow if it succeeds.
+   *
+   * @since 2.0.0
+   * @category request completion
+   */
   <A extends Request<any, any>, R>(
     self: A,
     effect: Effect.Effect<Request.Success<A>, Request.Error<A>, R>
@@ -212,7 +252,19 @@ export const completeEffect: {
  * @category request completion
  */
 export const fail: {
+  /**
+   * Complete a `Request` with the specified error.
+   *
+   * @since 2.0.0
+   * @category request completion
+   */
   <A extends Request<any, any>>(error: Request.Error<A>): (self: A) => Effect.Effect<void>
+  /**
+   * Complete a `Request` with the specified error.
+   *
+   * @since 2.0.0
+   * @category request completion
+   */
   <A extends Request<any, any>>(self: A, error: Request.Error<A>): Effect.Effect<void>
 } = internal.fail
 
@@ -223,7 +275,19 @@ export const fail: {
  * @category request completion
  */
 export const failCause: {
+  /**
+   * Complete a `Request` with the specified cause.
+   *
+   * @since 2.0.0
+   * @category request completion
+   */
   <A extends Request<any, any>>(cause: Cause<Request.Error<A>>): (self: A) => Effect.Effect<void>
+  /**
+   * Complete a `Request` with the specified cause.
+   *
+   * @since 2.0.0
+   * @category request completion
+   */
   <A extends Request<any, any>>(self: A, cause: Cause<Request.Error<A>>): Effect.Effect<void>
 } = internal.failCause
 
@@ -234,7 +298,19 @@ export const failCause: {
  * @category request completion
  */
 export const succeed: {
+  /**
+   * Complete a `Request` with the specified value.
+   *
+   * @since 2.0.0
+   * @category request completion
+   */
   <A extends Request<any, any>>(value: Request.Success<A>): (self: A) => Effect.Effect<void>
+  /**
+   * Complete a `Request` with the specified value.
+   *
+   * @since 2.0.0
+   * @category request completion
+   */
   <A extends Request<any, any>>(self: A, value: Request.Success<A>): Effect.Effect<void>
 } = internal.succeed
 

package/src/RequestResolver.ts

@@ -148,10 +148,24 @@ export const makeBatched: <A extends Request.Request<any, any>, R>(
  * @category combinators
  */
 export const around: {
+  /**
+   * A data source aspect that executes requests between two effects, `before`
+   * and `after`, where the result of `before` can be used by `after`.
+   *
+   * @since 2.0.0
+   * @category combinators
+   */
   <A2, R2, X, R3>(
     before: Effect.Effect<A2, never, R2>,
     after: (a: A2) => Effect.Effect<X, never, R3>
   ): <A, R>(self: RequestResolver<A, R>) => RequestResolver<A, R2 | R3 | R>
+  /**
+   * A data source aspect that executes requests between two effects, `before`
+   * and `after`, where the result of `before` can be used by `after`.
+   *
+   * @since 2.0.0
+   * @category combinators
+   */
   <A, R, A2, R2, X, R3>(
     self: RequestResolver<A, R>,
     before: Effect.Effect<A2, never, R2>,
@@ -185,10 +199,60 @@ export const around: {
  * )
  */
 export const aroundRequests: {
+  /**
+   * A data source aspect that executes requests between two effects, `before`
+   * and `after`, where the result of `before` can be used by `after`.
+   *
+   * The `before` and `after` effects are provided with the requests being executed.
+   *
+   * @since 2.0.0
+   * @category combinators
+   * @example
+   * import { Effect, Request, RequestResolver } from "effect"
+   *
+   * interface GetUserById extends Request.Request<unknown> {
+   *   readonly id: number
+   * }
+   *
+   * const resolver = RequestResolver.fromFunction(
+   *   (request: GetUserById) => ({ id: request.id, name: "John" })
+   * )
+   *
+   * RequestResolver.aroundRequests(
+   *   resolver,
+   *   (requests) => Effect.log(`got ${requests.length} requests`),
+   *   (requests, _) => Effect.log(`finised running ${requests.length} requests`)
+   * )
+   */
   <A, A2, R2, X, R3>(
     before: (requests: ReadonlyArray<Types.NoInfer<A>>) => Effect.Effect<A2, never, R2>,
     after: (requests: ReadonlyArray<Types.NoInfer<A>>, _: A2) => Effect.Effect<X, never, R3>
   ): <R>(self: RequestResolver<A, R>) => RequestResolver<A, R2 | R3 | R>
+  /**
+   * A data source aspect that executes requests between two effects, `before`
+   * and `after`, where the result of `before` can be used by `after`.
+   *
+   * The `before` and `after` effects are provided with the requests being executed.
+   *
+   * @since 2.0.0
+   * @category combinators
+   * @example
+   * import { Effect, Request, RequestResolver } from "effect"
+   *
+   * interface GetUserById extends Request.Request<unknown> {
+   *   readonly id: number
+   * }
+   *
+   * const resolver = RequestResolver.fromFunction(
+   *   (request: GetUserById) => ({ id: request.id, name: "John" })
+   * )
+   *
+   * RequestResolver.aroundRequests(
+   *   resolver,
+   *   (requests) => Effect.log(`got ${requests.length} requests`),
+   *   (requests, _) => Effect.log(`finised running ${requests.length} requests`)
+   * )
+   */
   <A, R, A2, R2, X, R3>(
     self: RequestResolver<A, R>,
     before: (requests: ReadonlyArray<Types.NoInfer<A>>) => Effect.Effect<A2, never, R2>,
@@ -203,7 +267,19 @@ export const aroundRequests: {
  * @category combinators
  */
 export const batchN: {
+  /**
+   * Returns a data source that executes at most `n` requests in parallel.
+   *
+   * @since 2.0.0
+   * @category combinators
+   */
   (n: number): <A, R>(self: RequestResolver<A, R>) => RequestResolver<A, R>
+  /**
+   * Returns a data source that executes at most `n` requests in parallel.
+   *
+   * @since 2.0.0
+   * @category combinators
+   */
   <A, R>(self: RequestResolver<A, R>, n: number): RequestResolver<A, R>
 } = internal.batchN
 
@@ -214,9 +290,21 @@ export const batchN: {
  * @category context
  */
 export const mapInputContext: {
+  /**
+   * Provides this data source with part of its required context.
+   *
+   * @since 2.0.0
+   * @category context
+   */
   <R0, R>(
     f: (context: Context.Context<R0>) => Context.Context<R>
   ): <A extends Request.Request<any, any>>(self: RequestResolver<A, R>) => RequestResolver<A, R0>
+  /**
+   * Provides this data source with part of its required context.
+   *
+   * @since 2.0.0
+   * @category context
+   */
   <R, A extends Request.Request<any, any>, R0>(
     self: RequestResolver<A, R>,
     f: (context: Context.Context<R0>) => Context.Context<R>
@@ -232,10 +320,26 @@ export const mapInputContext: {
  * @category combinators
  */
 export const eitherWith: {
+  /**
+   * Returns a new data source that executes requests of type `C` using the
+   * specified function to transform `C` requests into requests that either this
+   * data source or that data source can execute.
+   *
+   * @since 2.0.0
+   * @category combinators
+   */
   <A extends Request.Request<any, any>, R2, B extends Request.Request<any, any>, C extends Request.Request<any, any>>(
     that: RequestResolver<B, R2>,
     f: (_: Request.Entry<C>) => Either.Either<Request.Entry<B>, Request.Entry<A>>
   ): <R>(self: RequestResolver<A, R>) => RequestResolver<C, R2 | R>
+  /**
+   * Returns a new data source that executes requests of type `C` using the
+   * specified function to transform `C` requests into requests that either this
+   * data source or that data source can execute.
+   *
+   * @since 2.0.0
+   * @category combinators
+   */
   <
     R,
     A extends Request.Request<any, any>,
@@ -318,13 +422,22 @@ export const never: RequestResolver<never> = internal.never
  * @category context
  */
 export const provideContext: {
+  /**
+   * Provides this data source with its required context.
+   *
+   * @since 2.0.0
+   * @category context
+   */
   <R>(
     context: Context.Context<R>
   ): <A extends Request.Request<any, any>>(self: RequestResolver<A, R>) => RequestResolver<A>
-  <R, A extends Request.Request<any, any>>(
-    self: RequestResolver<A, R>,
-    context: Context.Context<R>
-  ): RequestResolver<A>
+  /**
+   * Provides this data source with its required context.
+   *
+   * @since 2.0.0
+   * @category context
+   */
+  <R, A extends Request.Request<any, any>>(self: RequestResolver<A, R>, context: Context.Context<R>): RequestResolver<A>
 } = internal.provideContext
 
 /**
@@ -336,9 +449,25 @@ export const provideContext: {
  * @category combinators
  */
 export const race: {
+  /**
+   * Returns a new data source that executes requests by sending them to this
+   * data source and that data source, returning the results from the first data
+   * source to complete and safely interrupting the loser.
+   *
+   * @since 2.0.0
+   * @category combinators
+   */
   <A2 extends Request.Request<any, any>, R2>(
     that: RequestResolver<A2, R2>
   ): <A extends Request.Request<any, any>, R>(self: RequestResolver<A, R>) => RequestResolver<A2 | A, R2 | R>
+  /**
+   * Returns a new data source that executes requests by sending them to this
+   * data source and that data source, returning the results from the first data
+   * source to complete and safely interrupting the loser.
+   *
+   * @since 2.0.0
+   * @category combinators
+   */
   <A extends Request.Request<any, any>, R, A2 extends Request.Request<any, any>, R2>(
     self: RequestResolver<A, R>,
     that: RequestResolver<A2, R2>
@@ -352,10 +481,22 @@ export const race: {
  * @category combinators
  */
 export const locally: {
+  /**
+   * Returns a new data source with a localized FiberRef
+   *
+   * @since 2.0.0
+   * @category combinators
+   */
   <A>(
     self: FiberRef<A>,
     value: A
   ): <R, B extends Request.Request<any, any>>(use: RequestResolver<B, R>) => RequestResolver<B, R>
+  /**
+   * Returns a new data source with a localized FiberRef
+   *
+   * @since 2.0.0
+   * @category combinators
+   */
   <R, B extends Request.Request<any, any>, A>(
     use: RequestResolver<B, R>,
     self: FiberRef<A>,

package/src/Resource.ts

@@ -8,6 +8,7 @@ import type * as Schedule from "./Schedule.js"
 import type * as Scope from "./Scope.js"
 import type * as ScopedRef from "./ScopedRef.js"
 import type * as Types from "./Types.js"
+import type * as Unify from "./Unify.js"
 
 /**
  * @since 2.0.0
@@ -28,11 +29,31 @@ export type ResourceTypeId = typeof ResourceTypeId
  * @since 2.0.0
  * @category models
  */
-export interface Resource<in out A, in out E = never> extends Resource.Variance<A, E> {
+export interface Resource<in out A, in out E = never> extends Effect.Effect<A, E>, Resource.Variance<A, E> {
   /** @internal */
   readonly scopedRef: ScopedRef.ScopedRef<Exit.Exit<A, E>>
   /** @internal */
   readonly acquire: Effect.Effect<A, E, Scope.Scope>
+
+  readonly [Unify.typeSymbol]?: unknown
+  readonly [Unify.unifySymbol]?: ResourceUnify<this>
+  readonly [Unify.ignoreSymbol]?: ResourceUnifyIgnore
+}
+
+/**
+ * @category models
+ * @since 3.9.0
+ */
+export interface ResourceUnify<A extends { [Unify.typeSymbol]?: any }> extends Effect.EffectUnify<A> {
+  Resource?: () => Extract<A[Unify.typeSymbol], Resource<any, any>>
+}
+
+/**
+ * @category models
+ * @since 3.9.0
+ */
+export interface ResourceUnifyIgnore extends Effect.EffectUnifyIgnore {
+  Effect?: true
 }
 
 /**

package/src/Runtime.ts

@@ -236,8 +236,19 @@ export const makeFiberFailure: <E>(cause: Cause<E>) => FiberFailure = internal.f
  * @category runtime flags
  */
 export const updateRuntimeFlags: {
+  /**
+   * @since 2.0.0
+   * @category runtime flags
+   */
   (f: (flags: RuntimeFlags.RuntimeFlags) => RuntimeFlags.RuntimeFlags): <R>(self: Runtime<R>) => Runtime<R>
-  <R>(self: Runtime<R>, f: (flags: RuntimeFlags.RuntimeFlags) => RuntimeFlags.RuntimeFlags): Runtime<R>
+  /**
+   * @since 2.0.0
+   * @category runtime flags
+   */
+  <R>(
+    self: Runtime<R>,
+    f: (flags: RuntimeFlags.RuntimeFlags) => RuntimeFlags.RuntimeFlags
+  ): Runtime<R>
 } = internal.updateRuntimeFlags
 
 /**
@@ -245,7 +256,15 @@ export const updateRuntimeFlags: {
  * @category runtime flags
  */
 export const enableRuntimeFlag: {
+  /**
+   * @since 2.0.0
+   * @category runtime flags
+   */
   (flag: RuntimeFlags.RuntimeFlag): <R>(self: Runtime<R>) => Runtime<R>
+  /**
+   * @since 2.0.0
+   * @category runtime flags
+   */
   <R>(self: Runtime<R>, flag: RuntimeFlags.RuntimeFlag): Runtime<R>
 } = internal.enableRuntimeFlag
 
@@ -254,7 +273,15 @@ export const enableRuntimeFlag: {
  * @category runtime flags
  */
 export const disableRuntimeFlag: {
+  /**
+   * @since 2.0.0
+   * @category runtime flags
+   */
   (flag: RuntimeFlags.RuntimeFlag): <R>(self: Runtime<R>) => Runtime<R>
+  /**
+   * @since 2.0.0
+   * @category runtime flags
+   */
   <R>(self: Runtime<R>, flag: RuntimeFlags.RuntimeFlag): Runtime<R>
 } = internal.disableRuntimeFlag
 
@@ -263,7 +290,15 @@ export const disableRuntimeFlag: {
  * @category context
  */
 export const updateContext: {
+  /**
+   * @since 2.0.0
+   * @category context
+   */
   <R, R2>(f: (context: Context.Context<R>) => Context.Context<R2>): (self: Runtime<R>) => Runtime<R2>
+  /**
+   * @since 2.0.0
+   * @category context
+   */
   <R, R2>(self: Runtime<R>, f: (context: Context.Context<R>) => Context.Context<R2>): Runtime<R2>
 } = internal.updateContext
 
@@ -280,7 +315,31 @@ export const updateContext: {
  * )
  */
 export const provideService: {
+  /**
+   * @since 2.0.0
+   * @category context
+   * @example
+   * import { Context, Runtime } from "effect"
+   *
+   * class Name extends Context.Tag("Name")<Name, string>() {}
+   *
+   * const runtime: Runtime.Runtime<Name> = Runtime.defaultRuntime.pipe(
+   *   Runtime.provideService(Name, "John")
+   * )
+   */
   <I, S>(tag: Context.Tag<I, S>, service: S): <R>(self: Runtime<R>) => Runtime<I | R>
+  /**
+   * @since 2.0.0
+   * @category context
+   * @example
+   * import { Context, Runtime } from "effect"
+   *
+   * class Name extends Context.Tag("Name")<Name, string>() {}
+   *
+   * const runtime: Runtime.Runtime<Name> = Runtime.defaultRuntime.pipe(
+   *   Runtime.provideService(Name, "John")
+   * )
+   */
   <R, I, S>(self: Runtime<R>, tag: Context.Tag<I, S>, service: S): Runtime<R | I>
 } = internal.provideService
 
@@ -289,8 +348,19 @@ export const provideService: {
  * @category fiber refs
  */
 export const updateFiberRefs: {
+  /**
+   * @since 2.0.0
+   * @category fiber refs
+   */
   (f: (fiberRefs: FiberRefs.FiberRefs) => FiberRefs.FiberRefs): <R>(self: Runtime<R>) => Runtime<R>
-  <R>(self: Runtime<R>, f: (fiberRefs: FiberRefs.FiberRefs) => FiberRefs.FiberRefs): Runtime<R>
+  /**
+   * @since 2.0.0
+   * @category fiber refs
+   */
+  <R>(
+    self: Runtime<R>,
+    f: (fiberRefs: FiberRefs.FiberRefs) => FiberRefs.FiberRefs
+  ): Runtime<R>
 } = internal.updateFiberRefs
 
 /**
@@ -309,7 +379,37 @@ export const updateFiberRefs: {
  * const result = Runtime.runSync(updatedRuntime)(FiberRef.get(ref))
  */
 export const setFiberRef: {
+  /**
+   * @since 2.0.0
+   * @category fiber refs
+   * @example
+   * import { Effect, FiberRef, Runtime } from "effect"
+   *
+   * const ref = FiberRef.unsafeMake(0)
+   *
+   * const updatedRuntime = Runtime.defaultRuntime.pipe(
+   *   Runtime.setFiberRef(ref, 1)
+   * )
+   *
+   * // returns 1
+   * const result = Runtime.runSync(updatedRuntime)(FiberRef.get(ref))
+   */
   <A>(fiberRef: FiberRef.FiberRef<A>, value: A): <R>(self: Runtime<R>) => Runtime<R>
+  /**
+   * @since 2.0.0
+   * @category fiber refs
+   * @example
+   * import { Effect, FiberRef, Runtime } from "effect"
+   *
+   * const ref = FiberRef.unsafeMake(0)
+   *
+   * const updatedRuntime = Runtime.defaultRuntime.pipe(
+   *   Runtime.setFiberRef(ref, 1)
+   * )
+   *
+   * // returns 1
+   * const result = Runtime.runSync(updatedRuntime)(FiberRef.get(ref))
+   */
   <R, A>(self: Runtime<R>, fiberRef: FiberRef.FiberRef<A>, value: A): Runtime<R>
 } = internal.setFiberRef
 
@@ -330,6 +430,38 @@ export const setFiberRef: {
  * const result = Runtime.runSync(updatedRuntime)(FiberRef.get(ref))
  */
 export const deleteFiberRef: {
+  /**
+   * @since 2.0.0
+   * @category fiber refs
+   * @example
+   * import { Effect, FiberRef, Runtime } from "effect"
+   *
+   * const ref = FiberRef.unsafeMake(0)
+   *
+   * const updatedRuntime = Runtime.defaultRuntime.pipe(
+   *   Runtime.setFiberRef(ref, 1),
+   *   Runtime.deleteFiberRef(ref)
+   * )
+   *
+   * // returns 0
+   * const result = Runtime.runSync(updatedRuntime)(FiberRef.get(ref))
+   */
   <A>(fiberRef: FiberRef.FiberRef<A>): <R>(self: Runtime<R>) => Runtime<R>
+  /**
+   * @since 2.0.0
+   * @category fiber refs
+   * @example
+   * import { Effect, FiberRef, Runtime } from "effect"
+   *
+   * const ref = FiberRef.unsafeMake(0)
+   *
+   * const updatedRuntime = Runtime.defaultRuntime.pipe(
+   *   Runtime.setFiberRef(ref, 1),
+   *   Runtime.deleteFiberRef(ref)
+   * )
+   *
+   * // returns 0
+   * const result = Runtime.runSync(updatedRuntime)(FiberRef.get(ref))
+   */
   <R, A>(self: Runtime<R>, fiberRef: FiberRef.FiberRef<A>): Runtime<R>
 } = internal.deleteFiberRef