effect 2.0.0-next.44 → 2.0.0-next.46

package/src/RequestResolver.ts

@@ -0,0 +1,305 @@
+/**
+ * @since 2.0.0
+ */
+
+import * as Context from "./Context"
+import * as Effect from "./Effect"
+import type * as Either from "./Either"
+import type * as Equal from "./Equal"
+import type { FiberRef } from "./FiberRef"
+import * as core from "./internal/core"
+import * as internal from "./internal/dataSource"
+import type { Pipeable } from "./Pipeable"
+import type * as Request from "./Request"
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export const RequestResolverTypeId: unique symbol = core.RequestResolverTypeId
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export type RequestResolverTypeId = typeof RequestResolverTypeId
+
+/**
+ * A `RequestResolver<A, R>` requires an environment `R` and is capable of executing
+ * requests of type `A`.
+ *
+ * Data sources must implement the method `runAll` which takes a collection of
+ * requests and returns an effect with a `RequestCompletionMap` containing a
+ * mapping from requests to results. The type of the collection of requests is
+ * a `Chunk<Chunk<A>>`. The outer `Chunk` represents batches of requests that
+ * must be performed sequentially. The inner `Chunk` represents a batch of
+ * requests that can be performed in parallel. This allows data sources to
+ * introspect on all the requests being executed and optimize the query.
+ *
+ * Data sources will typically be parameterized on a subtype of `Request<A>`,
+ * though that is not strictly necessarily as long as the data source can map
+ * the request type to a `Request<A>`. Data sources can then pattern match on
+ * the collection of requests to determine the information requested, execute
+ * the query, and place the results into the `RequestCompletionMap` using
+ * `RequestCompletionMap.empty` and `RequestCompletionMap.insert`. Data
+ * sources must provide results for all requests received. Failure to do so
+ * will cause a query to die with a `QueryFailure` when run.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export interface RequestResolver<A, R = never> extends Equal.Equal, Pipeable {
+  /**
+   * Execute a collection of requests. The outer `Chunk` represents batches
+   * of requests that must be performed sequentially. The inner `Chunk`
+   * represents a batch of requests that can be performed in parallel.
+   */
+  runAll(requests: Array<Array<Request.Entry<A>>>): Effect.Effect<R, never, void>
+
+  /**
+   * Identify the data source using the specific identifier
+   */
+  identified(...identifiers: Array<unknown>): RequestResolver<A, R>
+}
+
+/**
+ * @since 2.0.0
+ */
+export declare namespace RequestResolver {
+  /**
+   * @since 2.0.0
+   * @category models
+   */
+  export interface Variance<R, A> {
+    readonly [RequestResolverTypeId]: {
+      readonly _R: (_: never) => R
+      readonly _A: (_: never) => A
+    }
+  }
+}
+
+/**
+ * @since 2.0.0
+ * @category utils
+ */
+export const contextFromEffect = <R, A extends Request.Request<any, any>>(self: RequestResolver<A, R>) =>
+  Effect.contextWith((_: Context.Context<R>) => provideContext(self, _))
+
+/**
+ * @since 2.0.0
+ * @category utils
+ */
+export const contextFromServices =
+  <Services extends Array<Context.Tag<any, any>>>(...services: Services) =>
+  <R, A extends Request.Request<any, any>>(
+    self: RequestResolver<A, R>
+  ): Effect.Effect<
+    { [k in keyof Services]: Effect.Effect.Context<Services[k]> }[number],
+    never,
+    RequestResolver<A, Exclude<R, { [k in keyof Services]: Effect.Effect.Context<Services[k]> }[number]>>
+  > => Effect.contextWith((_) => provideContext(self as any, Context.pick(...services)(_ as any)))
+
+/**
+ * Returns `true` if the specified value is a `RequestResolver`, `false` otherwise.
+ *
+ * @since 2.0.0
+ * @category refinements
+ */
+export const isRequestResolver: (u: unknown) => u is RequestResolver<unknown, unknown> = core.isRequestResolver
+
+/**
+ * Constructs a data source with the specified identifier and method to run
+ * requests.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const make: <R, A>(
+  runAll: (requests: Array<Array<A>>) => Effect.Effect<R, never, void>
+) => RequestResolver<A, R> = internal.make
+
+/**
+ * Constructs a data source with the specified identifier and method to run
+ * requests.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const makeWithEntry: <R, A>(
+  runAll: (requests: Array<Array<Request.Entry<A>>>) => Effect.Effect<R, never, void>
+) => RequestResolver<A, R> = internal.makeWithEntry
+
+/**
+ * Constructs a data source from a function taking a collection of requests
+ * and returning a `RequestCompletionMap`.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const makeBatched: <R, A extends Request.Request<any, any>>(
+  run: (requests: Array<A>) => Effect.Effect<R, never, void>
+) => RequestResolver<A, R> = internal.makeBatched
+
+/**
+ * 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
+ */
+export const around: {
+  <R2, A2, R3, _>(
+    before: Effect.Effect<R2, never, A2>,
+    after: (a: A2) => Effect.Effect<R3, never, _>
+  ): <R, A>(self: RequestResolver<A, R>) => RequestResolver<A, R2 | R3 | R>
+  <R, A, R2, A2, R3, _>(
+    self: RequestResolver<A, R>,
+    before: Effect.Effect<R2, never, A2>,
+    after: (a: A2) => Effect.Effect<R3, never, _>
+  ): RequestResolver<A, R | R2 | R3>
+} = internal.around
+
+/**
+ * Returns a data source that executes at most `n` requests in parallel.
+ *
+ * @since 2.0.0
+ * @category combinators
+ */
+export const batchN: {
+  (n: number): <R, A>(self: RequestResolver<A, R>) => RequestResolver<A, R>
+  <R, A>(self: RequestResolver<A, R>, n: number): RequestResolver<A, R>
+} = internal.batchN
+
+/**
+ * Provides this data source with part of its required context.
+ *
+ * @since 2.0.0
+ * @category context
+ */
+export const mapInputContext: {
+  <R0, R>(
+    f: (context: Context.Context<R0>) => Context.Context<R>
+  ): <A extends Request.Request<any, any>>(self: RequestResolver<A, R>) => RequestResolver<A, R0>
+  <R, A extends Request.Request<any, any>, R0>(
+    self: RequestResolver<A, R>,
+    f: (context: Context.Context<R0>) => Context.Context<R>
+  ): RequestResolver<A, R0>
+} = internal.mapInputContext
+
+/**
+ * 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
+ */
+export const eitherWith: {
+  <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<A>, Request.Entry<B>>
+  ): <R>(self: RequestResolver<A, R>) => RequestResolver<C, R2 | R>
+  <
+    R,
+    A extends Request.Request<any, any>,
+    R2,
+    B extends Request.Request<any, any>,
+    C extends Request.Request<any, any>
+  >(
+    self: RequestResolver<A, R>,
+    that: RequestResolver<B, R2>,
+    f: (_: Request.Entry<C>) => Either.Either<Request.Entry<A>, Request.Entry<B>>
+  ): RequestResolver<C, R | R2>
+} = internal.eitherWith
+
+/**
+ * Constructs a data source from a pure function.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const fromFunction: <A extends Request.Request<never, any>>(
+  f: (request: A) => Request.Request.Success<A>
+) => RequestResolver<A, never> = internal.fromFunction
+
+/**
+ * Constructs a data source from a pure function that takes a list of requests
+ * and returns a list of results of the same size. Each item in the result
+ * list must correspond to the item at the same index in the request list.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const fromFunctionBatched: <A extends Request.Request<never, any>>(
+  f: (chunk: Array<A>) => Array<Request.Request.Success<A>>
+) => RequestResolver<A, never> = internal.fromFunctionBatched
+
+/**
+ * Constructs a data source from an effectual function.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const fromFunctionEffect: <R, A extends Request.Request<any, any>>(
+  f: (a: A) => Effect.Effect<R, Request.Request.Error<A>, Request.Request.Success<A>>
+) => RequestResolver<A, R> = internal.fromFunctionEffect
+
+/**
+ * A data source that never executes requests.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const never: RequestResolver<never, never> = internal.never
+
+/**
+ * Provides this data source with its required context.
+ *
+ * @since 2.0.0
+ * @category context
+ */
+export const provideContext: {
+  <R>(
+    context: Context.Context<R>
+  ): <A extends Request.Request<any, any>>(self: RequestResolver<A, R>) => RequestResolver<A, never>
+  <R, A extends Request.Request<any, any>>(
+    self: RequestResolver<A, R>,
+    context: Context.Context<R>
+  ): RequestResolver<A, never>
+} = internal.provideContext
+
+/**
+ * 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
+ */
+export const race: {
+  <R2, A2 extends Request.Request<any, any>>(
+    that: RequestResolver<A2, R2>
+  ): <R, A extends Request.Request<any, any>>(self: RequestResolver<A, R>) => RequestResolver<A2 | A, R2 | R>
+  <R, A extends Request.Request<any, any>, R2, A2 extends Request.Request<any, any>>(
+    self: RequestResolver<A, R>,
+    that: RequestResolver<A2, R2>
+  ): RequestResolver<A | A2, R | R2>
+} = internal.race
+
+/**
+ * Returns a new data source with a localized FiberRef
+ *
+ * @since 2.0.0
+ * @category combinators
+ */
+export const locally: {
+  <A>(
+    self: FiberRef<A>,
+    value: A
+  ): <R, B extends Request.Request<any, any>>(use: RequestResolver<B, R>) => RequestResolver<B, R>
+  <R, B extends Request.Request<any, any>, A>(
+    use: RequestResolver<B, R>,
+    self: FiberRef<A>,
+    value: A
+  ): RequestResolver<B, R>
+} = core.resolverLocally

package/src/Resource.ts

@@ -0,0 +1,97 @@
+/**
+ * @since 2.0.0
+ */
+import type * as Effect from "./Effect"
+import type * as Exit from "./Exit"
+import * as internal from "./internal/resource"
+import type * as Schedule from "./Schedule"
+import type * as Scope from "./Scope"
+import type * as ScopedRef from "./ScopedRef"
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export const ResourceTypeId: unique symbol = internal.ResourceTypeId
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export type ResourceTypeId = typeof ResourceTypeId
+
+/**
+ * A `Resource` is a possibly resourceful value that is loaded into memory, and
+ * which can be refreshed either manually or automatically.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export interface Resource<E, A> extends Resource.Variance<E, A> {
+  /** @internal */
+  readonly scopedRef: ScopedRef.ScopedRef<Exit.Exit<E, A>>
+  /** @internal */
+  acquire(): Effect.Effect<Scope.Scope, E, A>
+}
+
+/**
+ * @since 2.0.0
+ */
+export declare namespace Resource {
+  /**
+   * @since 2.0.0
+   * @category models
+   */
+  export interface Variance<E, A> {
+    readonly [ResourceTypeId]: {
+      _E: (_: never) => E
+      _A: (_: never) => A
+    }
+  }
+}
+
+/**
+ * Creates a new `Resource` value that is automatically refreshed according to
+ * the specified policy. Note that error retrying is not performed
+ * automatically, so if you want to retry on errors, you should first apply
+ * retry policies to the acquisition effect before passing it to this
+ * constructor.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const auto: <R, E, A, R2, Out>(
+  acquire: Effect.Effect<R, E, A>,
+  policy: Schedule.Schedule<R2, unknown, Out>
+) => Effect.Effect<Scope.Scope | R | R2, never, Resource<E, A>> = internal.auto
+
+/**
+ * Retrieves the current value stored in the cache.
+ *
+ * @since 2.0.0
+ * @category getters
+ */
+export const get: <E, A>(self: Resource<E, A>) => Effect.Effect<never, E, A> = internal.get
+
+/**
+ * Creates a new `Resource` value that must be manually refreshed by calling
+ * the refresh method. Note that error retrying is not performed
+ * automatically, so if you want to retry on errors, you should first apply
+ * retry policies to the acquisition effect before passing it to this
+ * constructor.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const manual: <R, E, A>(
+  acquire: Effect.Effect<R, E, A>
+) => Effect.Effect<Scope.Scope | R, never, Resource<E, A>> = internal.manual
+
+/**
+ * Refreshes the cache. This method will not return until either the refresh
+ * is successful, or the refresh operation fails.
+ *
+ * @since 2.0.0
+ * @category utils
+ */
+export const refresh: <E, A>(self: Resource<E, A>) => Effect.Effect<never, E, void> = internal.refresh

package/src/Runtime.ts

@@ -0,0 +1,216 @@
+/**
+ * @since 2.0.0
+ */
+import type { Cause } from "./Cause"
+import type * as Context from "./Context"
+import type * as Effect from "./Effect"
+import type * as Exit from "./Exit"
+import type * as Fiber from "./Fiber"
+import type * as FiberId from "./FiberId"
+import type * as FiberRefs from "./FiberRefs"
+import type { Inspectable } from "./Inspectable"
+import * as internal from "./internal/runtime"
+import type { Pipeable } from "./Pipeable"
+import type * as RuntimeFlags from "./RuntimeFlags"
+import type { Scheduler } from "./Scheduler"
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface AsyncFiberException<E, A> {
+  readonly _tag: "AsyncFiberException"
+  readonly fiber: Fiber.RuntimeFiber<E, A>
+}
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface Cancel<E, A> {
+  (fiberId?: FiberId.FiberId, onExit?: (exit: Exit.Exit<E, A>) => void): void
+}
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface Runtime<R> extends Pipeable {
+  /**
+   * The context used as initial for forks
+   */
+  readonly context: Context.Context<R>
+  /**
+   * The runtime flags used as initial for forks
+   */
+  readonly runtimeFlags: RuntimeFlags.RuntimeFlags
+  /**
+   * The fiber references used as initial for forks
+   */
+  readonly fiberRefs: FiberRefs.FiberRefs
+}
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface RunForkOptions {
+  scheduler?: Scheduler
+  updateRefs?: (refs: FiberRefs.FiberRefs, fiberId: FiberId.Runtime) => FiberRefs.FiberRefs
+}
+
+/**
+ * Executes the effect using the provided Scheduler or using the global
+ * Scheduler if not provided
+ *
+ * @since 2.0.0
+ * @category execution
+ */
+export const runFork: <R>(
+  runtime: Runtime<R>
+) => <E, A>(self: Effect.Effect<R, E, A>, options?: RunForkOptions | undefined) => Fiber.RuntimeFiber<E, A> =
+  internal.unsafeFork
+
+/**
+ * Executes the effect synchronously returning the exit.
+ *
+ * This method is effectful and should only be invoked at the edges of your
+ * program.
+ *
+ * @since 2.0.0
+ * @category execution
+ */
+export const runSyncExit: <R>(runtime: Runtime<R>) => <E, A>(effect: Effect.Effect<R, E, A>) => Exit.Exit<E, A> =
+  internal.unsafeRunSyncExit
+
+/**
+ * Executes the effect synchronously throwing in case of errors or async boundaries.
+ *
+ * This method is effectful and should only be invoked at the edges of your
+ * program.
+ *
+ * @since 2.0.0
+ * @category execution
+ */
+export const runSync: <R>(runtime: Runtime<R>) => <E, A>(effect: Effect.Effect<R, E, A>) => A = internal.unsafeRunSync
+
+/**
+ * Executes the effect asynchronously, eventually passing the exit value to
+ * the specified callback.
+ *
+ * This method is effectful and should only be invoked at the edges of your
+ * program.
+ *
+ * @since 2.0.0
+ * @category execution
+ */
+export const runCallback: <R>(
+  runtime: Runtime<R>
+) => <E, A>(
+  effect: Effect.Effect<R, E, A>,
+  onExit?: ((exit: Exit.Exit<E, A>) => void) | undefined
+) => (fiberId?: FiberId.FiberId | undefined, onExit?: ((exit: Exit.Exit<E, A>) => void) | undefined) => void =
+  internal.unsafeRunCallback
+
+/**
+ * Runs the `Effect`, returning a JavaScript `Promise` that will be resolved
+ * with the value of the effect once the effect has been executed, or will be
+ * rejected with the first error or exception throw by the effect.
+ *
+ * This method is effectful and should only be used at the edges of your
+ * program.
+ *
+ * @since 2.0.0
+ * @category execution
+ */
+export const runPromise: <R>(runtime: Runtime<R>) => <E, A>(effect: Effect.Effect<R, E, A>) => Promise<A> =
+  internal.unsafeRunPromise
+
+/**
+ * Runs the `Effect`, returning a JavaScript `Promise` that will be resolved
+ * with the `Exit` state of the effect once the effect has been executed.
+ *
+ * This method is effectful and should only be used at the edges of your
+ * program.
+ *
+ * @since 2.0.0
+ * @category execution
+ */
+export const runPromiseExit: <R>(
+  runtime: Runtime<R>
+) => <E, A>(effect: Effect.Effect<R, E, A>) => Promise<Exit.Exit<E, A>> = internal.unsafeRunPromiseExit
+
+/**
+ * @since 2.0.0
+ * @category constructors
+ */
+export const defaultRuntime: Runtime<never> = internal.defaultRuntime
+
+/**
+ * @since 2.0.0
+ * @category constructors
+ */
+export const defaultRuntimeFlags: RuntimeFlags.RuntimeFlags = internal.defaultRuntimeFlags
+
+/**
+ * @since 2.0.0
+ * @category constructors
+ */
+export const make: <R>(
+  options: {
+    readonly context: Context.Context<R>
+    readonly runtimeFlags: RuntimeFlags.RuntimeFlags
+    readonly fiberRefs: FiberRefs.FiberRefs
+  }
+) => Runtime<R> = internal.make
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export const FiberFailureId = Symbol.for("effect/Runtime/FiberFailure")
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export type FiberFailureId = typeof FiberFailureId
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export const FiberFailureCauseId: unique symbol = internal.FiberFailureCauseId
+
+/**
+ * @since 2.0.0
+ * @category exports
+ */
+export type FiberFailureCauseId = typeof FiberFailureCauseId
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface FiberFailure extends Error, Inspectable {
+  readonly [FiberFailureId]: FiberFailureId
+  readonly [FiberFailureCauseId]: Cause<unknown>
+}
+
+/**
+ * @since 2.0.0
+ * @category guards
+ */
+export const isAsyncFiberException: (u: unknown) => u is AsyncFiberException<unknown, unknown> =
+  internal.isAsyncFiberException
+
+/**
+ * @since 2.0.0
+ * @category guards
+ */
+export const isFiberFailure: (u: unknown) => u is FiberFailure = internal.isFiberFailure
+
+/**
+ * @since 2.0.0
+ * @category constructors
+ */
+export const makeFiberFailure: <E>(cause: Cause<E>) => FiberFailure = internal.fiberFailure