@clayroach/effect 3.19.14-source-capture.8 → 3.19.14-source-trace.1

package/src/Runtime.ts

@@ -0,0 +1,383 @@
+/**
+ * @since 2.0.0
+ */
+import type { Cause } from "./Cause.js"
+import type * as Context from "./Context.js"
+import type * as Effect from "./Effect.js"
+import type * as Exit from "./Exit.js"
+import type * as Fiber from "./Fiber.js"
+import type * as FiberId from "./FiberId.js"
+import type * as FiberRef from "./FiberRef.js"
+import type * as FiberRefs from "./FiberRefs.js"
+import type { Inspectable } from "./Inspectable.js"
+import * as internal from "./internal/runtime.js"
+import type { Pipeable } from "./Pipeable.js"
+import type * as RuntimeFlags from "./RuntimeFlags.js"
+import type { Scheduler } from "./Scheduler.js"
+import type { Scope } from "./Scope.js"
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface AsyncFiberException<out A, out E = never> {
+  readonly _tag: "AsyncFiberException"
+  readonly fiber: Fiber.RuntimeFiber<A, E>
+}
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface Cancel<out A, out E = never> {
+  (fiberId?: FiberId.FiberId, options?: RunCallbackOptions<A, E> | undefined): void
+}
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface Runtime<in 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 3.12.0
+ */
+export declare namespace Runtime {
+  /**
+   * @since 3.12.0
+   * @category Type Extractors
+   */
+  export type Context<T extends Runtime<never>> = [T] extends [Runtime<infer R>] ? R : never
+}
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface RunForkOptions {
+  readonly scheduler?: Scheduler | undefined
+  readonly updateRefs?: ((refs: FiberRefs.FiberRefs, fiberId: FiberId.Runtime) => FiberRefs.FiberRefs) | undefined
+  readonly immediate?: boolean
+  readonly scope?: Scope
+}
+
+/**
+ * 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>
+  ): <A, E>(effect: Effect.Effect<A, E, R>, options?: RunForkOptions | undefined) => Fiber.RuntimeFiber<A, E>
+  <R, A, E>(
+    runtime: Runtime<R>,
+    effect: Effect.Effect<A, E, R>,
+    options?: RunForkOptions | undefined
+  ): Fiber.RuntimeFiber<A, E>
+} = 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: {
+  <A, E, R>(runtime: Runtime<R>, effect: Effect.Effect<A, E, R>): Exit.Exit<A, E>
+  <R>(runtime: Runtime<R>): <A, E>(effect: Effect.Effect<A, E, R>) => Exit.Exit<A, E>
+} = 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: {
+  <A, E, R>(runtime: Runtime<R>, effect: Effect.Effect<A, E, R>): A
+  <R>(runtime: Runtime<R>): <A, E>(effect: Effect.Effect<A, E, R>) => A
+} = internal.unsafeRunSync
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface RunCallbackOptions<in A, in E = never> extends RunForkOptions {
+  readonly onExit?: ((exit: Exit.Exit<A, E>) => void) | undefined
+}
+
+/**
+ * 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>
+  ): <A, E>(
+    effect: Effect.Effect<A, E, R>,
+    options?: RunCallbackOptions<A, E> | undefined
+  ) => (fiberId?: FiberId.FiberId, options?: RunCallbackOptions<A, E> | undefined) => void
+  <R, A, E>(
+    runtime: Runtime<R>,
+    effect: Effect.Effect<A, E, R>,
+    options?: RunCallbackOptions<A, E> | undefined
+  ): (fiberId?: FiberId.FiberId, options?: RunCallbackOptions<A, E> | 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>
+  ): <A, E>(effect: Effect.Effect<A, E, R>, options?: { readonly signal?: AbortSignal } | undefined) => Promise<A>
+  <R, A, E>(
+    runtime: Runtime<R>,
+    effect: Effect.Effect<A, E, R>,
+    options?: { readonly signal?: AbortSignal } | undefined
+  ): 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>
+  ): <A, E>(
+    effect: Effect.Effect<A, E, R>,
+    options?: { readonly signal?: AbortSignal } | undefined
+  ) => Promise<Exit.Exit<A, E>>
+  <R, A, E>(
+    runtime: Runtime<R>,
+    effect: Effect.Effect<A, E, R>,
+    options?: { readonly signal?: AbortSignal } | undefined
+  ): Promise<Exit.Exit<A, E>>
+} = 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
+
+/**
+ * @since 2.0.0
+ * @category runtime flags
+ */
+export const updateRuntimeFlags: {
+  (f: (flags: RuntimeFlags.RuntimeFlags) => RuntimeFlags.RuntimeFlags): <R>(self: Runtime<R>) => Runtime<R>
+  <R>(self: Runtime<R>, f: (flags: RuntimeFlags.RuntimeFlags) => RuntimeFlags.RuntimeFlags): Runtime<R>
+} = internal.updateRuntimeFlags
+
+/**
+ * @since 2.0.0
+ * @category runtime flags
+ */
+export const enableRuntimeFlag: {
+  (flag: RuntimeFlags.RuntimeFlag): <R>(self: Runtime<R>) => Runtime<R>
+  <R>(self: Runtime<R>, flag: RuntimeFlags.RuntimeFlag): Runtime<R>
+} = internal.enableRuntimeFlag
+
+/**
+ * @since 2.0.0
+ * @category runtime flags
+ */
+export const disableRuntimeFlag: {
+  (flag: RuntimeFlags.RuntimeFlag): <R>(self: Runtime<R>) => Runtime<R>
+  <R>(self: Runtime<R>, flag: RuntimeFlags.RuntimeFlag): Runtime<R>
+} = internal.disableRuntimeFlag
+
+/**
+ * @since 2.0.0
+ * @category context
+ */
+export const updateContext: {
+  <R, R2>(f: (context: Context.Context<R>) => Context.Context<R2>): (self: Runtime<R>) => Runtime<R2>
+  <R, R2>(self: Runtime<R>, f: (context: Context.Context<R>) => Context.Context<R2>): Runtime<R2>
+} = internal.updateContext
+
+/**
+ * @since 2.0.0
+ * @category context
+ * @example
+ * ```ts
+ * 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")
+ * )
+ * ```
+ */
+export const provideService: {
+  <I, S>(tag: Context.Tag<I, S>, service: S): <R>(self: Runtime<R>) => Runtime<I | R>
+  <R, I, S>(self: Runtime<R>, tag: Context.Tag<I, S>, service: S): Runtime<R | I>
+} = internal.provideService
+
+/**
+ * @since 2.0.0
+ * @category fiber refs
+ */
+export const updateFiberRefs: {
+  (f: (fiberRefs: FiberRefs.FiberRefs) => FiberRefs.FiberRefs): <R>(self: Runtime<R>) => Runtime<R>
+  <R>(self: Runtime<R>, f: (fiberRefs: FiberRefs.FiberRefs) => FiberRefs.FiberRefs): Runtime<R>
+} = internal.updateFiberRefs
+
+/**
+ * @since 2.0.0
+ * @category fiber refs
+ * @example
+ * ```ts
+ * 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))
+ * ```
+ */
+export const setFiberRef: {
+  <A>(fiberRef: FiberRef.FiberRef<A>, value: A): <R>(self: Runtime<R>) => Runtime<R>
+  <R, A>(self: Runtime<R>, fiberRef: FiberRef.FiberRef<A>, value: A): Runtime<R>
+} = internal.setFiberRef
+
+/**
+ * @since 2.0.0
+ * @category fiber refs
+ * @example
+ * ```ts
+ * 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))
+ * ```
+ */
+export const deleteFiberRef: {
+  <A>(fiberRef: FiberRef.FiberRef<A>): <R>(self: Runtime<R>) => Runtime<R>
+  <R, A>(self: Runtime<R>, fiberRef: FiberRef.FiberRef<A>): Runtime<R>
+} = internal.deleteFiberRef

package/src/RuntimeFlags.ts

@@ -0,0 +1,336 @@
+/**
+ * @since 2.0.0
+ */
+
+import type * as Differ from "./Differ.js"
+import * as circular from "./internal/layer/circular.js"
+import * as internal from "./internal/runtimeFlags.js"
+import type * as Layer from "./Layer.js"
+import type * as RuntimeFlagsPatch from "./RuntimeFlagsPatch.js"
+
+/**
+ * Represents a set of `RuntimeFlag`s. `RuntimeFlag`s affect the operation of
+ * the Effect runtime system. They are exposed to application-level code because
+ * they affect the behavior and performance of application code.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export type RuntimeFlags = number & {
+  readonly RuntimeFlags: unique symbol
+}
+
+/**
+ * Represents a flag that can be set to enable or disable a particular feature
+ * of the Effect runtime.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export type RuntimeFlag = number & {
+  readonly RuntimeFlag: unique symbol
+}
+
+/**
+ * No runtime flags.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const None: RuntimeFlag = internal.None
+
+/**
+ * The interruption flag determines whether or not the Effect runtime system will
+ * interrupt a fiber.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const Interruption: RuntimeFlag = internal.Interruption
+
+/**
+ * The op supervision flag determines whether or not the Effect runtime system
+ * will supervise all operations of the Effect runtime. Use of this flag will
+ * negatively impact performance, but is required for some operations, such as
+ * profiling.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const OpSupervision: RuntimeFlag = internal.OpSupervision
+
+/**
+ * The runtime metrics flag determines whether or not the Effect runtime system
+ * will collect metrics about the Effect runtime. Use of this flag will have a
+ * very small negative impact on performance, but generates very helpful
+ * operational insight into running Effect applications that can be exported to
+ * Prometheus or other tools via Effect Metrics.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const RuntimeMetrics: RuntimeFlag = internal.RuntimeMetrics
+
+/**
+ * The wind down flag determines whether the Effect runtime system will execute
+ * effects in wind-down mode. In wind-down mode, even if interruption is
+ * enabled and a fiber has been interrupted, the fiber will continue its
+ * execution uninterrupted.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const WindDown: RuntimeFlag = internal.WindDown
+
+/**
+ * The cooperative yielding flag determines whether the Effect runtime will
+ * yield to another fiber.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const CooperativeYielding: RuntimeFlag = internal.CooperativeYielding
+
+/**
+ * Returns `true` if the `CooperativeYielding` `RuntimeFlag` is enabled, `false`
+ * otherwise.
+ *
+ * @since 2.0.0
+ * @category getters
+ */
+export const cooperativeYielding: (self: RuntimeFlags) => boolean = internal.cooperativeYielding
+
+/**
+ * Creates a `RuntimeFlagsPatch` which describes the difference between `self`
+ * and `that`.
+ *
+ * @since 2.0.0
+ * @category diffing
+ */
+export const diff: {
+  (that: RuntimeFlags): (self: RuntimeFlags) => RuntimeFlagsPatch.RuntimeFlagsPatch
+  (self: RuntimeFlags, that: RuntimeFlags): RuntimeFlagsPatch.RuntimeFlagsPatch
+} = internal.diff
+
+/**
+ * Constructs a differ that knows how to diff `RuntimeFlags` values.
+ *
+ * @since 2.0.0
+ * @category utils
+ */
+export const differ: Differ.Differ<RuntimeFlags, RuntimeFlagsPatch.RuntimeFlagsPatch> = internal.differ
+
+/**
+ * Disables the specified `RuntimeFlag`.
+ *
+ * @since 2.0.0
+ * @category utils
+ */
+export const disable: {
+  (flag: RuntimeFlag): (self: RuntimeFlags) => RuntimeFlags
+  (self: RuntimeFlags, flag: RuntimeFlag): RuntimeFlags
+} = internal.disable
+
+/**
+ * Disables all of the `RuntimeFlag`s in the specified set of `RuntimeFlags`.
+ *
+ * @since 2.0.0
+ * @category utils
+ */
+export const disableAll: {
+  (flags: RuntimeFlags): (self: RuntimeFlags) => RuntimeFlags
+  (self: RuntimeFlags, flags: RuntimeFlags): RuntimeFlags
+} = internal.disableAll
+
+/**
+ * @since 2.0.0
+ * @category context
+ */
+export const disableCooperativeYielding: Layer.Layer<never> = circular.disableCooperativeYielding
+
+/**
+ * @since 2.0.0
+ * @category context
+ */
+export const disableInterruption: Layer.Layer<never> = circular.disableInterruption
+
+/**
+ * @since 2.0.0
+ * @category context
+ */
+export const disableOpSupervision: Layer.Layer<never> = circular.disableOpSupervision
+
+/**
+ * @since 2.0.0
+ * @category context
+ */
+export const disableRuntimeMetrics: Layer.Layer<never> = circular.disableRuntimeMetrics
+
+/**
+ * @since 2.0.0
+ * @category context
+ */
+export const disableWindDown: Layer.Layer<never> = circular.disableWindDown
+
+/**
+ * Enables the specified `RuntimeFlag`.
+ *
+ * @since 2.0.0
+ * @category utils
+ */
+export const enable: {
+  (flag: RuntimeFlag): (self: RuntimeFlags) => RuntimeFlags
+  (self: RuntimeFlags, flag: RuntimeFlag): RuntimeFlags
+} = internal.enable
+
+/**
+ * Enables all of the `RuntimeFlag`s in the specified set of `RuntimeFlags`.
+ *
+ * @since 2.0.0
+ * @category utils
+ */
+export const enableAll: {
+  (flags: RuntimeFlags): (self: RuntimeFlags) => RuntimeFlags
+  (self: RuntimeFlags, flags: RuntimeFlags): RuntimeFlags
+} = internal.enableAll
+
+/**
+ * @since 2.0.0
+ * @category context
+ */
+export const enableCooperativeYielding: Layer.Layer<never> = circular.enableCooperativeYielding
+
+/**
+ * @since 2.0.0
+ * @category context
+ */
+export const enableInterruption: Layer.Layer<never> = circular.enableInterruption
+
+/**
+ * @since 2.0.0
+ * @category context
+ */
+export const enableOpSupervision: Layer.Layer<never> = circular.enableOpSupervision
+
+/**
+ * @since 2.0.0
+ * @category context
+ */
+export const enableRuntimeMetrics: Layer.Layer<never> = circular.enableRuntimeMetrics
+
+/**
+ * @since 2.0.0
+ * @category context
+ */
+export const enableWindDown: Layer.Layer<never> = circular.enableWindDown
+
+/**
+ * Returns true only if the `Interruption` flag is **enabled** and the
+ * `WindDown` flag is **disabled**.
+ *
+ * A fiber is said to be interruptible if interruption is enabled and the fiber
+ * is not in its wind-down phase, in which it takes care of cleanup activities
+ * related to fiber shutdown.
+ *
+ * @since 2.0.0
+ * @category getters
+ */
+export const interruptible: (self: RuntimeFlags) => boolean = internal.interruptible
+
+/**
+ * Returns `true` if the `Interruption` `RuntimeFlag` is enabled, `false`
+ * otherwise.
+ *
+ * @since 2.0.0
+ * @category getters
+ */
+export const interruption: (self: RuntimeFlags) => boolean = internal.interruption
+
+/**
+ * Returns `true` if the specified `RuntimeFlag` is enabled, `false` otherwise.
+ *
+ * @since 2.0.0
+ * @category elements
+ */
+export const isEnabled: {
+  (flag: RuntimeFlag): (self: RuntimeFlags) => boolean
+  (self: RuntimeFlags, flag: RuntimeFlag): boolean
+} = internal.isEnabled
+
+/**
+ * Returns `true` if the specified `RuntimeFlag` is disabled, `false` otherwise.
+ *
+ * @since 2.0.0
+ * @category elements
+ */
+export const isDisabled: {
+  (flag: RuntimeFlag): (self: RuntimeFlags) => boolean
+  (self: RuntimeFlags, flag: RuntimeFlag): boolean
+} = internal.isDisabled
+
+/**
+ * @since 2.0.0
+ * @category constructors
+ */
+export const make: (...flags: ReadonlyArray<RuntimeFlag>) => RuntimeFlags = internal.make
+
+/**
+ * @since 2.0.0
+ * @category constructors
+ */
+export const none: RuntimeFlags = internal.none
+
+/**
+ * Returns `true` if the `OpSupervision` `RuntimeFlag` is enabled, `false`
+ * otherwise.
+ *
+ * @since 2.0.0
+ * @category getters
+ */
+export const opSupervision: (self: RuntimeFlags) => boolean = internal.opSupervision
+
+/**
+ * Patches a set of `RuntimeFlag`s with a `RuntimeFlagsPatch`, returning the
+ * patched set of `RuntimeFlag`s.
+ *
+ * @since 2.0.0
+ * @category utils
+ */
+export const patch: {
+  (patch: RuntimeFlagsPatch.RuntimeFlagsPatch): (self: RuntimeFlags) => RuntimeFlags
+  (self: RuntimeFlags, patch: RuntimeFlagsPatch.RuntimeFlagsPatch): RuntimeFlags
+} = internal.patch
+
+/**
+ * Converts the provided `RuntimeFlags` into a `string`.
+ *
+ * @category conversions
+ * @since 2.0.0
+ */
+export const render: (self: RuntimeFlags) => string = internal.render
+
+/**
+ * Returns `true` if the `RuntimeMetrics` `RuntimeFlag` is enabled, `false`
+ * otherwise.
+ *
+ * @since 2.0.0
+ * @category getters
+ */
+export const runtimeMetrics: (self: RuntimeFlags) => boolean = internal.runtimeMetrics
+
+/**
+ * Converts the provided `RuntimeFlags` into a `ReadonlySet<number>`.
+ *
+ * @category conversions
+ * @since 2.0.0
+ */
+export const toSet: (self: RuntimeFlags) => ReadonlySet<RuntimeFlag> = internal.toSet
+
+/**
+ * Returns `true` if the `WindDown` `RuntimeFlag` is enabled, `false`
+ * otherwise.
+ *
+ * @since 2.0.0
+ * @category getters
+ */
+export const windDown: (self: RuntimeFlags) => boolean = internal.windDown