10642 lines
330 KiB
JavaScript
10642 lines
330 KiB
JavaScript
"use strict";
|
||
|
||
Object.defineProperty(exports, "__esModule", {
|
||
value: true
|
||
});
|
||
exports.forEach = exports.fnUntraced = exports.fn = exports.flipWith = exports.flip = exports.flatten = exports.flatMap = exports.firstSuccessOf = exports.findFirst = exports.finalizersMask = exports.filterOrFail = exports.filterOrElse = exports.filterOrDieMessage = exports.filterOrDie = exports.filterMap = exports.filterEffectOrFail = exports.filterEffectOrElse = exports.filter = exports.fiberIdWith = exports.fiberId = exports.failSync = exports.failCauseSync = exports.failCause = exports.fail = exports.exit = exports.exists = exports.every = exports.eventually = exports.ensuringChildren = exports.ensuringChild = exports.ensuring = exports.either = exports.dropWhile = exports.dropUntil = exports.disconnect = exports.diffFiberRefs = exports.dieSync = exports.dieMessage = exports.die = exports.descriptorWith = exports.descriptor = exports.delay = exports.daemonChildren = exports.custom = exports.currentSpan = exports.currentParentSpan = exports.contextWithEffect = exports.contextWith = exports.context = exports.consoleWith = exports.console = exports.configProviderWith = exports.clockWith = exports.clock = exports.checkInterruptible = exports.cause = exports.catchTags = exports.catchTag = exports.catchSomeDefect = exports.catchSomeCause = exports.catchSome = exports.catchIf = exports.catchAllDefect = exports.catchAllCause = exports.catchAll = exports.catch = exports.cachedWithTTL = exports.cachedInvalidateWithTTL = exports.cachedFunction = exports.cached = exports.cacheRequestResult = exports.blocked = exports.bindTo = exports.bindAll = exports.bind = exports.awaitAllChildren = exports.asyncEffect = exports.async = exports.asVoid = exports.asSomeError = exports.asSome = exports.as = exports.ap = exports.annotateSpans = exports.annotateLogsScoped = exports.annotateLogs = exports.annotateCurrentSpan = exports.andThen = exports.allowInterrupt = exports.allWith = exports.allSuccesses = exports.all = exports.addFinalizer = exports.acquireUseRelease = exports.acquireReleaseInterruptible = exports.acquireRelease = exports.Tag = exports.Service = exports.EffectTypeId = exports.Do = void 0;
|
||
exports.repeatN = exports.repeat = exports.reduceWhile = exports.reduceRight = exports.reduceEffect = exports.reduce = exports.randomWith = exports.random = exports.raceWith = exports.raceFirst = exports.raceAll = exports.race = exports.provideServiceEffect = exports.provideService = exports.provide = exports.promise = exports.patchRuntimeFlags = exports.patchFiberRefs = exports.partition = exports.parallelFinalizers = exports.parallelErrors = exports.orElseSucceed = exports.orElseFail = exports.orElse = exports.orDieWith = exports.orDie = exports.optionFromOptional = exports.option = exports.once = exports.onInterrupt = exports.onExit = exports.onError = exports.none = exports.never = exports.negate = exports.metricLabels = exports.mergeAll = exports.merge = exports.matchEffect = exports.matchCauseEffect = exports.matchCause = exports.match = exports.mapInputContext = exports.mapErrorCause = exports.mapError = exports.mapBoth = exports.mapAccum = exports.map = exports.makeSpanScoped = exports.makeSpan = exports.makeSemaphore = exports.makeLatch = exports.loop = exports.logWithLevel = exports.logWarning = exports.logTrace = exports.logInfo = exports.logFatal = exports.logError = exports.logDebug = exports.logAnnotations = exports.log = exports.locallyWith = exports.locallyScopedWith = exports.locallyScoped = exports.locally = exports.linkSpans = exports.linkSpanCurrent = exports.liftPredicate = exports.let = exports.labelMetricsScoped = exports.labelMetrics = exports.iterate = exports.isSuccess = exports.isFailure = exports.isEffect = exports.intoDeferred = exports.interruptibleMask = exports.interruptible = exports.interruptWith = exports.interrupt = exports.inheritFiberRefs = exports.ignoreLogged = exports.ignore = exports.if = exports.head = exports.getRuntimeFlags = exports.getFiberRefs = exports.gen = exports.functionWithSpan = exports.fromNullable = exports.fromFiberEffect = exports.fromFiber = exports.forkWithErrorHandler = exports.forkScoped = exports.forkIn = exports.forkDaemon = exports.forkAll = exports.fork = exports.forever = void 0;
|
||
exports.withFiberRuntime = exports.withExecutionPlan = exports.withEarlyRelease = exports.withConsoleScoped = exports.withConsole = exports.withConfigProviderScoped = exports.withConfigProvider = exports.withConcurrency = exports.withClockScoped = exports.withClock = exports.whileLoop = exports.whenRef = exports.whenLogLevel = exports.whenFiberRef = exports.whenEffect = exports.when = exports.void = exports.validateWith = exports.validateFirst = exports.validateAll = exports.validate = exports.using = exports.useSpan = exports.updateService = exports.updateFiberRefs = exports.unsandbox = exports.unsafeMakeSemaphore = exports.unsafeMakeLatch = exports.unlessEffect = exports.unless = exports.uninterruptibleMask = exports.uninterruptible = exports.tryPromise = exports.tryMapPromise = exports.tryMap = exports.try = exports.transposeOption = exports.transposeMapOption = exports.transplant = exports.tracerWith = exports.tracer = exports.timeoutTo = exports.timeoutOption = exports.timeoutFailCause = exports.timeoutFail = exports.timeout = exports.timedWith = exports.timed = exports.tapErrorTag = exports.tapErrorCause = exports.tapError = exports.tapDefect = exports.tapBoth = exports.tap = exports.takeWhile = exports.takeUntil = exports.tagMetricsScoped = exports.tagMetrics = exports.sync = exports.suspend = exports.supervised = exports.summarized = exports.succeedSome = exports.succeedNone = exports.succeed = exports.step = exports.spanLinks = exports.spanAnnotations = exports.sleep = exports.setFiberRefs = exports.serviceOptional = exports.serviceOption = exports.serviceMembers = exports.serviceFunctions = exports.serviceFunctionEffect = exports.serviceFunction = exports.serviceConstants = exports.sequentialFinalizers = exports.scopedWith = exports.scoped = exports.scopeWith = exports.scope = exports.scheduleFrom = exports.scheduleForked = exports.schedule = exports.sandbox = exports.runtime = exports.runSyncExit = exports.runSync = exports.runRequestBlock = exports.runPromiseExit = exports.runPromise = exports.runFork = exports.runCallback = exports.retryOrElse = exports.retry = exports.request = exports.replicateEffect = exports.replicate = exports.repeatOrElse = void 0;
|
||
exports.zipWith = exports.zipRight = exports.zipLeft = exports.zip = exports.yieldNow = exports.withUnhandledErrorLogLevel = exports.withTracerTiming = exports.withTracerScoped = exports.withTracerEnabled = exports.withTracer = exports.withSpanScoped = exports.withSpan = exports.withSchedulingPriority = exports.withScheduler = exports.withRuntimeFlagsPatchScoped = exports.withRuntimeFlagsPatch = exports.withRequestCaching = exports.withRequestCache = exports.withRequestBatching = exports.withRandomScoped = exports.withRandom = exports.withParentSpan = exports.withMetric = exports.withMaxOpsBeforeYield = exports.withLogSpan = void 0;
|
||
var _Function = require("./Function.js");
|
||
var internalCause = _interopRequireWildcard(require("./internal/cause.js"));
|
||
var console_ = _interopRequireWildcard(require("./internal/console.js"));
|
||
var _context = require("./internal/context.js");
|
||
var effect = _interopRequireWildcard(require("./internal/core-effect.js"));
|
||
var core = _interopRequireWildcard(require("./internal/core.js"));
|
||
var defaultServices = _interopRequireWildcard(require("./internal/defaultServices.js"));
|
||
var circular = _interopRequireWildcard(require("./internal/effect/circular.js"));
|
||
var internalExecutionPlan = _interopRequireWildcard(require("./internal/executionPlan.js"));
|
||
var fiberRuntime = _interopRequireWildcard(require("./internal/fiberRuntime.js"));
|
||
var layer = _interopRequireWildcard(require("./internal/layer.js"));
|
||
var option_ = _interopRequireWildcard(require("./internal/option.js"));
|
||
var query = _interopRequireWildcard(require("./internal/query.js"));
|
||
var runtime_ = _interopRequireWildcard(require("./internal/runtime.js"));
|
||
var schedule_ = _interopRequireWildcard(require("./internal/schedule.js"));
|
||
var internalTracer = _interopRequireWildcard(require("./internal/tracer.js"));
|
||
var Request = _interopRequireWildcard(require("./Request.js"));
|
||
var Scheduler = _interopRequireWildcard(require("./Scheduler.js"));
|
||
var _Utils = require("./Utils.js");
|
||
function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Symbols
|
||
*/
|
||
const EffectTypeId = exports.EffectTypeId = core.EffectTypeId;
|
||
/**
|
||
* Checks if a given value is an `Effect` value.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function can be useful for checking the type of a value before
|
||
* attempting to operate on it as an `Effect` value. For example, you could use
|
||
* `Effect.isEffect` to check the type of a value before using it as an argument
|
||
* to a function that expects an `Effect` value.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Guards
|
||
*/
|
||
const isEffect = exports.isEffect = core.isEffect;
|
||
/**
|
||
* Returns an effect that caches its result for a specified `Duration`,
|
||
* known as "timeToLive" (TTL).
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function is used to cache the result of an effect for a specified amount
|
||
* of time. This means that the first time the effect is evaluated, its result
|
||
* is computed and stored.
|
||
*
|
||
* If the effect is evaluated again within the specified `timeToLive`, the
|
||
* cached result will be used, avoiding recomputation.
|
||
*
|
||
* After the specified duration has passed, the cache expires, and the effect
|
||
* will be recomputed upon the next evaluation.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you have an effect that involves costly operations or
|
||
* computations, and you want to avoid repeating them within a short time frame.
|
||
*
|
||
* It's ideal for scenarios where the result of an effect doesn't change
|
||
* frequently and can be reused for a specified duration.
|
||
*
|
||
* By caching the result, you can improve efficiency and reduce unnecessary
|
||
* computations, especially in performance-critical applications.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* 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
|
||
* ```
|
||
*
|
||
* @see {@link cached} for a similar function that caches the result
|
||
* indefinitely.
|
||
* @see {@link cachedInvalidateWithTTL} for a similar function that includes an
|
||
* additional effect for manually invalidating the cached value.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Caching
|
||
*/
|
||
const cachedWithTTL = exports.cachedWithTTL = circular.cached;
|
||
/**
|
||
* Caches an effect's result for a specified duration and allows manual
|
||
* invalidation before expiration.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function behaves similarly to {@link cachedWithTTL} by caching the
|
||
* result of an effect for a specified period of time. However, it introduces an
|
||
* additional feature: it provides an effect that allows you to manually
|
||
* invalidate the cached result before it naturally expires.
|
||
*
|
||
* This gives you more control over the cache, allowing you to refresh the
|
||
* result when needed, even if the original cache has not yet expired.
|
||
*
|
||
* Once the cache is invalidated, the next time the effect is evaluated, the
|
||
* result will be recomputed, and the cache will be refreshed.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you have an effect whose result needs to be cached for
|
||
* a certain period, but you also want the option to refresh the cache manually
|
||
* before the expiration time.
|
||
*
|
||
* This is useful when you need to ensure that the cached data remains valid for
|
||
* a certain period but still want to invalidate it if the underlying data
|
||
* changes or if you want to force a recomputation.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* 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
|
||
* ```
|
||
*
|
||
* @see {@link cached} for a similar function that caches the result
|
||
* indefinitely.
|
||
* @see {@link cachedWithTTL} for a similar function that caches the result for
|
||
* a specified duration but does not include an effect for manual invalidation.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Caching
|
||
*/
|
||
const cachedInvalidateWithTTL = exports.cachedInvalidateWithTTL = circular.cachedInvalidateWithTTL;
|
||
/**
|
||
* Returns an effect that lazily computes a result and caches it for subsequent
|
||
* evaluations.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function wraps an effect and ensures that its result is computed only
|
||
* once. Once the result is computed, it is cached, meaning that subsequent
|
||
* evaluations of the same effect will return the cached result without
|
||
* re-executing the logic.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you have an expensive or time-consuming operation that
|
||
* you want to avoid repeating. The first evaluation will compute the result,
|
||
* and all following evaluations will immediately return the cached value,
|
||
* improving performance and reducing unnecessary work.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* 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
|
||
* ```
|
||
*
|
||
* @see {@link cachedWithTTL} for a similar function that includes a
|
||
* time-to-live duration for the cached value.
|
||
* @see {@link cachedInvalidateWithTTL} for a similar function that includes an
|
||
* additional effect for manually invalidating the cached value.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Caching
|
||
*/
|
||
const cached = exports.cached = effect.memoize;
|
||
/**
|
||
* Returns a memoized version of a function with effects, reusing results for
|
||
* the same inputs.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function creates a memoized version of a given function that performs an
|
||
* effect. Memoization ensures that once a result is computed for a specific
|
||
* input, it is stored and reused for subsequent calls with the same input,
|
||
* reducing the need to recompute the result.
|
||
*
|
||
* The function can optionally take an `Equivalence` parameter to
|
||
* determine how inputs are compared for caching purposes.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you have a function that performs an effect and you
|
||
* want to avoid recomputing the result for the same input multiple times.
|
||
*
|
||
* It's ideal for functions that produce deterministic results based on their
|
||
* inputs, and you want to improve performance by caching the output.
|
||
*
|
||
* This is particularly useful in scenarios where the function involves
|
||
* expensive calculations or operations that should be avoided after the first
|
||
* execution with the same parameters.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* 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
|
||
*/
|
||
const cachedFunction = exports.cachedFunction = circular.cachedFunction;
|
||
/**
|
||
* Returns an effect that executes only once, regardless of how many times it's
|
||
* called.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function ensures that a specific effect is executed only a single time,
|
||
* no matter how many times it is invoked. The result of the effect will be
|
||
* cached, and subsequent calls to the effect will immediately return the cached
|
||
* result without re-executing the original logic.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you need to perform a task only once, regardless of
|
||
* how many times the effect is triggered. It's particularly useful when you
|
||
* have initialization tasks, logging, or other one-time actions that should not
|
||
* be repeated. This can help optimize performance and avoid redundant actions.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* 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:
|
||
* // task1
|
||
* // task1
|
||
* // task1
|
||
* // task2
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Caching
|
||
*/
|
||
const once = exports.once = effect.once;
|
||
/**
|
||
* Combines multiple effects into one, returning results based on the input
|
||
* structure.
|
||
*
|
||
* **Details**
|
||
*
|
||
* Use this function when you need to run multiple effects and combine their
|
||
* results into a single output. It supports tuples, iterables, structs, and
|
||
* records, making it flexible for different input types.
|
||
*
|
||
* For instance, if the input is a tuple:
|
||
*
|
||
* ```ts skip-type-checking
|
||
* // ┌─── a tuple of effects
|
||
* // ▼
|
||
* Effect.all([effect1, effect2, ...])
|
||
* ```
|
||
*
|
||
* the effects are executed sequentially, and the result is a new effect
|
||
* containing the results as a tuple. The results in the tuple match the order
|
||
* of the effects passed to `Effect.all`.
|
||
*
|
||
* **Concurrency**
|
||
*
|
||
* You can control the execution order (e.g., sequential vs. concurrent) using
|
||
* the `concurrency` option.
|
||
*
|
||
* **Short-Circuiting Behavior**
|
||
*
|
||
* This function stops execution on the first error it encounters, this is
|
||
* called "short-circuiting". If any effect in the collection fails, the
|
||
* remaining effects will not run, and the error will be propagated. To change
|
||
* this behavior, you can use the `mode` option, which allows all effects to run
|
||
* and collect results as `Either` or `Option`.
|
||
*
|
||
* **The `mode` option**
|
||
*
|
||
* The `{ mode: "either" }` option changes the behavior of `Effect.all` to
|
||
* ensure all effects run, even if some fail. Instead of stopping on the first
|
||
* failure, this mode collects both successes and failures, returning an array
|
||
* of `Either` instances where each result is either a `Right` (success) or a
|
||
* `Left` (failure).
|
||
*
|
||
* Similarly, the `{ mode: "validate" }` option uses `Option` to indicate
|
||
* success or failure. Each effect returns `None` for success and `Some` with
|
||
* the error for failure.
|
||
*
|
||
* **Example** (Combining Effects in Tuples)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const tupleOfEffects = [
|
||
* Effect.succeed(42).pipe(Effect.tap(Console.log)),
|
||
* Effect.succeed("Hello").pipe(Effect.tap(Console.log))
|
||
* ] as const
|
||
*
|
||
* // ┌─── Effect<[number, string], never, never>
|
||
* // ▼
|
||
* const resultsAsTuple = Effect.all(tupleOfEffects)
|
||
*
|
||
* Effect.runPromise(resultsAsTuple).then(console.log)
|
||
* // Output:
|
||
* // 42
|
||
* // Hello
|
||
* // [ 42, 'Hello' ]
|
||
* ```
|
||
*
|
||
* **Example** (Combining Effects in Iterables)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const iterableOfEffects: Iterable<Effect.Effect<number>> = [1, 2, 3].map(
|
||
* (n) => Effect.succeed(n).pipe(Effect.tap(Console.log))
|
||
* )
|
||
*
|
||
* // ┌─── Effect<number[], never, never>
|
||
* // ▼
|
||
* const resultsAsArray = Effect.all(iterableOfEffects)
|
||
*
|
||
* Effect.runPromise(resultsAsArray).then(console.log)
|
||
* // Output:
|
||
* // 1
|
||
* // 2
|
||
* // 3
|
||
* // [ 1, 2, 3 ]
|
||
* ```
|
||
*
|
||
* **Example** (Combining Effects in Structs)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const structOfEffects = {
|
||
* a: Effect.succeed(42).pipe(Effect.tap(Console.log)),
|
||
* b: Effect.succeed("Hello").pipe(Effect.tap(Console.log))
|
||
* }
|
||
*
|
||
* // ┌─── Effect<{ a: number; b: string; }, never, never>
|
||
* // ▼
|
||
* const resultsAsStruct = Effect.all(structOfEffects)
|
||
*
|
||
* Effect.runPromise(resultsAsStruct).then(console.log)
|
||
* // Output:
|
||
* // 42
|
||
* // Hello
|
||
* // { a: 42, b: 'Hello' }
|
||
* ```
|
||
*
|
||
* **Example** (Combining Effects in Records)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const recordOfEffects: Record<string, Effect.Effect<number>> = {
|
||
* key1: Effect.succeed(1).pipe(Effect.tap(Console.log)),
|
||
* key2: Effect.succeed(2).pipe(Effect.tap(Console.log))
|
||
* }
|
||
*
|
||
* // ┌─── Effect<{ [x: string]: number; }, never, never>
|
||
* // ▼
|
||
* const resultsAsRecord = Effect.all(recordOfEffects)
|
||
*
|
||
* Effect.runPromise(resultsAsRecord).then(console.log)
|
||
* // Output:
|
||
* // 1
|
||
* // 2
|
||
* // { key1: 1, key2: 2 }
|
||
* ```
|
||
*
|
||
* **Example** (Short-Circuiting Behavior)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const program = Effect.all([
|
||
* Effect.succeed("Task1").pipe(Effect.tap(Console.log)),
|
||
* Effect.fail("Task2: Oh no!").pipe(Effect.tap(Console.log)),
|
||
* // Won't execute due to earlier failure
|
||
* Effect.succeed("Task3").pipe(Effect.tap(Console.log))
|
||
* ])
|
||
*
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // Task1
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: { _id: 'Cause', _tag: 'Fail', failure: 'Task2: Oh no!' }
|
||
* // }
|
||
* ```
|
||
*
|
||
* **Example** (Collecting Results with `mode: "either"`)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const effects = [
|
||
* Effect.succeed("Task1").pipe(Effect.tap(Console.log)),
|
||
* Effect.fail("Task2: Oh no!").pipe(Effect.tap(Console.log)),
|
||
* Effect.succeed("Task3").pipe(Effect.tap(Console.log))
|
||
* ]
|
||
*
|
||
* const program = Effect.all(effects, { mode: "either" })
|
||
*
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // Task1
|
||
* // Task3
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Success',
|
||
* // value: [
|
||
* // { _id: 'Either', _tag: 'Right', right: 'Task1' },
|
||
* // { _id: 'Either', _tag: 'Left', left: 'Task2: Oh no!' },
|
||
* // { _id: 'Either', _tag: 'Right', right: 'Task3' }
|
||
* // ]
|
||
* // }
|
||
* ```
|
||
*
|
||
* **Example** (Collecting Results with `mode: "validate"`)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const effects = [
|
||
* Effect.succeed("Task1").pipe(Effect.tap(Console.log)),
|
||
* Effect.fail("Task2: Oh no!").pipe(Effect.tap(Console.log)),
|
||
* Effect.succeed("Task3").pipe(Effect.tap(Console.log))
|
||
* ]
|
||
*
|
||
* const program = Effect.all(effects, { mode: "validate" })
|
||
*
|
||
* Effect.runPromiseExit(program).then((result) => console.log("%o", result))
|
||
* // Output:
|
||
* // Task1
|
||
* // Task3
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: {
|
||
* // _id: 'Cause',
|
||
* // _tag: 'Fail',
|
||
* // failure: [
|
||
* // { _id: 'Option', _tag: 'None' },
|
||
* // { _id: 'Option', _tag: 'Some', value: 'Task2: Oh no!' },
|
||
* // { _id: 'Option', _tag: 'None' }
|
||
* // ]
|
||
* // }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @see {@link forEach} for iterating over elements and applying an effect.
|
||
* @see {@link allWith} for a data-last version of this function.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Collecting
|
||
*/
|
||
const all = exports.all = fiberRuntime.all;
|
||
/**
|
||
* A data-last version of {@link all}, designed for use in pipelines.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function enables you to combine multiple effects and customize execution
|
||
* options such as concurrency levels. This version is useful in functional
|
||
* pipelines where you first define your data and then apply operations to it.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, pipe } 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 program = pipe(
|
||
* [task1, task2],
|
||
* // Run both effects concurrently using the concurrent option
|
||
* Effect.allWith({ concurrency: 2 })
|
||
* )
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output:
|
||
* // timestamp=... level=INFO fiber=#3 message="task2 done"
|
||
* // timestamp=... level=INFO fiber=#2 message="task1 done"
|
||
* // [ 1, 'hello' ]
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Collecting
|
||
*/
|
||
const allWith = exports.allWith = fiberRuntime.allWith;
|
||
/**
|
||
* Evaluates and runs each effect in the iterable, collecting only the
|
||
* successful results while discarding failures.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function function processes an iterable of effects and runs each one. If
|
||
* an effect is successful, its result is collected; if it fails, the result is
|
||
* discarded. This ensures that only successful outcomes are kept.
|
||
*
|
||
* **Options**
|
||
*
|
||
* The function also allows you to customize how the effects are handled by
|
||
* specifying options such as concurrency, batching, and how finalizers behave.
|
||
* These options provide flexibility in running the effects concurrently or
|
||
* adjusting other execution details.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const tasks = [
|
||
* Effect.succeed(1),
|
||
* Effect.fail("Error 1"),
|
||
* Effect.succeed(2),
|
||
* Effect.fail("Error 2")
|
||
* ]
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* const successfulResults = yield* Effect.allSuccesses(tasks)
|
||
* console.log(successfulResults)
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output: [1, 2]
|
||
*
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Collecting
|
||
*/
|
||
const allSuccesses = exports.allSuccesses = fiberRuntime.allSuccesses;
|
||
/**
|
||
* Drops elements until the effectful predicate returns `true`.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function processes a collection of elements and uses an effectful
|
||
* predicate to determine when to stop dropping elements. It drops elements from
|
||
* the beginning of the collection until the predicate returns `true`.
|
||
*
|
||
* The predicate is a function that takes an element and its index in the
|
||
* collection and returns an effect that evaluates to a boolean.
|
||
*
|
||
* Once the predicate returns `true`, the remaining elements of the collection
|
||
* are returned.
|
||
*
|
||
* **Note**: The first element for which the predicate returns `true` is also
|
||
* dropped.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function allows you to conditionally skip over a part of the collection
|
||
* based on some criteria defined in the predicate.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const numbers = [1, 2, 3, 4, 5, 6]
|
||
* const predicate = (n: number, i: number) => Effect.succeed(n > 3)
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* const result = yield* Effect.dropUntil(numbers, predicate)
|
||
* console.log(result)
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output: [5, 6]
|
||
* ```
|
||
*
|
||
* @see {@link dropWhile} for a similar function that drops elements while the
|
||
* predicate returns `true`.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Collecting
|
||
*/
|
||
const dropUntil = exports.dropUntil = effect.dropUntil;
|
||
/**
|
||
* Drops elements as long as the predicate returns `true`.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function processes a collection of elements and uses a predicate to
|
||
* decide whether to drop an element.
|
||
*
|
||
* The predicate is a function that takes an element and its index, and it
|
||
* returns an effect that evaluates to a boolean.
|
||
*
|
||
* As long as the predicate returns `true`, elements will continue to be dropped
|
||
* from the collection.
|
||
*
|
||
* Once the predicate returns `false`, the remaining elements are kept.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function allows you to discard elements from the start of a collection
|
||
* based on a condition, and only keep the rest when the condition no longer
|
||
* holds.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const numbers = [1, 2, 3, 4, 5, 6]
|
||
* const predicate = (n: number, i: number) => Effect.succeed(n <= 3)
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* const result = yield* Effect.dropWhile(numbers, predicate)
|
||
* console.log(result)
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output: [4, 5, 6]
|
||
* ```
|
||
*
|
||
* @see {@link dropUntil} for a similar function that drops elements until the
|
||
* predicate returns `true`.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Collecting
|
||
*/
|
||
const dropWhile = exports.dropWhile = effect.dropWhile;
|
||
/**
|
||
* Takes elements from a collection until the effectful predicate returns
|
||
* `true`.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function processes a collection of elements and uses an effectful
|
||
* predicate to decide when to stop taking elements. The elements are taken from
|
||
* the beginning of the collection until the predicate returns `true`.
|
||
*
|
||
* The predicate is a function that takes an element and its index in the
|
||
* collection, and returns an effect that resolves to a boolean.
|
||
*
|
||
* Once the predicate returns `true`, the remaining elements of the collection
|
||
* are discarded, and the function stops taking more elements.
|
||
*
|
||
* **Note**: The first element for which the predicate returns `true` is also
|
||
* included in the result.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you want to conditionally take elements from a
|
||
* collection based on a dynamic condition. For example, you may want to collect
|
||
* numbers from a list until a certain threshold is reached, or gather items
|
||
* until a specific condition is met.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const numbers = [1, 2, 3, 4, 5, 6]
|
||
* const predicate = (n: number, i: number) => Effect.succeed(n > 3)
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* const result = yield* Effect.takeUntil(numbers, predicate)
|
||
* console.log(result)
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output: [ 1, 2, 3, 4 ]
|
||
* ```
|
||
*
|
||
* @see {@link takeWhile} for a similar function that takes elements while the
|
||
* predicate returns `true`.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Collecting
|
||
*/
|
||
const takeUntil = exports.takeUntil = effect.takeUntil;
|
||
/**
|
||
* Takes elements as long as the predicate returns `true`.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function processes a collection of elements and uses a predicate to
|
||
* decide whether to take an element.
|
||
*
|
||
* The predicate is a function that takes an element and its index, and it
|
||
* returns an effect that evaluates to a boolean.
|
||
*
|
||
* As long as the predicate returns `true`, elements will continue to be taken
|
||
* from the collection.
|
||
*
|
||
* Once the predicate returns `false`, the remaining elements are discarded.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const numbers = [1, 2, 3, 4, 5, 6]
|
||
* const predicate = (n: number, i: number) => Effect.succeed(n <= 3)
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* const result = yield* Effect.takeWhile(numbers, predicate)
|
||
* console.log(result)
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output: [1, 2, 3]
|
||
* ```
|
||
*
|
||
* @see {@link takeUntil} for a similar function that takes elements until the predicate returns `true`.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Collecting
|
||
*/
|
||
const takeWhile = exports.takeWhile = effect.takeWhile;
|
||
/**
|
||
* Determines whether all elements of the iterable satisfy the effectful
|
||
* predicate.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function checks whether every element in a given collection (an
|
||
* iterable) satisfies a condition defined by an effectful predicate.
|
||
*
|
||
* The predicate is a function that takes an element and its index, and it
|
||
* returns an effect that evaluates to a boolean.
|
||
*
|
||
* The function will process each element and return `true` if all elements
|
||
* satisfy the predicate; otherwise, it returns `false`.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function is useful when you need to verify that all items in a
|
||
* collection meet certain criteria, even when the evaluation of each item
|
||
* involves effects, such as asynchronous checks or complex computations.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const numbers = [2, 4, 6, 8]
|
||
* const predicate = (n: number, i: number) => Effect.succeed(n % 2 === 0)
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* const allEven = yield* Effect.every(numbers, predicate)
|
||
* console.log(allEven)
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output: true
|
||
* ```
|
||
*
|
||
* @see {@link exists} for a similar function that returns a boolean indicating
|
||
* whether **any** element satisfies the predicate.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Condition Checking
|
||
*/
|
||
const every = exports.every = effect.every;
|
||
/**
|
||
* Determines whether any element of the iterable satisfies the effectual
|
||
* predicate.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function checks whether any element in a given collection (an iterable)
|
||
* satisfies a condition defined by an effectful predicate.
|
||
*
|
||
* The predicate is a function that takes an element and its index, and it
|
||
* returns an effect that evaluates to a boolean.
|
||
*
|
||
* The function will process each element, and if any element satisfies the
|
||
* predicate (returns `true`), the function will immediately return `true`.
|
||
*
|
||
* If none of the elements satisfy the condition, it will return `false`.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function allows you to quickly check for a condition in a collection
|
||
* without having to manually iterate over it.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const numbers = [1, 2, 3, 4]
|
||
* const predicate = (n: number, i: number) => Effect.succeed(n > 2)
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* const hasLargeNumber = yield* Effect.exists(numbers, predicate)
|
||
* console.log(hasLargeNumber)
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output: true
|
||
* ```
|
||
*
|
||
* @see {@link every} for a similar function that checks if **all** elements
|
||
* satisfy the predicate.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Condition Checking
|
||
*/
|
||
const exists = exports.exists = fiberRuntime.exists;
|
||
/**
|
||
* Filters an iterable using the specified effectful predicate.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function filters a collection (an iterable) by applying an effectful
|
||
* predicate.
|
||
*
|
||
* The predicate is a function that takes an element and its index, and it
|
||
* returns an effect that evaluates to a boolean.
|
||
*
|
||
* The function processes each element in the collection and keeps only those
|
||
* that satisfy the condition defined by the predicate.
|
||
*
|
||
* **Options**
|
||
*
|
||
* You can also adjust the behavior with options such as concurrency, batching,
|
||
* or whether to negate the condition.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function allows you to selectively keep or remove elements based on a
|
||
* condition that may involve asynchronous or side-effect-causing operations.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const numbers = [1, 2, 3, 4, 5]
|
||
* const predicate = (n: number, i: number) => Effect.succeed(n % 2 === 0)
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* const result = yield* Effect.filter(numbers, predicate)
|
||
* console.log(result)
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output: [2, 4]
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Filtering
|
||
*/
|
||
const filter = exports.filter = fiberRuntime.filter;
|
||
/**
|
||
* Filters and maps elements sequentially in one operation.
|
||
*
|
||
* This function processes each element one by one. It applies a function that
|
||
* returns an `Option` to each element. If the function returns `Some`, the
|
||
* element is kept; if it returns `None`, the element is removed. The operation
|
||
* is done sequentially for each element.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect, Option } from "effect"
|
||
*
|
||
* const task = (n: number) =>
|
||
* Effect.succeed(n).pipe(
|
||
* Effect.delay(1000 - (n * 100)),
|
||
* Effect.tap(Console.log(`task${n} done`))
|
||
* )
|
||
*
|
||
* const program = Effect.filterMap(
|
||
* [task(1), task(2), task(3), task(4)],
|
||
* (n) => n % 2 === 0 ? Option.some(n) : Option.none()
|
||
* )
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output:
|
||
* // task1 done
|
||
* // task2 done
|
||
* // task3 done
|
||
* // task4 done
|
||
* // [ 2, 4 ]
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Filtering
|
||
*/
|
||
const filterMap = exports.filterMap = effect.filterMap;
|
||
/**
|
||
* Returns the first element that satisfies the effectful predicate.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function processes a collection of elements and applies an effectful
|
||
* predicate to each element.
|
||
*
|
||
* The predicate is a function that takes an element and its index in the
|
||
* collection, and it returns an effect that evaluates to a boolean.
|
||
*
|
||
* The function stops as soon as it finds the first element for which the
|
||
* predicate returns `true` and returns that element wrapped in an `Option`.
|
||
*
|
||
* If no element satisfies the predicate, the result will be `None`.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function allows you to efficiently find an element that meets a specific
|
||
* condition, even when the evaluation involves effects like asynchronous
|
||
* operations or side effects.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const numbers = [1, 2, 3, 4, 5]
|
||
* const predicate = (n: number, i: number) => Effect.succeed(n > 3)
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* const result = yield* Effect.findFirst(numbers, predicate)
|
||
* console.log(result)
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output: { _id: 'Option', _tag: 'Some', value: 4 }
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Collecting
|
||
*/
|
||
const findFirst = exports.findFirst = effect.findFirst;
|
||
/**
|
||
* Executes an effectful operation for each element in an `Iterable`.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function applies a provided operation to each element in the iterable,
|
||
* producing a new effect that returns an array of results.
|
||
*
|
||
* If any effect fails, the iteration stops immediately (short-circuiting), and
|
||
* the error is propagated.
|
||
*
|
||
* **Concurrency**
|
||
*
|
||
* The `concurrency` option controls how many operations are performed
|
||
* concurrently. By default, the operations are performed sequentially.
|
||
*
|
||
* **Discarding Results**
|
||
*
|
||
* If the `discard` option is set to `true`, the intermediate results are not
|
||
* collected, and the final result of the operation is `void`.
|
||
*
|
||
* **Example** (Applying Effects to Iterable Elements)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const result = Effect.forEach([1, 2, 3, 4, 5], (n, index) =>
|
||
* Console.log(`Currently at index ${index}`).pipe(Effect.as(n * 2))
|
||
* )
|
||
*
|
||
* Effect.runPromise(result).then(console.log)
|
||
* // Output:
|
||
* // Currently at index 0
|
||
* // Currently at index 1
|
||
* // Currently at index 2
|
||
* // Currently at index 3
|
||
* // Currently at index 4
|
||
* // [ 2, 4, 6, 8, 10 ]
|
||
* ```
|
||
*
|
||
* **Example** (Discarding Results)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* // Apply effects but discard the results
|
||
* const result = Effect.forEach(
|
||
* [1, 2, 3, 4, 5],
|
||
* (n, index) =>
|
||
* Console.log(`Currently at index ${index}`).pipe(Effect.as(n * 2)),
|
||
* { discard: true }
|
||
* )
|
||
*
|
||
* Effect.runPromise(result).then(console.log)
|
||
* // Output:
|
||
* // Currently at index 0
|
||
* // Currently at index 1
|
||
* // Currently at index 2
|
||
* // Currently at index 3
|
||
* // Currently at index 4
|
||
* // undefined
|
||
* ```
|
||
*
|
||
* @see {@link all} for combining multiple effects into one.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Looping
|
||
*/
|
||
const forEach = exports.forEach = fiberRuntime.forEach;
|
||
/**
|
||
* Returns the first element of the iterable if the collection is non-empty, or
|
||
* fails with the error `NoSuchElementException` if the collection is empty.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function is useful when you need to retrieve the first item from a
|
||
* collection and want to handle the case where the collection might be empty
|
||
* without causing an unhandled exception.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // Simulate an async operation
|
||
* const fetchNumbers = Effect.succeed([1, 2, 3]).pipe(Effect.delay("100 millis"))
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* const firstElement = yield* Effect.head(fetchNumbers)
|
||
* console.log(firstElement)
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output: 1
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Collecting
|
||
*/
|
||
const head = exports.head = effect.head;
|
||
/**
|
||
* Merges an `Iterable<Effect<A, E, R>>` to a single effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function takes an iterable of effects and combines them into a single
|
||
* effect. It does this by iterating over each effect in the collection and
|
||
* applying a function that accumulates results into a "zero" value, which
|
||
* starts with an initial value and is updated with each effect's success.
|
||
*
|
||
* The provided function `f` is called for each element in the iterable,
|
||
* allowing you to specify how to combine the results.
|
||
*
|
||
* **Options**
|
||
*
|
||
* The function also allows you to customize how the effects are handled by
|
||
* specifying options such as concurrency, batching, and how finalizers behave.
|
||
* These options provide flexibility in running the effects concurrently or
|
||
* adjusting other execution details.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const numbers = [Effect.succeed(1), Effect.succeed(2), Effect.succeed(3)]
|
||
* const add = (sum: number, value: number, i: number) => sum + value
|
||
* const zero = 0
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* const total = yield* Effect.mergeAll(numbers, zero, add)
|
||
* console.log(total)
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output: 6
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Collecting
|
||
*/
|
||
const mergeAll = exports.mergeAll = fiberRuntime.mergeAll;
|
||
/**
|
||
* Processes an iterable and applies an effectful function to each element,
|
||
* categorizing the results into successes and failures.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function processes each element in the provided iterable by applying an
|
||
* effectful function to it. The results are then categorized into two separate
|
||
* lists: one for failures and another for successes. This separation allows you
|
||
* to handle the two categories differently. Failures are collected in a list
|
||
* without interrupting the processing of the remaining elements, so the
|
||
* operation continues even if some elements fail. This is particularly useful
|
||
* when you need to handle both successful and failed results separately,
|
||
* without stopping the entire process on encountering a failure.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you want to process a collection of items and handle
|
||
* errors or failures without interrupting the processing of other items. It's
|
||
* useful when you need to distinguish between successful and failed results and
|
||
* process them separately, for example, when logging errors while continuing to
|
||
* work with valid data. The function ensures that failures are captured, while
|
||
* successes are processed normally.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // ┌─── Effect<[string[], number[]], never, never>
|
||
* // ▼
|
||
* const program = Effect.partition([0, 1, 2, 3, 4], (n) => {
|
||
* if (n % 2 === 0) {
|
||
* return Effect.succeed(n)
|
||
* } else {
|
||
* return Effect.fail(`${n} is not even`)
|
||
* }
|
||
* })
|
||
*
|
||
* Effect.runPromise(program).then(console.log, console.error)
|
||
* // Output:
|
||
* // [ [ '1 is not even', '3 is not even' ], [ 0, 2, 4 ] ]
|
||
* ```
|
||
*
|
||
* @see {@link validateAll} for a function that either collects all failures or all successes.
|
||
* @see {@link validateFirst} for a function that stops at the first success.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error Accumulation
|
||
*/
|
||
const partition = exports.partition = fiberRuntime.partition;
|
||
/**
|
||
* Reduces an `Iterable<A>` using an effectual function `f`, working
|
||
* sequentially from left to right.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function takes an iterable and applies a function `f` to each element in
|
||
* the iterable. The function works sequentially, starting with an initial value
|
||
* `zero` and then combining it with each element in the collection. The
|
||
* provided function `f` is called for each element in the iterable, allowing
|
||
* you to accumulate a result based on the current value and the element being
|
||
* processed.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* The function is often used for operations like summing a collection of
|
||
* numbers or combining results from multiple tasks. It ensures that operations
|
||
* are performed one after the other, maintaining the order of the elements.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* const processOrder = (id: number) =>
|
||
* Effect.succeed({ id, price: 100 * id })
|
||
* .pipe(Effect.tap(() => Console.log(`Order ${id} processed`)), Effect.delay(500 - (id * 100)))
|
||
*
|
||
* const program = Effect.reduce(
|
||
* [1, 2, 3, 4],
|
||
* 0,
|
||
* (acc, id, i) =>
|
||
* processOrder(id)
|
||
* .pipe(Effect.map((order) => acc + order.price))
|
||
* )
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output:
|
||
* // Order 1 processed
|
||
* // Order 2 processed
|
||
* // Order 3 processed
|
||
* // Order 4 processed
|
||
* // 1000
|
||
* ```
|
||
*
|
||
* @see {@link reduceWhile} for a similar function that stops the process based on a predicate.
|
||
* @see {@link reduceRight} for a similar function that works from right to left.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Collecting
|
||
*/
|
||
const reduce = exports.reduce = effect.reduce;
|
||
/**
|
||
* Reduces an `Iterable<A>` using an effectual function `body`, working
|
||
* sequentially from left to right, stopping the process early when the
|
||
* predicate `while` is not satisfied.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function processes a collection of elements, applying a function `body`
|
||
* to reduce them to a single value, starting from the first element. It checks
|
||
* the value of the accumulator against a predicate (`while`). If at any point
|
||
* the predicate returns `false`, the reduction stops, and the accumulated
|
||
* result is returned.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you need to reduce a collection of elements, but only
|
||
* continue the process as long as a certain condition holds true. For example,
|
||
* if you want to sum values in a list but stop as soon as the sum exceeds a
|
||
* certain threshold, you can use this function.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* const processOrder = (id: number) =>
|
||
* Effect.succeed({ id, price: 100 * id })
|
||
* .pipe(Effect.tap(() => Console.log(`Order ${id} processed`)), Effect.delay(500 - (id * 100)))
|
||
*
|
||
* const program = Effect.reduceWhile(
|
||
* [1, 2, 3, 4],
|
||
* 0,
|
||
* {
|
||
* body: (acc, id, i) =>
|
||
* processOrder(id)
|
||
* .pipe(Effect.map((order) => acc + order.price)),
|
||
* while: (acc) => acc < 500
|
||
* }
|
||
* )
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output:
|
||
* // Order 1 processed
|
||
* // Order 2 processed
|
||
* // Order 3 processed
|
||
* // 600
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Collecting
|
||
*/
|
||
const reduceWhile = exports.reduceWhile = effect.reduceWhile;
|
||
/**
|
||
* Reduces an `Iterable<A>` using an effectual function `f`, working
|
||
* sequentially from right to left.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function takes an iterable and applies a function `f` to each element in
|
||
* the iterable. The function works sequentially, starting with an initial value
|
||
* `zero` and then combining it with each element in the collection. The
|
||
* provided function `f` is called for each element in the iterable, allowing
|
||
* you to accumulate a result based on the current value and the element being
|
||
* processed.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* The function is often used for operations like summing a collection of
|
||
* numbers or combining results from multiple tasks. It ensures that operations
|
||
* are performed one after the other, maintaining the order of the elements.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* const processOrder = (id: number) =>
|
||
* Effect.succeed({ id, price: 100 * id })
|
||
* .pipe(Effect.tap(() => Console.log(`Order ${id} processed`)), Effect.delay(500 - (id * 100)))
|
||
*
|
||
* const program = Effect.reduceRight(
|
||
* [1, 2, 3, 4],
|
||
* 0,
|
||
* (id, acc, i) =>
|
||
* processOrder(id)
|
||
* .pipe(Effect.map((order) => acc + order.price))
|
||
* )
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output:
|
||
* // Order 4 processed
|
||
* // Order 3 processed
|
||
* // Order 2 processed
|
||
* // Order 1 processed
|
||
* // 1000
|
||
* ```
|
||
*
|
||
* @see {@link reduce} for a similar function that works from left to right.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Collecting
|
||
*/
|
||
const reduceRight = exports.reduceRight = effect.reduceRight;
|
||
/**
|
||
* Reduces an `Iterable<Effect<A, E, R>>` to a single effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function processes a collection of effects and combines them into one
|
||
* single effect. It starts with an initial effect (`zero`) and applies a
|
||
* function `f` to each element in the collection.
|
||
*
|
||
* **Options**
|
||
*
|
||
* The function also allows you to customize how the effects are handled by
|
||
* specifying options such as concurrency, batching, and how finalizers behave.
|
||
* These options provide flexibility in running the effects concurrently or
|
||
* adjusting other execution details.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* const processOrder = (id: number) =>
|
||
* Effect.succeed({ id, price: 100 * id })
|
||
* .pipe(Effect.tap(() => Console.log(`Order ${id} processed`)), Effect.delay(500 - (id * 100)))
|
||
*
|
||
* const program = Effect.reduceEffect(
|
||
* [processOrder(1), processOrder(2), processOrder(3), processOrder(4)],
|
||
* Effect.succeed(0),
|
||
* (acc, order, i) => acc + order.price
|
||
* )
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output:
|
||
* // Order 1 processed
|
||
* // Order 2 processed
|
||
* // Order 3 processed
|
||
* // Order 4 processed
|
||
* // 1000
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Collecting
|
||
*/
|
||
const reduceEffect = exports.reduceEffect = fiberRuntime.reduceEffect;
|
||
/**
|
||
* Replicates the given effect `n` times.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function takes an effect and replicates it a specified number of times
|
||
* (`n`). The result is an array of `n` effects, each of which is identical to
|
||
* the original effect.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* const task = Effect.succeed("Hello, World!").pipe(
|
||
* Effect.tap(Console.log)
|
||
* )
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* // Replicate the task 3 times
|
||
* const tasks = Effect.replicate(task, 3)
|
||
* for (const t of tasks) {
|
||
* // Run each task
|
||
* yield* t
|
||
* }
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output:
|
||
* // Hello, World!
|
||
* // Hello, World!
|
||
* // Hello, World!
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
*/
|
||
const replicate = exports.replicate = fiberRuntime.replicate;
|
||
/**
|
||
* Performs this effect the specified number of times and collects the results.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function repeats an effect multiple times and collects the results into
|
||
* an array. You specify how many times to execute the effect, and it runs that
|
||
* many times, either in sequence or concurrently depending on the provided
|
||
* options.
|
||
*
|
||
* **Options**
|
||
*
|
||
* If the `discard` option is set to `true`, the intermediate results are not
|
||
* collected, and the final result of the operation is `void`.
|
||
*
|
||
* The function also allows you to customize how the effects are handled by
|
||
* specifying options such as concurrency, batching, and how finalizers behave.
|
||
* These options provide flexibility in running the effects concurrently or
|
||
* adjusting other execution details.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* let counter = 0
|
||
*
|
||
* const task = Effect.sync(() => ++counter).pipe(
|
||
* Effect.tap(() => Console.log(`Task completed`))
|
||
* )
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* // Replicate the task 3 times and collect the results
|
||
* const results = yield* Effect.replicateEffect(task, 3)
|
||
* yield* Console.log(`Results: ${results.join(", ")}`)
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output:
|
||
* // Task completed
|
||
* // Task completed
|
||
* // Task completed
|
||
* // Results: 1, 2, 3
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Collecting
|
||
*/
|
||
const replicateEffect = exports.replicateEffect = fiberRuntime.replicateEffect;
|
||
/**
|
||
* Applies an effectful operation to each element in a collection while
|
||
* collecting both successes and failures.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to apply an effectful operation to every item in a
|
||
* collection.
|
||
*
|
||
* Unlike {@link forEach}, which would stop at the first error, this function
|
||
* continues processing all elements, accumulating both successes and failures.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you want to process every item in a collection, even
|
||
* if some items fail. This is particularly useful when you need to perform
|
||
* operations on all elements without halting due to an error.
|
||
*
|
||
* Keep in mind that if there are any failures, **all successes will be lost**,
|
||
* so this function is not suitable when you need to keep the successful results
|
||
* in case of errors.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* // ┌─── Effect<number[], [string, ...string[]], never>
|
||
* // ▼
|
||
* const program = Effect.validateAll([1, 2, 3, 4, 5], (n) => {
|
||
* if (n < 4) {
|
||
* return Console.log(`item ${n}`).pipe(Effect.as(n))
|
||
* } else {
|
||
* return Effect.fail(`${n} is not less that 4`)
|
||
* }
|
||
* })
|
||
*
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // item 1
|
||
* // item 2
|
||
* // item 3
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: {
|
||
* // _id: 'Cause',
|
||
* // _tag: 'Fail',
|
||
* // failure: [ '4 is not less that 4', '5 is not less that 4' ]
|
||
* // }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @see {@link forEach} for a similar function that stops at the first error.
|
||
* @see {@link partition} when you need to separate successes and failures
|
||
* instead of losing successes with errors.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error Accumulation
|
||
*/
|
||
const validateAll = exports.validateAll = fiberRuntime.validateAll;
|
||
/**
|
||
* This function is similar to {@link validateAll} but with a key difference: it
|
||
* returns the first successful result or all errors if none of the operations
|
||
* succeed.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function processes a collection of elements and applies an effectful
|
||
* operation to each. Unlike {@link validateAll}, which accumulates both
|
||
* successes and failures, `Effect.validateFirst` stops and returns the first
|
||
* success it encounters. If no success occurs, it returns all accumulated
|
||
* errors. This can be useful when you are interested in the first successful
|
||
* result and want to avoid processing further once a valid result is found.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* // ┌─── Effect<number, string[], never>
|
||
* // ▼
|
||
* const program = Effect.validateFirst([1, 2, 3, 4, 5], (n) => {
|
||
* if (n < 4) {
|
||
* return Effect.fail(`${n} is not less that 4`)
|
||
* } else {
|
||
* return Console.log(`item ${n}`).pipe(Effect.as(n))
|
||
* }
|
||
* })
|
||
*
|
||
* Effect.runPromise(program).then(console.log, console.error)
|
||
* // Output:
|
||
* // item 4
|
||
* // 4
|
||
* ```
|
||
*
|
||
* @see {@link validateAll} for a similar function that accumulates all results.
|
||
* @see {@link firstSuccessOf} for a similar function that processes multiple
|
||
* effects and returns the first successful one or the last error.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error Accumulation
|
||
*/
|
||
const validateFirst = exports.validateFirst = fiberRuntime.validateFirst;
|
||
/**
|
||
* Creates an `Effect` from a callback-based asynchronous function.
|
||
*
|
||
* **Details**
|
||
*
|
||
* The `resume` function:
|
||
* - Must be called exactly once. Any additional calls will be ignored.
|
||
* - Can return an optional `Effect` that will be run if the `Fiber` executing
|
||
* this `Effect` is interrupted. This can be useful in scenarios where you
|
||
* need to handle resource cleanup if the operation is interrupted.
|
||
* - Can receive an `AbortSignal` to handle interruption if needed.
|
||
*
|
||
* The `FiberId` of the fiber that may complete the async callback may also be
|
||
* specified using the `blockingOn` argument. This is called the "blocking
|
||
* fiber" because it suspends the fiber executing the `async` effect (i.e.
|
||
* semantically blocks the fiber from making progress). Specifying this fiber id
|
||
* in cases where it is known will improve diagnostics, but not affect the
|
||
* behavior of the returned effect.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use `Effect.async` when dealing with APIs that use callback-style instead of
|
||
* `async/await` or `Promise`.
|
||
*
|
||
* **Example** (Wrapping a Callback API)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
* import * as NodeFS from "node:fs"
|
||
*
|
||
* const readFile = (filename: string) =>
|
||
* Effect.async<Buffer, Error>((resume) => {
|
||
* NodeFS.readFile(filename, (error, data) => {
|
||
* if (error) {
|
||
* // Resume with a failed Effect if an error occurs
|
||
* resume(Effect.fail(error))
|
||
* } else {
|
||
* // Resume with a succeeded Effect if successful
|
||
* resume(Effect.succeed(data))
|
||
* }
|
||
* })
|
||
* })
|
||
*
|
||
* // ┌─── Effect<Buffer, Error, never>
|
||
* // ▼
|
||
* const program = readFile("example.txt")
|
||
* ```
|
||
*
|
||
* **Example** (Handling Interruption with Cleanup)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Fiber } from "effect"
|
||
* import * as NodeFS from "node:fs"
|
||
*
|
||
* // Simulates a long-running operation to write to a file
|
||
* const writeFileWithCleanup = (filename: string, data: string) =>
|
||
* Effect.async<void, Error>((resume) => {
|
||
* const writeStream = NodeFS.createWriteStream(filename)
|
||
*
|
||
* // Start writing data to the file
|
||
* writeStream.write(data)
|
||
*
|
||
* // When the stream is finished, resume with success
|
||
* writeStream.on("finish", () => resume(Effect.void))
|
||
*
|
||
* // In case of an error during writing, resume with failure
|
||
* writeStream.on("error", (err) => resume(Effect.fail(err)))
|
||
*
|
||
* // Handle interruption by returning a cleanup effect
|
||
* return Effect.sync(() => {
|
||
* console.log(`Cleaning up ${filename}`)
|
||
* NodeFS.unlinkSync(filename)
|
||
* })
|
||
* })
|
||
*
|
||
* const program = Effect.gen(function* () {
|
||
* const fiber = yield* Effect.fork(
|
||
* writeFileWithCleanup("example.txt", "Some long data...")
|
||
* )
|
||
* // Simulate interrupting the fiber after 1 second
|
||
* yield* Effect.sleep("1 second")
|
||
* yield* Fiber.interrupt(fiber) // This will trigger the cleanup
|
||
* })
|
||
*
|
||
* // Run the program
|
||
* Effect.runPromise(program)
|
||
* // Output:
|
||
* // Cleaning up example.txt
|
||
* ```
|
||
*
|
||
* **Example** (Handling Interruption with AbortSignal)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Fiber } from "effect"
|
||
*
|
||
* // A task that supports interruption using AbortSignal
|
||
* const interruptibleTask = Effect.async<void, Error>((resume, signal) => {
|
||
* // Handle interruption
|
||
* signal.addEventListener("abort", () => {
|
||
* console.log("Abort signal received")
|
||
* clearTimeout(timeoutId)
|
||
* })
|
||
*
|
||
* // Simulate a long-running task
|
||
* const timeoutId = setTimeout(() => {
|
||
* console.log("Operation completed")
|
||
* resume(Effect.void)
|
||
* }, 2000)
|
||
* })
|
||
*
|
||
* const program = Effect.gen(function* () {
|
||
* const fiber = yield* Effect.fork(interruptibleTask)
|
||
* // Simulate interrupting the fiber after 1 second
|
||
* yield* Effect.sleep("1 second")
|
||
* yield* Fiber.interrupt(fiber)
|
||
* })
|
||
*
|
||
* // Run the program
|
||
* Effect.runPromise(program)
|
||
* // Output:
|
||
* // Abort signal received
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const async = exports.async = core.async;
|
||
/**
|
||
* A variant of {@link async} where the registration function may return an `Effect`.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const asyncEffect = exports.asyncEffect = runtime_.asyncEffect;
|
||
/**
|
||
* Low level constructor that enables for custom stack tracing cutpoints.
|
||
*
|
||
* It is meant to be called with a bag of instructions that become available in
|
||
* the "this" of the effect.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const throwingFunction = () => { throw new Error() }
|
||
* const blowUp = Effect.custom(throwingFunction, function() {
|
||
* return Effect.succeed(this.effect_instruction_i0())
|
||
* })
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const custom = exports.custom = core.custom;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const withFiberRuntime = exports.withFiberRuntime = core.withFiberRuntime;
|
||
/**
|
||
* Creates an `Effect` that represents a recoverable error.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function to explicitly signal an error in an `Effect`. The error
|
||
* will keep propagating unless it is handled. You can handle the error with
|
||
* functions like {@link catchAll} or {@link catchTag}.
|
||
*
|
||
* **Example** (Creating a Failed Effect)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // ┌─── Effect<never, Error, never>
|
||
* // ▼
|
||
* const failure = Effect.fail(
|
||
* new Error("Operation failed due to network error")
|
||
* )
|
||
* ```
|
||
*
|
||
* @see {@link succeed} to create an effect that represents a successful value.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const fail = exports.fail = core.fail;
|
||
/**
|
||
* Creates an `Effect` that fails with the specified error, evaluated lazily.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const failSync = exports.failSync = core.failSync;
|
||
/**
|
||
* Creates an `Effect` that fails with the specified `Cause`.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const failCause = exports.failCause = core.failCause;
|
||
/**
|
||
* Creates an `Effect` that fails with the specified `Cause`, evaluated lazily.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const failCauseSync = exports.failCauseSync = core.failCauseSync;
|
||
/**
|
||
* Creates an effect that terminates a fiber with a specified error.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function is used to signal a defect, which represents a critical and
|
||
* unexpected error in the code. When invoked, it produces an effect that does
|
||
* not handle the error and instead terminates the fiber.
|
||
*
|
||
* The error channel of the resulting effect is of type `never`, indicating that
|
||
* it cannot recover from this failure.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when encountering unexpected conditions in your code that
|
||
* should not be handled as regular errors but instead represent unrecoverable
|
||
* defects.
|
||
*
|
||
* **Example** (Terminating on Division by Zero with a Specified Error)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const divide = (a: number, b: number) =>
|
||
* b === 0
|
||
* ? Effect.die(new Error("Cannot divide by zero"))
|
||
* : Effect.succeed(a / b)
|
||
*
|
||
* // ┌─── Effect<number, never, never>
|
||
* // ▼
|
||
* const program = divide(1, 0)
|
||
*
|
||
* Effect.runPromise(program).catch(console.error)
|
||
* // Output:
|
||
* // (FiberFailure) Error: Cannot divide by zero
|
||
* // ...stack trace...
|
||
* ```
|
||
*
|
||
* @see {@link dieSync} for a variant that throws a specified error, evaluated
|
||
* lazily.
|
||
* @see {@link dieMessage} for a variant that throws a `RuntimeException` with a
|
||
* message.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const die = exports.die = core.die;
|
||
/**
|
||
* Creates an effect that terminates a fiber with a `RuntimeException`
|
||
* containing the specified message.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function is used to signal a defect, representing a critical and
|
||
* unexpected error in the code. When invoked, it produces an effect that
|
||
* terminates the fiber with a `RuntimeException` carrying the given message.
|
||
*
|
||
* The resulting effect has an error channel of type `never`, indicating it does
|
||
* not handle or recover from the error.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you want to terminate a fiber due to an unrecoverable
|
||
* defect and include a clear explanation in the message.
|
||
*
|
||
* **Example** (Terminating on Division by Zero with a Specified Message)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const divide = (a: number, b: number) =>
|
||
* b === 0
|
||
* ? Effect.dieMessage("Cannot divide by zero")
|
||
* : Effect.succeed(a / b)
|
||
*
|
||
* // ┌─── Effect<number, never, never>
|
||
* // ▼
|
||
* const program = divide(1, 0)
|
||
*
|
||
* Effect.runPromise(program).catch(console.error)
|
||
* // Output:
|
||
* // (FiberFailure) RuntimeException: Cannot divide by zero
|
||
* // ...stack trace...
|
||
* ```
|
||
*
|
||
* @see {@link die} for a variant that throws a specified error.
|
||
* @see {@link dieSync} for a variant that throws a specified error, evaluated
|
||
* lazily.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const dieMessage = exports.dieMessage = core.dieMessage;
|
||
/**
|
||
* Creates an effect that dies with the specified error, evaluated lazily.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to create an effect that will terminate with a fatal error.
|
||
* The error is provided as a lazy argument, meaning it will only be evaluated when the effect runs.
|
||
*
|
||
* @see {@link die} if you don't need to evaluate the error lazily.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const dieSync = exports.dieSync = core.dieSync;
|
||
/**
|
||
* Provides a way to write effectful code using generator functions, simplifying
|
||
* control flow and error handling.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* `Effect.gen` allows you to write code that looks and behaves like synchronous
|
||
* code, but it can handle asynchronous tasks, errors, and complex control flow
|
||
* (like loops and conditions). It helps make asynchronous code more readable
|
||
* and easier to manage.
|
||
*
|
||
* The generator functions work similarly to `async/await` but with more
|
||
* explicit control over the execution of effects. You can `yield*` values from
|
||
* effects and return the final result at the end.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const addServiceCharge = (amount: number) => amount + 1
|
||
*
|
||
* const applyDiscount = (
|
||
* total: number,
|
||
* discountRate: number
|
||
* ): Effect.Effect<number, Error> =>
|
||
* discountRate === 0
|
||
* ? Effect.fail(new Error("Discount rate cannot be zero"))
|
||
* : Effect.succeed(total - (total * discountRate) / 100)
|
||
*
|
||
* const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))
|
||
*
|
||
* const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))
|
||
*
|
||
* export const program = Effect.gen(function* () {
|
||
* const transactionAmount = yield* fetchTransactionAmount
|
||
* const discountRate = yield* fetchDiscountRate
|
||
* const discountedAmount = yield* applyDiscount(
|
||
* transactionAmount,
|
||
* discountRate
|
||
* )
|
||
* const finalAmount = addServiceCharge(discountedAmount)
|
||
* return `Final amount to charge: ${finalAmount}`
|
||
* })
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const gen = exports.gen = core.gen;
|
||
/**
|
||
* An effect that that runs indefinitely and never produces any result. The
|
||
* moral equivalent of `while(true) {}`, only without the wasted CPU cycles.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* It could be useful for long-running background tasks or to simulate waiting
|
||
* behavior without actually consuming resources. This effect is ideal for cases
|
||
* where you want to keep the program alive or in a certain state without
|
||
* performing any active work.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const never = exports.never = core.never;
|
||
/**
|
||
* Ensures the `Option` is `None`, returning `void`. Otherwise, raises a
|
||
* `NoSuchElementException`.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function checks if the provided `Option` is `None`. If it is, it returns
|
||
* an effect that produces no result (i.e., `void`). If the `Option` is not
|
||
* `None` (i.e., it contains a value), the function will raise a
|
||
* `NoSuchElementException` error.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful when you want to ensure that a certain value is absent (i.e.,
|
||
* `None`) before continuing execution, and to handle cases where the value is
|
||
* unexpectedly present.
|
||
*
|
||
* @since 2.0.0
|
||
*/
|
||
const none = exports.none = effect.none;
|
||
/**
|
||
* Creates an `Effect` that represents an asynchronous computation guaranteed to
|
||
* succeed.
|
||
*
|
||
* **Details**
|
||
*
|
||
* The provided function (`thunk`) returns a `Promise` that should never reject; if it does, the error
|
||
* will be treated as a "defect".
|
||
*
|
||
* This defect is not a standard error but indicates a flaw in the logic that
|
||
* was expected to be error-free. You can think of it similar to an unexpected
|
||
* crash in the program, which can be further managed or logged using tools like
|
||
* {@link catchAllDefect}.
|
||
*
|
||
* **Interruptions**
|
||
*
|
||
* An optional `AbortSignal` can be provided to allow for interruption of the
|
||
* wrapped `Promise` API.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you are sure the operation will not reject.
|
||
*
|
||
* **Example** (Delayed Message)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const delay = (message: string) =>
|
||
* Effect.promise<string>(
|
||
* () =>
|
||
* new Promise((resolve) => {
|
||
* setTimeout(() => {
|
||
* resolve(message)
|
||
* }, 2000)
|
||
* })
|
||
* )
|
||
*
|
||
* // ┌─── Effect<string, never, never>
|
||
* // ▼
|
||
* const program = delay("Async operation completed successfully!")
|
||
* ```
|
||
*
|
||
* @see {@link tryPromise} for a version that can handle failures.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const promise = exports.promise = effect.promise;
|
||
/**
|
||
* Creates an `Effect` that always succeeds with a given value.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you need an effect that completes successfully with a
|
||
* specific value without any errors or external dependencies.
|
||
*
|
||
* **Example** (Creating a Successful Effect)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // Creating an effect that represents a successful scenario
|
||
* //
|
||
* // ┌─── Effect<number, never, never>
|
||
* // ▼
|
||
* const success = Effect.succeed(42)
|
||
* ```
|
||
*
|
||
* @see {@link fail} to create an effect that represents a failure.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const succeed = exports.succeed = core.succeed;
|
||
/**
|
||
* Returns an effect which succeeds with `None`.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you need to represent the absence of a value in your
|
||
* code, especially when working with optional data. This can be helpful when
|
||
* you want to indicate that no result is available without throwing an error or
|
||
* performing additional logic.
|
||
*
|
||
* @see {@link succeedSome} to create an effect that succeeds with a `Some` value.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const succeedNone = exports.succeedNone = effect.succeedNone;
|
||
/**
|
||
* Returns an effect which succeeds with the value wrapped in a `Some`.
|
||
*
|
||
* @see {@link succeedNone} for a similar function that returns `None` when the value is absent.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const succeedSome = exports.succeedSome = effect.succeedSome;
|
||
/**
|
||
* Delays the creation of an `Effect` until it is actually needed.
|
||
*
|
||
* **Details**
|
||
*
|
||
* The `Effect.suspend` function takes a thunk that represents the effect and
|
||
* wraps it in a suspended effect. This means the effect will not be created
|
||
* until it is explicitly needed, which is helpful in various scenarios:
|
||
* - **Lazy Evaluation**: Helps optimize performance by deferring computations,
|
||
* especially when the effect might not be needed, or when its computation is
|
||
* expensive. This also ensures that any side effects or scoped captures are
|
||
* re-executed on each invocation.
|
||
* - **Handling Circular Dependencies**: Useful in managing circular
|
||
* dependencies, such as recursive functions that need to avoid eager
|
||
* evaluation to prevent stack overflow.
|
||
* - **Unifying Return Types**: Can help TypeScript unify return types in
|
||
* situations where multiple branches of logic return different effects,
|
||
* simplifying type inference.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you need to defer the evaluation of an effect until it
|
||
* is required. This is particularly useful for optimizing expensive
|
||
* computations, managing circular dependencies, or resolving type inference
|
||
* issues.
|
||
*
|
||
* **Example** (Lazy Evaluation with Side Effects)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* let i = 0
|
||
*
|
||
* const bad = Effect.succeed(i++)
|
||
*
|
||
* const good = Effect.suspend(() => Effect.succeed(i++))
|
||
*
|
||
* console.log(Effect.runSync(bad)) // Output: 0
|
||
* console.log(Effect.runSync(bad)) // Output: 0
|
||
*
|
||
* console.log(Effect.runSync(good)) // Output: 1
|
||
* console.log(Effect.runSync(good)) // Output: 2
|
||
* ```
|
||
*
|
||
* **Example** (Recursive Fibonacci)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const blowsUp = (n: number): Effect.Effect<number> =>
|
||
* n < 2
|
||
* ? Effect.succeed(1)
|
||
* : Effect.zipWith(blowsUp(n - 1), blowsUp(n - 2), (a, b) => a + b)
|
||
*
|
||
* console.log(Effect.runSync(blowsUp(32)))
|
||
* // crash: JavaScript heap out of memory
|
||
*
|
||
* const allGood = (n: number): Effect.Effect<number> =>
|
||
* n < 2
|
||
* ? Effect.succeed(1)
|
||
* : Effect.zipWith(
|
||
* Effect.suspend(() => allGood(n - 1)),
|
||
* Effect.suspend(() => allGood(n - 2)),
|
||
* (a, b) => a + b
|
||
* )
|
||
*
|
||
* console.log(Effect.runSync(allGood(32)))
|
||
* // Output: 3524578
|
||
* ```
|
||
*
|
||
* **Example** (Using Effect.suspend to Help TypeScript Infer Types)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // Without suspend, TypeScript may struggle with type inference.
|
||
* // Inferred type:
|
||
* // (a: number, b: number) =>
|
||
* // Effect<never, Error, never> | Effect<number, never, never>
|
||
* const withoutSuspend = (a: number, b: number) =>
|
||
* b === 0
|
||
* ? Effect.fail(new Error("Cannot divide by zero"))
|
||
* : Effect.succeed(a / b)
|
||
*
|
||
* // Using suspend to unify return types.
|
||
* // Inferred type:
|
||
* // (a: number, b: number) => Effect<number, Error, never>
|
||
* const withSuspend = (a: number, b: number) =>
|
||
* Effect.suspend(() =>
|
||
* b === 0
|
||
* ? Effect.fail(new Error("Cannot divide by zero"))
|
||
* : Effect.succeed(a / b)
|
||
* )
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const suspend = exports.suspend = core.suspend;
|
||
/**
|
||
* Creates an `Effect` that represents a synchronous side-effectful computation.
|
||
*
|
||
* **Details**
|
||
*
|
||
* The provided function (`thunk`) must not throw errors; if it does, the error
|
||
* will be treated as a "defect".
|
||
*
|
||
* This defect is not a standard error but indicates a flaw in the logic that
|
||
* was expected to be error-free. You can think of it similar to an unexpected
|
||
* crash in the program, which can be further managed or logged using tools like
|
||
* {@link catchAllDefect}.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you are sure the operation will not fail.
|
||
*
|
||
* **Example** (Logging a Message)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const log = (message: string) =>
|
||
* Effect.sync(() => {
|
||
* console.log(message) // side effect
|
||
* })
|
||
*
|
||
* // ┌─── Effect<void, never, never>
|
||
* // ▼
|
||
* const program = log("Hello, World!")
|
||
* ```
|
||
*
|
||
* @see {@link try_ | try} for a version that can handle failures.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const sync = exports.sync = core.sync;
|
||
const _void = exports.void = core.void;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const yieldNow = exports.yieldNow = core.yieldNow;
|
||
const _catch = exports.catch = effect._catch;
|
||
/**
|
||
* Handles all errors in an effect by providing a fallback effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function catches any errors that may occur during the execution of an
|
||
* effect and allows you to handle them by specifying a fallback effect. This
|
||
* ensures that the program continues without failing by recovering from errors
|
||
* using the provided fallback logic.
|
||
*
|
||
* **Note**: This function only handles recoverable errors. It will not recover
|
||
* from unrecoverable defects.
|
||
*
|
||
* **Example** (Providing Recovery Logic for Recoverable Errors)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Random } from "effect"
|
||
*
|
||
* class HttpError {
|
||
* readonly _tag = "HttpError"
|
||
* }
|
||
*
|
||
* class ValidationError {
|
||
* readonly _tag = "ValidationError"
|
||
* }
|
||
*
|
||
* // ┌─── Effect<string, HttpError | ValidationError, never>
|
||
* // ▼
|
||
* const program = Effect.gen(function* () {
|
||
* const n1 = yield* Random.next
|
||
* const n2 = yield* Random.next
|
||
* if (n1 < 0.5) {
|
||
* yield* Effect.fail(new HttpError())
|
||
* }
|
||
* if (n2 < 0.5) {
|
||
* yield* Effect.fail(new ValidationError())
|
||
* }
|
||
* return "some result"
|
||
* })
|
||
*
|
||
* // ┌─── Effect<string, never, never>
|
||
* // ▼
|
||
* const recovered = program.pipe(
|
||
* Effect.catchAll((error) =>
|
||
* Effect.succeed(`Recovering from ${error._tag}`)
|
||
* )
|
||
* )
|
||
* ```
|
||
*
|
||
* @see {@link catchAllCause} for a version that can recover from both
|
||
* recoverable and unrecoverable errors.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const catchAll = exports.catchAll = core.catchAll;
|
||
/**
|
||
* Handles both recoverable and unrecoverable errors by providing a recovery
|
||
* effect.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* The `catchAllCause` function allows you to handle all errors, including
|
||
* unrecoverable defects, by providing a recovery effect. The recovery logic is
|
||
* based on the `Cause` of the error, which provides detailed information about
|
||
* the failure.
|
||
*
|
||
* **When to Recover from Defects**
|
||
*
|
||
* Defects are unexpected errors that typically shouldn't be recovered from, as
|
||
* they often indicate serious issues. However, in some cases, such as
|
||
* dynamically loaded plugins, controlled recovery might be needed.
|
||
*
|
||
* **Example** (Recovering from All Errors)
|
||
*
|
||
* ```ts
|
||
* import { Cause, Effect } from "effect"
|
||
*
|
||
* // Define an effect that may fail with a recoverable or unrecoverable error
|
||
* const program = Effect.fail("Something went wrong!")
|
||
*
|
||
* // Recover from all errors by examining the cause
|
||
* const recovered = program.pipe(
|
||
* Effect.catchAllCause((cause) =>
|
||
* Cause.isFailure(cause)
|
||
* ? Effect.succeed("Recovered from a regular error")
|
||
* : Effect.succeed("Recovered from a defect")
|
||
* )
|
||
* )
|
||
*
|
||
* Effect.runPromise(recovered).then(console.log)
|
||
* // Output: "Recovered from a regular error"
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const catchAllCause = exports.catchAllCause = core.catchAllCause;
|
||
/**
|
||
* Recovers from all defects using a provided recovery function.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* There is no sensible way to recover from defects. This method should be used
|
||
* only at the boundary between Effect and an external system, to transmit
|
||
* information on a defect for diagnostic or explanatory purposes.
|
||
*
|
||
* **Details**
|
||
*
|
||
* `catchAllDefect` allows you to handle defects, which are unexpected errors
|
||
* that usually cause the program to terminate. This function lets you recover
|
||
* from these defects by providing a function that handles the error. However,
|
||
* it does not handle expected errors (like those from {@link fail}) or
|
||
* execution interruptions (like those from {@link interrupt}).
|
||
*
|
||
* **When to Recover from Defects**
|
||
*
|
||
* Defects are unexpected errors that typically shouldn't be recovered from, as
|
||
* they often indicate serious issues. However, in some cases, such as
|
||
* dynamically loaded plugins, controlled recovery might be needed.
|
||
*
|
||
* **Example** (Handling All Defects)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Cause, Console } from "effect"
|
||
*
|
||
* // Simulating a runtime error
|
||
* const task = Effect.dieMessage("Boom!")
|
||
*
|
||
* const program = Effect.catchAllDefect(task, (defect) => {
|
||
* if (Cause.isRuntimeException(defect)) {
|
||
* return Console.log(
|
||
* `RuntimeException defect caught: ${defect.message}`
|
||
* )
|
||
* }
|
||
* return Console.log("Unknown defect caught.")
|
||
* })
|
||
*
|
||
* // We get an Exit.Success because we caught all defects
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // RuntimeException defect caught: Boom!
|
||
* // {
|
||
* // _id: "Exit",
|
||
* // _tag: "Success",
|
||
* // value: undefined
|
||
* // }
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const catchAllDefect = exports.catchAllDefect = effect.catchAllDefect;
|
||
/**
|
||
* Recovers from specific errors based on a predicate.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* `catchIf` works similarly to {@link catchSome}, but it allows you to
|
||
* recover from errors by providing a predicate function. If the predicate
|
||
* matches the error, the recovery effect is applied. This function doesn't
|
||
* alter the error type, so the resulting effect still carries the original
|
||
* error type unless a user-defined type guard is used to narrow the type.
|
||
*
|
||
* **Example** (Catching Specific Errors with a Predicate)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Random } from "effect"
|
||
*
|
||
* class HttpError {
|
||
* readonly _tag = "HttpError"
|
||
* }
|
||
*
|
||
* class ValidationError {
|
||
* readonly _tag = "ValidationError"
|
||
* }
|
||
*
|
||
* // ┌─── Effect<string, HttpError | ValidationError, never>
|
||
* // ▼
|
||
* const program = Effect.gen(function* () {
|
||
* const n1 = yield* Random.next
|
||
* const n2 = yield* Random.next
|
||
* if (n1 < 0.5) {
|
||
* yield* Effect.fail(new HttpError())
|
||
* }
|
||
* if (n2 < 0.5) {
|
||
* yield* Effect.fail(new ValidationError())
|
||
* }
|
||
* return "some result"
|
||
* })
|
||
*
|
||
* // ┌─── Effect<string, ValidationError, never>
|
||
* // ▼
|
||
* const recovered = program.pipe(
|
||
* Effect.catchIf(
|
||
* // Only handle HttpError errors
|
||
* (error) => error._tag === "HttpError",
|
||
* () => Effect.succeed("Recovering from HttpError")
|
||
* )
|
||
* )
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const catchIf = exports.catchIf = core.catchIf;
|
||
/**
|
||
* Catches and recovers from specific types of errors, allowing you to attempt
|
||
* recovery only for certain errors.
|
||
*
|
||
* **Details**
|
||
*
|
||
* `catchSome` lets you selectively catch and handle errors of certain
|
||
* types by providing a recovery effect for specific errors. If the error
|
||
* matches a condition, recovery is attempted; if not, it doesn't affect the
|
||
* program. This function doesn't alter the error type, meaning the error type
|
||
* remains the same as in the original effect.
|
||
*
|
||
* **Example** (Handling Specific Errors with Effect.catchSome)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Random, Option } from "effect"
|
||
*
|
||
* class HttpError {
|
||
* readonly _tag = "HttpError"
|
||
* }
|
||
*
|
||
* class ValidationError {
|
||
* readonly _tag = "ValidationError"
|
||
* }
|
||
*
|
||
* // ┌─── Effect<string, HttpError | ValidationError, never>
|
||
* // ▼
|
||
* const program = Effect.gen(function* () {
|
||
* const n1 = yield* Random.next
|
||
* const n2 = yield* Random.next
|
||
* if (n1 < 0.5) {
|
||
* yield* Effect.fail(new HttpError())
|
||
* }
|
||
* if (n2 < 0.5) {
|
||
* yield* Effect.fail(new ValidationError())
|
||
* }
|
||
* return "some result"
|
||
* })
|
||
*
|
||
* // ┌─── Effect<string, HttpError | ValidationError, never>
|
||
* // ▼
|
||
* const recovered = program.pipe(
|
||
* Effect.catchSome((error) => {
|
||
* // Only handle HttpError errors
|
||
* if (error._tag === "HttpError") {
|
||
* return Option.some(Effect.succeed("Recovering from HttpError"))
|
||
* } else {
|
||
* return Option.none()
|
||
* }
|
||
* })
|
||
* )
|
||
* ```
|
||
*
|
||
* @see {@link catchIf} for a version that allows you to recover from errors based on a predicate.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const catchSome = exports.catchSome = core.catchSome;
|
||
/**
|
||
* Recovers from specific causes using a provided partial function.
|
||
*
|
||
* @see {@link catchSome} for a version that allows you to recover from errors.
|
||
* @see {@link catchSomeDefect} for a version that allows you to recover from defects.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const catchSomeCause = exports.catchSomeCause = effect.catchSomeCause;
|
||
/**
|
||
* Recovers from specific defects using a provided partial function.
|
||
*
|
||
* **Details**
|
||
*
|
||
* `catchSomeDefect` allows you to handle specific defects, which are
|
||
* unexpected errors that can cause the program to stop. It uses a partial
|
||
* function to catch only certain defects and ignores others. The function does
|
||
* not handle expected errors (such as those caused by {@link fail}) or
|
||
* interruptions in execution (like those caused by {@link interrupt}).
|
||
*
|
||
* This function provides a way to handle certain types of defects while
|
||
* allowing others to propagate and cause failure in the program.
|
||
*
|
||
* **Note**: There is no sensible way to recover from defects. This method
|
||
* should be used only at the boundary between Effect and an external system, to
|
||
* transmit information on a defect for diagnostic or explanatory purposes.
|
||
*
|
||
* **How the Partial Function Works**
|
||
*
|
||
* The function provided to `catchSomeDefect` acts as a filter and a handler for defects:
|
||
* - It receives the defect as an input.
|
||
* - If the defect matches a specific condition (e.g., a certain error type), the function returns
|
||
* an `Option.some` containing the recovery logic.
|
||
* - If the defect does not match, the function returns `Option.none`, allowing the defect to propagate.
|
||
*
|
||
* **Example** (Handling Specific Defects)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Cause, Option, Console } from "effect"
|
||
*
|
||
* // Simulating a runtime error
|
||
* const task = Effect.dieMessage("Boom!")
|
||
*
|
||
* const program = Effect.catchSomeDefect(task, (defect) => {
|
||
* if (Cause.isIllegalArgumentException(defect)) {
|
||
* return Option.some(
|
||
* Console.log(
|
||
* `Caught an IllegalArgumentException defect: ${defect.message}`
|
||
* )
|
||
* )
|
||
* }
|
||
* return Option.none()
|
||
* })
|
||
*
|
||
* // Since we are only catching IllegalArgumentException
|
||
* // we will get an Exit.Failure because we simulated a runtime error.
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: {
|
||
* // _id: 'Cause',
|
||
* // _tag: 'Die',
|
||
* // defect: { _tag: 'RuntimeException' }
|
||
* // }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const catchSomeDefect = exports.catchSomeDefect = effect.catchSomeDefect;
|
||
/**
|
||
* Catches and handles specific errors by their `_tag` field, which is used as a
|
||
* discriminator.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* `catchTag` is useful when your errors are tagged with a readonly `_tag` field
|
||
* that identifies the error type. You can use this function to handle specific
|
||
* error types by matching the `_tag` value. This allows for precise error
|
||
* handling, ensuring that only specific errors are caught and handled.
|
||
*
|
||
* The error type must have a readonly `_tag` field to use `catchTag`. This
|
||
* field is used to identify and match errors.
|
||
*
|
||
* **Example** (Handling Errors by Tag)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Random } from "effect"
|
||
*
|
||
* class HttpError {
|
||
* readonly _tag = "HttpError"
|
||
* }
|
||
*
|
||
* class ValidationError {
|
||
* readonly _tag = "ValidationError"
|
||
* }
|
||
*
|
||
* // ┌─── Effect<string, HttpError | ValidationError, never>
|
||
* // ▼
|
||
* const program = Effect.gen(function* () {
|
||
* const n1 = yield* Random.next
|
||
* const n2 = yield* Random.next
|
||
* if (n1 < 0.5) {
|
||
* yield* Effect.fail(new HttpError())
|
||
* }
|
||
* if (n2 < 0.5) {
|
||
* yield* Effect.fail(new ValidationError())
|
||
* }
|
||
* return "some result"
|
||
* })
|
||
*
|
||
* // ┌─── Effect<string, ValidationError, never>
|
||
* // ▼
|
||
* const recovered = program.pipe(
|
||
* // Only handle HttpError errors
|
||
* Effect.catchTag("HttpError", (_HttpError) =>
|
||
* Effect.succeed("Recovering from HttpError")
|
||
* )
|
||
* )
|
||
* ```
|
||
*
|
||
* @see {@link catchTags} for a version that allows you to handle multiple error
|
||
* types at once.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const catchTag = exports.catchTag = effect.catchTag;
|
||
/**
|
||
* Handles multiple errors in a single block of code using their `_tag` field.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* `catchTags` is a convenient way to handle multiple error types at
|
||
* once. Instead of using {@link catchTag} multiple times, you can pass an
|
||
* object where each key is an error type's `_tag`, and the value is the handler
|
||
* for that specific error. This allows you to catch and recover from multiple
|
||
* error types in a single call.
|
||
*
|
||
* The error type must have a readonly `_tag` field to use `catchTag`. This
|
||
* field is used to identify and match errors.
|
||
*
|
||
* **Example** (Handling Multiple Tagged Error Types at Once)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Random } from "effect"
|
||
*
|
||
* class HttpError {
|
||
* readonly _tag = "HttpError"
|
||
* }
|
||
*
|
||
* class ValidationError {
|
||
* readonly _tag = "ValidationError"
|
||
* }
|
||
*
|
||
* // ┌─── Effect<string, HttpError | ValidationError, never>
|
||
* // ▼
|
||
* const program = Effect.gen(function* () {
|
||
* const n1 = yield* Random.next
|
||
* const n2 = yield* Random.next
|
||
* if (n1 < 0.5) {
|
||
* yield* Effect.fail(new HttpError())
|
||
* }
|
||
* if (n2 < 0.5) {
|
||
* yield* Effect.fail(new ValidationError())
|
||
* }
|
||
* return "some result"
|
||
* })
|
||
*
|
||
* // ┌─── Effect<string, never, never>
|
||
* // ▼
|
||
* const recovered = program.pipe(
|
||
* Effect.catchTags({
|
||
* HttpError: (_HttpError) =>
|
||
* Effect.succeed(`Recovering from HttpError`),
|
||
* ValidationError: (_ValidationError) =>
|
||
* Effect.succeed(`Recovering from ValidationError`)
|
||
* })
|
||
* )
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const catchTags = exports.catchTags = effect.catchTags;
|
||
/**
|
||
* Retrieves the cause of a failure in an effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to expose the detailed cause of an effect, which
|
||
* includes a more precise representation of failures, such as error messages
|
||
* and defects.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function is helpful when you need to inspect the cause of a failure in
|
||
* an effect, giving you more information than just the error message. It can be
|
||
* used to log, handle, or analyze failures in more detail, including
|
||
* distinguishing between different types of defects (e.g., runtime exceptions,
|
||
* interruptions, etc.).
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* // ┌─── Effect<number, string, never>
|
||
* // ▼
|
||
* const program = Effect.fail("Oh uh!").pipe(Effect.as(2))
|
||
*
|
||
* // ┌─── Effect<void, never, never>
|
||
* // ▼
|
||
* const recovered = Effect.gen(function* () {
|
||
* const cause = yield* Effect.cause(program)
|
||
* yield* Console.log(cause)
|
||
* })
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const cause = exports.cause = effect.cause;
|
||
/**
|
||
* Runs an effect repeatedly until it succeeds, ignoring errors.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function takes an effect and runs it repeatedly until the effect
|
||
* successfully completes. If the effect fails, it will ignore the error and
|
||
* retry the operation. This is useful when you need to perform a task that may
|
||
* fail occasionally, but you want to keep trying until it eventually succeeds.
|
||
* It works by repeatedly executing the effect until it no longer throws an
|
||
* error.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you want to retry an operation multiple times until it
|
||
* succeeds. It is helpful in cases where the operation may fail temporarily
|
||
* (e.g., a network request), and you want to keep trying without handling or
|
||
* worrying about the errors.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* let counter = 0
|
||
*
|
||
* const effect = Effect.try(() => {
|
||
* counter++
|
||
* if (counter < 3) {
|
||
* console.log("running effect")
|
||
* throw new Error("error")
|
||
* } else {
|
||
* console.log("effect done")
|
||
* return "some result"
|
||
* }
|
||
* })
|
||
*
|
||
* const program = Effect.eventually(effect)
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output:
|
||
* // running effect
|
||
* // running effect
|
||
* // effect done
|
||
* // some result
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const eventually = exports.eventually = effect.eventually;
|
||
/**
|
||
* Discards both the success and failure values of an effect.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* `ignore` allows you to run an effect without caring about its result, whether
|
||
* it succeeds or fails. This is useful when you only care about the side
|
||
* effects of the effect and do not need to handle or process its outcome.
|
||
*
|
||
* **Example** (Using Effect.ignore to Discard Values)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // ┌─── Effect<number, string, never>
|
||
* // ▼
|
||
* const task = Effect.fail("Uh oh!").pipe(Effect.as(5))
|
||
*
|
||
* // ┌─── Effect<void, never, never>
|
||
* // ▼
|
||
* const program = Effect.ignore(task)
|
||
* ```
|
||
*
|
||
* @see {@link ignoreLogged} to log failures while ignoring them.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const ignore = exports.ignore = effect.ignore;
|
||
/**
|
||
* Ignores the result of an effect but logs any failures.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function takes an effect and returns a new effect that ignores whether
|
||
* the original effect succeeds or fails. However, if the effect fails, it will
|
||
* log the failure at the Debug level, so you can keep track of any issues that
|
||
* arise.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful in scenarios where you want to continue with your program
|
||
* regardless of the result of the effect, but you still want to be aware of
|
||
* potential failures that may need attention later.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const ignoreLogged = exports.ignoreLogged = effect.ignoreLogged;
|
||
/**
|
||
* Combines all errors from concurrent operations into a single error.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function is used when you have multiple operations running at the same
|
||
* time, and you want to capture all the errors that occur across those
|
||
* operations. Instead of handling each error separately, it combines all the
|
||
* errors into one unified error.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* When using this function, any errors that occur in the concurrently running
|
||
* operations will be grouped together into a single error. This helps simplify
|
||
* error handling in cases where you don't need to differentiate between each
|
||
* failure, but simply want to know that multiple failures occurred.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const fail1 = Effect.fail("Oh uh!")
|
||
* const fail2 = Effect.fail("Oh no!")
|
||
* const die = Effect.dieMessage("Boom!")
|
||
*
|
||
* // Run all effects concurrently and capture all errors
|
||
* const program = Effect.all([fail1, fail2, die], {
|
||
* concurrency: "unbounded"
|
||
* }).pipe(Effect.asVoid, Effect.parallelErrors)
|
||
*
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: { _id: 'Cause', _tag: 'Fail', failure: [ 'Oh uh!', 'Oh no!' ] }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const parallelErrors = exports.parallelErrors = effect.parallelErrors;
|
||
/**
|
||
* Transforms an effect to expose detailed error causes.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function enhances an effect by providing detailed information about any
|
||
* error, defect, or interruption that may occur during its execution. It
|
||
* modifies the error channel of the effect so that it includes a full cause of
|
||
* the failure, wrapped in a `Cause<E>` type.
|
||
*
|
||
* After applying this function, you can use operators like {@link catchAll} and
|
||
* {@link catchTags} to handle specific types of errors.
|
||
*
|
||
* If you no longer need the detailed cause information, you can revert the
|
||
* changes using {@link unsandbox} to return to the original error-handling
|
||
* behavior.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* // ┌─── Effect<string, Error, never>
|
||
* // ▼
|
||
* const task = Effect.fail(new Error("Oh uh!")).pipe(
|
||
* Effect.as("primary result")
|
||
* )
|
||
*
|
||
* // ┌─── Effect<string, Cause<Error>, never>
|
||
* // ▼
|
||
* const sandboxed = Effect.sandbox(task)
|
||
*
|
||
* const program = Effect.catchTags(sandboxed, {
|
||
* Die: (cause) =>
|
||
* Console.log(`Caught a defect: ${cause.defect}`).pipe(
|
||
* Effect.as("fallback result on defect")
|
||
* ),
|
||
* Interrupt: (cause) =>
|
||
* Console.log(`Caught a defect: ${cause.fiberId}`).pipe(
|
||
* Effect.as("fallback result on fiber interruption")
|
||
* ),
|
||
* Fail: (cause) =>
|
||
* Console.log(`Caught a defect: ${cause.error}`).pipe(
|
||
* Effect.as("fallback result on failure")
|
||
* )
|
||
* })
|
||
*
|
||
* // Restore the original error handling with unsandbox
|
||
* const main = Effect.unsandbox(program)
|
||
*
|
||
* Effect.runPromise(main).then(console.log)
|
||
* // Output:
|
||
* // Caught a defect: Oh uh!
|
||
* // fallback result on failure
|
||
* ```
|
||
*
|
||
* @see {@link unsandbox} to restore the original error handling.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const sandbox = exports.sandbox = effect.sandbox;
|
||
/**
|
||
* Retries a failing effect based on a defined retry policy.
|
||
*
|
||
* **Details**
|
||
*
|
||
* The `Effect.retry` function takes an effect and a {@link Schedule} policy,
|
||
* and will automatically retry the effect if it fails, following the rules of
|
||
* the policy.
|
||
*
|
||
* If the effect ultimately succeeds, the result will be returned.
|
||
*
|
||
* If the maximum retries are exhausted and the effect still fails, the failure
|
||
* is propagated.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This can be useful when dealing with intermittent failures, such as network
|
||
* issues or temporary resource unavailability. By defining a retry policy, you
|
||
* can control the number of retries, the delay between them, and when to stop
|
||
* retrying.
|
||
*
|
||
* **Example** (Retrying with a Fixed Delay)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Schedule } from "effect"
|
||
*
|
||
* let count = 0
|
||
*
|
||
* // Simulates an effect with possible failures
|
||
* const task = Effect.async<string, Error>((resume) => {
|
||
* if (count <= 2) {
|
||
* count++
|
||
* console.log("failure")
|
||
* resume(Effect.fail(new Error()))
|
||
* } else {
|
||
* console.log("success")
|
||
* resume(Effect.succeed("yay!"))
|
||
* }
|
||
* })
|
||
*
|
||
* // Define a repetition policy using a fixed delay between retries
|
||
* const policy = Schedule.fixed("100 millis")
|
||
*
|
||
* const repeated = Effect.retry(task, policy)
|
||
*
|
||
* Effect.runPromise(repeated).then(console.log)
|
||
* // Output:
|
||
* // failure
|
||
* // failure
|
||
* // failure
|
||
* // success
|
||
* // yay!
|
||
* ```
|
||
*
|
||
* **Example** (Retrying a Task up to 5 times)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* let count = 0
|
||
*
|
||
* // Simulates an effect with possible failures
|
||
* const task = Effect.async<string, Error>((resume) => {
|
||
* if (count <= 2) {
|
||
* count++
|
||
* console.log("failure")
|
||
* resume(Effect.fail(new Error()))
|
||
* } else {
|
||
* console.log("success")
|
||
* resume(Effect.succeed("yay!"))
|
||
* }
|
||
* })
|
||
*
|
||
* // Retry the task up to 5 times
|
||
* Effect.runPromise(Effect.retry(task, { times: 5 })).then(console.log)
|
||
* // Output:
|
||
* // failure
|
||
* // failure
|
||
* // failure
|
||
* // success
|
||
* ```
|
||
*
|
||
* **Example** (Retrying Until a Specific Condition is Met)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* let count = 0
|
||
*
|
||
* // Define an effect that simulates varying error on each invocation
|
||
* const action = Effect.failSync(() => {
|
||
* console.log(`Action called ${++count} time(s)`)
|
||
* return `Error ${count}`
|
||
* })
|
||
*
|
||
* // Retry the action until a specific condition is met
|
||
* const program = Effect.retry(action, {
|
||
* until: (err) => err === "Error 3"
|
||
* })
|
||
*
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // Action called 1 time(s)
|
||
* // Action called 2 time(s)
|
||
* // Action called 3 time(s)
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: { _id: 'Cause', _tag: 'Fail', failure: 'Error 3' }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @see {@link retryOrElse} for a version that allows you to run a fallback.
|
||
* @see {@link repeat} if your retry condition is based on successful outcomes rather than errors.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const retry = exports.retry = schedule_.retry_combined;
|
||
/**
|
||
* Apply an `ExecutionPlan` to the effect, which allows you to fallback to
|
||
* different resources in case of failure.
|
||
*
|
||
* @since 3.16.0
|
||
* @category Error handling
|
||
* @experimental
|
||
*/
|
||
const withExecutionPlan = exports.withExecutionPlan = internalExecutionPlan.withExecutionPlan;
|
||
/**
|
||
* Retries a failing effect and runs a fallback effect if retries are exhausted.
|
||
*
|
||
* **Details**
|
||
*
|
||
* The `Effect.retryOrElse` function attempts to retry a failing effect multiple
|
||
* times according to a defined {@link Schedule} policy.
|
||
*
|
||
* If the retries are exhausted and the effect still fails, it runs a fallback
|
||
* effect instead.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function is useful when you want to handle failures gracefully by
|
||
* specifying an alternative action after repeated failures.
|
||
*
|
||
* **Example** (Retrying with Fallback)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Schedule, Console } from "effect"
|
||
*
|
||
* let count = 0
|
||
*
|
||
* // Simulates an effect with possible failures
|
||
* const task = Effect.async<string, Error>((resume) => {
|
||
* if (count <= 2) {
|
||
* count++
|
||
* console.log("failure")
|
||
* resume(Effect.fail(new Error()))
|
||
* } else {
|
||
* console.log("success")
|
||
* resume(Effect.succeed("yay!"))
|
||
* }
|
||
* })
|
||
*
|
||
* // Retry the task with a delay between retries and a maximum of 2 retries
|
||
* const policy = Schedule.addDelay(Schedule.recurs(2), () => "100 millis")
|
||
*
|
||
* // If all retries fail, run the fallback effect
|
||
* const repeated = Effect.retryOrElse(
|
||
* task,
|
||
* policy,
|
||
* // fallback
|
||
* () => Console.log("orElse").pipe(Effect.as("default value"))
|
||
* )
|
||
*
|
||
* Effect.runPromise(repeated).then(console.log)
|
||
* // Output:
|
||
* // failure
|
||
* // failure
|
||
* // failure
|
||
* // orElse
|
||
* // default value
|
||
* ```
|
||
*
|
||
* @see {@link retry} for a version that does not run a fallback effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const retryOrElse = exports.retryOrElse = schedule_.retryOrElse_Effect;
|
||
const try_ = exports.try = effect.try_;
|
||
/**
|
||
* Returns an effect that maps its success using the specified side-effecting
|
||
* `try` function, converting any errors into typed failed effects using the
|
||
* `catch` function.
|
||
*
|
||
* @see {@link tryPromise} for a version that works with asynchronous computations.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const tryMap = exports.tryMap = effect.tryMap;
|
||
/**
|
||
* Returns an effect that maps its success using the specified side-effecting
|
||
* `try` function, converting any promise rejections into typed failed effects
|
||
* using the `catch` function.
|
||
*
|
||
* An optional `AbortSignal` can be provided to allow for interruption of the
|
||
* wrapped `Promise` API.
|
||
*
|
||
* @see {@link tryMap} for a version that works with synchronous computations.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const tryMapPromise = exports.tryMapPromise = effect.tryMapPromise;
|
||
/**
|
||
* Creates an `Effect` that represents an asynchronous computation that might
|
||
* fail.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* In situations where you need to perform asynchronous operations that might
|
||
* fail, such as fetching data from an API, you can use the `tryPromise`
|
||
* constructor. This constructor is designed to handle operations that could
|
||
* throw exceptions by capturing those exceptions and transforming them into
|
||
* manageable errors.
|
||
*
|
||
* **Error Handling**
|
||
*
|
||
* There are two ways to handle errors with `tryPromise`:
|
||
*
|
||
* 1. If you don't provide a `catch` function, the error is caught and the
|
||
* effect fails with an `UnknownException`.
|
||
* 2. If you provide a `catch` function, the error is caught and the `catch`
|
||
* function maps it to an error of type `E`.
|
||
*
|
||
* **Interruptions**
|
||
*
|
||
* An optional `AbortSignal` can be provided to allow for interruption of the
|
||
* wrapped `Promise` API.
|
||
*
|
||
* **Example** (Fetching a TODO Item)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const getTodo = (id: number) =>
|
||
* // Will catch any errors and propagate them as UnknownException
|
||
* Effect.tryPromise(() =>
|
||
* fetch(`https://jsonplaceholder.typicode.com/todos/${id}`)
|
||
* )
|
||
*
|
||
* // ┌─── Effect<Response, UnknownException, never>
|
||
* // ▼
|
||
* const program = getTodo(1)
|
||
* ```
|
||
*
|
||
* **Example** (Custom Error Handling)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const getTodo = (id: number) =>
|
||
* Effect.tryPromise({
|
||
* try: () => fetch(`https://jsonplaceholder.typicode.com/todos/${id}`),
|
||
* // remap the error
|
||
* catch: (unknown) => new Error(`something went wrong ${unknown}`)
|
||
* })
|
||
*
|
||
* // ┌─── Effect<Response, Error, never>
|
||
* // ▼
|
||
* const program = getTodo(1)
|
||
* ```
|
||
*
|
||
* @see {@link promise} if the effectful computation is asynchronous and does not throw errors.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const tryPromise = exports.tryPromise = effect.tryPromise;
|
||
/**
|
||
* The `unsandbox` function is used to revert an effect that has been
|
||
* sandboxed by {@link sandbox}. When you apply `unsandbox`, the
|
||
* effect's error channel is restored to its original state, without the
|
||
* detailed `Cause<E>` information. This means that any underlying causes of
|
||
* errors, defects, or fiber interruptions are no longer exposed in the error
|
||
* channel.
|
||
*
|
||
* This function is useful when you want to remove the detailed error tracking
|
||
* provided by `sandbox` and return to the standard error handling for
|
||
* your effect. Once unsandboxed, the effect behaves as if `sandbox` was
|
||
* never applied.
|
||
*
|
||
* @see {@link sandbox} to expose the full cause of failures, defects, or interruptions.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error handling
|
||
*/
|
||
const unsandbox = exports.unsandbox = effect.unsandbox;
|
||
/**
|
||
* Allows interruption of the current fiber, even in uninterruptible regions.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This effect checks whether any other fibers are attempting to interrupt the
|
||
* current fiber. If so, it allows the current fiber to perform a
|
||
* self-interruption.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful in situations where you want to allow interruption to happen
|
||
* even in regions of the code that are normally uninterruptible.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Interruption
|
||
*/
|
||
const allowInterrupt = exports.allowInterrupt = effect.allowInterrupt;
|
||
/**
|
||
* Checks if interruption is allowed and executes a callback accordingly.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function checks the current interrupt status of the running fiber. It
|
||
* then calls the provided callback, passing a boolean indicating whether
|
||
* interruption is allowed.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful for handling specific logic based on whether the current
|
||
* operation can be interrupted, such as when performing asynchronous operations
|
||
* or handling cancellation.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* yield* Effect.checkInterruptible((isInterruptible) => {
|
||
* if (isInterruptible) {
|
||
* return Console.log("You can interrupt this operation.")
|
||
* } else {
|
||
* return Console.log("This operation cannot be interrupted.")
|
||
* }
|
||
* })
|
||
* })
|
||
*
|
||
* Effect.runPromise(program)
|
||
* // Output: You can interrupt this operation.
|
||
*
|
||
* Effect.runPromise(program.pipe(Effect.uninterruptible))
|
||
* // Output: This operation cannot be interrupted.
|
||
*
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Interruption
|
||
*/
|
||
const checkInterruptible = exports.checkInterruptible = core.checkInterruptible;
|
||
/**
|
||
* Provides a way to handle timeouts in uninterruptible effects, allowing them
|
||
* to continue in the background while the main control flow proceeds with the
|
||
* timeout error.
|
||
*
|
||
* **Details**
|
||
*
|
||
* The `disconnect` function allows an uninterruptible effect to continue
|
||
* running in the background, while enabling the main control flow to
|
||
* immediately recognize a timeout condition. This is useful when you want to
|
||
* avoid blocking the program due to long-running tasks, especially when those
|
||
* tasks do not need to affect the flow of the rest of the program.
|
||
*
|
||
* Without `disconnect`, an uninterruptible effect will ignore the
|
||
* timeout and continue executing until it completes. The timeout error will
|
||
* only be assessed after the effect finishes, which can cause delays in
|
||
* recognizing a timeout.
|
||
*
|
||
* With `disconnect`, the uninterruptible effect proceeds in the
|
||
* background while the main program flow can immediately handle the timeout
|
||
* error or trigger alternative logic. This enables faster timeout handling
|
||
* without waiting for the completion of the long-running task.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const longRunningTask = Effect.gen(function* () {
|
||
* console.log("Start heavy processing...")
|
||
* yield* Effect.sleep("5 seconds") // Simulate a long process
|
||
* console.log("Heavy processing done.")
|
||
* return "Data processed"
|
||
* })
|
||
*
|
||
* const timedEffect = longRunningTask.pipe(
|
||
* Effect.uninterruptible,
|
||
* // Allows the task to finish in the background if it times out
|
||
* Effect.disconnect,
|
||
* Effect.timeout("1 second")
|
||
* )
|
||
*
|
||
* Effect.runPromiseExit(timedEffect).then(console.log)
|
||
* // Output:
|
||
* // Start heavy processing...
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: {
|
||
* // _id: 'Cause',
|
||
* // _tag: 'Fail',
|
||
* // failure: { _tag: 'TimeoutException' }
|
||
* // }
|
||
* // }
|
||
* // Heavy processing done.
|
||
* ```
|
||
*
|
||
* @see {@link timeout} for a version that interrupts the effect.
|
||
* @see {@link uninterruptible} for creating an uninterruptible effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Interruption
|
||
*/
|
||
const disconnect = exports.disconnect = fiberRuntime.disconnect;
|
||
/**
|
||
* Represents an effect that interrupts the current fiber.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This effect models the explicit interruption of the fiber in which it runs.
|
||
* When executed, it causes the fiber to stop its operation immediately,
|
||
* capturing the interruption details such as the fiber's ID and its start time.
|
||
* The resulting interruption can be observed in the `Exit` type if the effect
|
||
* is run with functions like {@link runPromiseExit}.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const program = Effect.gen(function* () {
|
||
* console.log("start")
|
||
* yield* Effect.sleep("2 seconds")
|
||
* yield* Effect.interrupt
|
||
* console.log("done")
|
||
* return "some result"
|
||
* })
|
||
*
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // start
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: {
|
||
* // _id: 'Cause',
|
||
* // _tag: 'Interrupt',
|
||
* // fiberId: {
|
||
* // _id: 'FiberId',
|
||
* // _tag: 'Runtime',
|
||
* // id: 0,
|
||
* // startTimeMillis: ...
|
||
* // }
|
||
* // }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Interruption
|
||
*/
|
||
const interrupt = exports.interrupt = core.interrupt;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Interruption
|
||
*/
|
||
const interruptWith = exports.interruptWith = core.interruptWith;
|
||
/**
|
||
* Marks an effect as interruptible.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Interruption
|
||
*/
|
||
const interruptible = exports.interruptible = core.interruptible;
|
||
/**
|
||
* This function behaves like {@link interruptible}, but it also provides a
|
||
* `restore` function. This function can be used to restore the interruptibility
|
||
* of any specific region of code.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Interruption
|
||
*/
|
||
const interruptibleMask = exports.interruptibleMask = core.interruptibleMask;
|
||
/**
|
||
* Registers a cleanup effect to run when an effect is interrupted.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to specify an effect to run when the fiber is
|
||
* interrupted. This effect will be executed when the fiber is interrupted,
|
||
* allowing you to perform cleanup or other actions.
|
||
*
|
||
* **Example** (Running a Cleanup Action on Interruption)
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* // This handler is executed when the fiber is interrupted
|
||
* const handler = Effect.onInterrupt((_fibers) => Console.log("Cleanup completed"))
|
||
*
|
||
* const success = Console.log("Task completed").pipe(Effect.as("some result"), handler)
|
||
*
|
||
* Effect.runFork(success)
|
||
* // Output:
|
||
* // Task completed
|
||
*
|
||
* const failure = Console.log("Task failed").pipe(Effect.andThen(Effect.fail("some error")), handler)
|
||
*
|
||
* Effect.runFork(failure)
|
||
* // Output:
|
||
* // Task failed
|
||
*
|
||
* const interruption = Console.log("Task interrupted").pipe(Effect.andThen(Effect.interrupt), handler)
|
||
*
|
||
* Effect.runFork(interruption)
|
||
* // Output:
|
||
* // Task interrupted
|
||
* // Cleanup completed
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Interruption
|
||
*/
|
||
const onInterrupt = exports.onInterrupt = core.onInterrupt;
|
||
/**
|
||
* Marks an effect as uninterruptible.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Interruption
|
||
*/
|
||
const uninterruptible = exports.uninterruptible = core.uninterruptible;
|
||
/**
|
||
* This function behaves like {@link uninterruptible}, but it also provides a
|
||
* `restore` function. This function can be used to restore the interruptibility
|
||
* of any specific region of code.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Interruption
|
||
*/
|
||
const uninterruptibleMask = exports.uninterruptibleMask = core.uninterruptibleMask;
|
||
/**
|
||
* 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
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* 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 Condition Checking
|
||
* @since 3.4.0
|
||
*/
|
||
const liftPredicate = exports.liftPredicate = effect.liftPredicate;
|
||
/**
|
||
* Replaces the value inside an effect with a constant value.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to ignore the original value inside an effect and
|
||
* replace it with a constant value.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* It is useful when you no longer need the value produced by an effect but want
|
||
* to ensure that the effect completes successfully with a specific constant
|
||
* result instead. For instance, you can replace the value produced by a
|
||
* computation with a predefined value, ignoring what was calculated before.
|
||
*
|
||
* **Example** (Replacing a Value)
|
||
*
|
||
* ```ts
|
||
* import { pipe, Effect } from "effect"
|
||
*
|
||
* // Replaces the value 5 with the constant "new value"
|
||
* const program = pipe(Effect.succeed(5), Effect.as("new value"))
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output: "new value"
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Mapping
|
||
*/
|
||
const as = exports.as = core.as;
|
||
/**
|
||
* This function maps the success value of an `Effect` value to a `Some` value
|
||
* in an `Option` value. If the original `Effect` value fails, the returned
|
||
* `Effect` value will also fail.
|
||
*
|
||
* @category Mapping
|
||
* @since 2.0.0
|
||
*/
|
||
const asSome = exports.asSome = effect.asSome;
|
||
/**
|
||
* This function maps the error value of an `Effect` value to a `Some` value
|
||
* in an `Option` value. If the original `Effect` value succeeds, the returned
|
||
* `Effect` value will also succeed.
|
||
*
|
||
* @category Mapping
|
||
* @since 2.0.0
|
||
*/
|
||
const asSomeError = exports.asSomeError = effect.asSomeError;
|
||
/**
|
||
* This function maps the success value of an `Effect` value to `void`. If the
|
||
* original `Effect` value succeeds, the returned `Effect` value will also
|
||
* succeed. If the original `Effect` value fails, the returned `Effect` value
|
||
* will fail with the same error.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Mapping
|
||
*/
|
||
const asVoid = exports.asVoid = core.asVoid;
|
||
/**
|
||
* Swaps the success and error channels of an effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function reverses the flow of an effect by swapping its success and
|
||
* error channels. The success value becomes an error, and the error value
|
||
* becomes a success.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // ┌─── Effect<number, string, never>
|
||
* // ▼
|
||
* const program = Effect.fail("Oh uh!").pipe(Effect.as(2))
|
||
*
|
||
* // ┌─── Effect<string, number, never>
|
||
* // ▼
|
||
* const flipped = Effect.flip(program)
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Mapping
|
||
*/
|
||
const flip = exports.flip = core.flip;
|
||
/**
|
||
* Swaps the error/value parameters, applies the function `f` and flips the
|
||
* parameters back
|
||
*
|
||
* @since 2.0.0
|
||
* @category Mapping
|
||
*/
|
||
const flipWith = exports.flipWith = effect.flipWith;
|
||
/**
|
||
* Transforms the value inside an effect by applying a function to it.
|
||
*
|
||
* **Syntax**
|
||
*
|
||
* ```ts skip-type-checking
|
||
* const mappedEffect = pipe(myEffect, Effect.map(transformation))
|
||
* // or
|
||
* const mappedEffect = Effect.map(myEffect, transformation)
|
||
* // or
|
||
* const mappedEffect = myEffect.pipe(Effect.map(transformation))
|
||
* ```
|
||
*
|
||
* **Details**
|
||
*
|
||
* `map` takes a function and applies it to the value contained within an
|
||
* effect, creating a new effect with the transformed value.
|
||
*
|
||
* It's important to note that effects are immutable, meaning that the original
|
||
* effect is not modified. Instead, a new effect is returned with the updated
|
||
* value.
|
||
*
|
||
* **Example** (Adding a Service Charge)
|
||
*
|
||
* ```ts
|
||
* import { pipe, Effect } from "effect"
|
||
*
|
||
* const addServiceCharge = (amount: number) => amount + 1
|
||
*
|
||
* const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))
|
||
*
|
||
* const finalAmount = pipe(
|
||
* fetchTransactionAmount,
|
||
* Effect.map(addServiceCharge)
|
||
* )
|
||
*
|
||
* Effect.runPromise(finalAmount).then(console.log)
|
||
* // Output: 101
|
||
* ```
|
||
*
|
||
* @see {@link mapError} for a version that operates on the error channel.
|
||
* @see {@link mapBoth} for a version that operates on both channels.
|
||
* @see {@link flatMap} or {@link andThen} for a version that can return a new effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Mapping
|
||
*/
|
||
const map = exports.map = core.map;
|
||
/**
|
||
* Applies a stateful transformation to each element of a collection, producing
|
||
* new elements along with an updated state.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use `mapAccum` when you need to process each element of a collection while
|
||
* keeping track of some state across iterations.
|
||
*
|
||
* **Details**
|
||
*
|
||
* `mapAccum` takes an initial state (`initial`) and a function (`f`) that is
|
||
* applied to each element. This function returns a new state and a transformed
|
||
* element. The final effect produces both the accumulated state and the
|
||
* transformed collection.
|
||
*
|
||
* If the input collection is a non-empty array, the return type will match the
|
||
* input collection type.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // Define an initial state and a transformation function
|
||
* const initialState = 0
|
||
*
|
||
* const transformation = (state: number, element: string) =>
|
||
* Effect.succeed<[number, string]>([state + element.length, element.toUpperCase()])
|
||
*
|
||
* // Apply mapAccum to transform an array of strings
|
||
* const program = Effect.mapAccum(["a", "bb", "ccc"], initialState, transformation)
|
||
*
|
||
* Effect.runPromise(program).then(([finalState, transformedCollection]) => {
|
||
* console.log(finalState)
|
||
* console.log(transformedCollection)
|
||
* })
|
||
* // Output:
|
||
* // 6
|
||
* // [ 'A', 'BB', 'CCC' ]
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Mapping
|
||
*/
|
||
const mapAccum = exports.mapAccum = effect.mapAccum;
|
||
/**
|
||
* Applies transformations to both the success and error channels of an effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function takes two map functions as arguments: one for the error channel
|
||
* and one for the success channel. You can use it when you want to modify both
|
||
* the error and the success values without altering the overall success or
|
||
* failure status of the effect.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // ┌─── Effect<number, string, never>
|
||
* // ▼
|
||
* const simulatedTask = Effect.fail("Oh no!").pipe(Effect.as(1))
|
||
*
|
||
* // ┌─── Effect<boolean, Error, never>
|
||
* // ▼
|
||
* const modified = Effect.mapBoth(simulatedTask, {
|
||
* onFailure: (message) => new Error(message),
|
||
* onSuccess: (n) => n > 0
|
||
* })
|
||
* ```
|
||
*
|
||
* @see {@link map} for a version that operates on the success channel.
|
||
* @see {@link mapError} for a version that operates on the error channel.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Mapping
|
||
*/
|
||
const mapBoth = exports.mapBoth = core.mapBoth;
|
||
/**
|
||
* Transforms or modifies the error produced by an effect without affecting its
|
||
* success value.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function is helpful when you want to enhance the error with additional
|
||
* information, change the error type, or apply custom error handling while
|
||
* keeping the original behavior of the effect's success values intact. It only
|
||
* operates on the error channel and leaves the success channel unchanged.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // ┌─── Effect<number, string, never>
|
||
* // ▼
|
||
* const simulatedTask = Effect.fail("Oh no!").pipe(Effect.as(1))
|
||
*
|
||
* // ┌─── Effect<number, Error, never>
|
||
* // ▼
|
||
* const mapped = Effect.mapError(
|
||
* simulatedTask,
|
||
* (message) => new Error(message)
|
||
* )
|
||
* ```
|
||
*
|
||
* @see {@link map} for a version that operates on the success channel.
|
||
* @see {@link mapBoth} for a version that operates on both channels.
|
||
* @see {@link orElseFail} if you want to replace the error with a new one.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Mapping
|
||
*/
|
||
const mapError = exports.mapError = core.mapError;
|
||
/**
|
||
* Maps the cause of failure of an effect using a specified function.
|
||
*
|
||
* @see {@link sandbox} for a version that exposes the full cause of failures, defects, or interruptions.
|
||
* @see {@link catchAllCause} for a version that can recover from all types of defects.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Mapping
|
||
*/
|
||
const mapErrorCause = exports.mapErrorCause = effect.mapErrorCause;
|
||
/**
|
||
* Combines both success and error channels of an effect into a single outcome.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function transforms an effect that may fail into one that always returns
|
||
* a value, where both success and failure outcomes are handled as values in the
|
||
* success channel.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This can be useful when you want to continue execution regardless of the
|
||
* error type and still capture both successful results and errors as part of
|
||
* the outcome.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // ┌─── Effect<number, string, never>
|
||
* // ▼
|
||
* const program = Effect.fail("Oh uh!").pipe(Effect.as(2))
|
||
*
|
||
* // ┌─── Effect<number | string, never, never>
|
||
* // ▼
|
||
* const recovered = Effect.merge(program)
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Mapping
|
||
*/
|
||
const merge = exports.merge = effect.merge;
|
||
/**
|
||
* Returns a new effect with the boolean value of this effect negated.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Mapping
|
||
*/
|
||
const negate = exports.negate = effect.negate;
|
||
/**
|
||
* Creates a scoped resource using an `acquire` and `release` effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function helps manage resources by combining two `Effect` values: one
|
||
* for acquiring the resource and one for releasing it.
|
||
*
|
||
* `acquireRelease` does the following:
|
||
*
|
||
* 1. Ensures that the effect that acquires the resource will not be
|
||
* interrupted. Note that acquisition may still fail due to internal
|
||
* reasons (such as an uncaught exception).
|
||
* 2. Ensures that the `release` effect will not be interrupted, and will be
|
||
* executed as long as the acquisition effect successfully acquires the
|
||
* resource.
|
||
*
|
||
* If the `acquire` function succeeds, the `release` function is added to the
|
||
* list of finalizers for the scope. This ensures that the release will happen
|
||
* automatically when the scope is closed.
|
||
*
|
||
* Both `acquire` and `release` run uninterruptibly, meaning they cannot be
|
||
* interrupted while they are executing.
|
||
*
|
||
* Additionally, the `release` function can be influenced by the exit value when
|
||
* the scope closes, allowing for custom handling of how the resource is
|
||
* released based on the execution outcome.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function is used to ensure that an effect that represents the
|
||
* acquisition of a resource (for example, opening a file, launching a thread,
|
||
* etc.) will not be interrupted, and that the resource will always be released
|
||
* when the `Effect` completes execution.
|
||
*
|
||
* **Example** (Defining a Simple Resource)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // Define an interface for a resource
|
||
* interface MyResource {
|
||
* readonly contents: string
|
||
* readonly close: () => Promise<void>
|
||
* }
|
||
*
|
||
* // Simulate resource acquisition
|
||
* const getMyResource = (): Promise<MyResource> =>
|
||
* Promise.resolve({
|
||
* contents: "lorem ipsum",
|
||
* close: () =>
|
||
* new Promise((resolve) => {
|
||
* console.log("Resource released")
|
||
* resolve()
|
||
* })
|
||
* })
|
||
*
|
||
* // Define how the resource is acquired
|
||
* const acquire = Effect.tryPromise({
|
||
* try: () =>
|
||
* getMyResource().then((res) => {
|
||
* console.log("Resource acquired")
|
||
* return res
|
||
* }),
|
||
* catch: () => new Error("getMyResourceError")
|
||
* })
|
||
*
|
||
* // Define how the resource is released
|
||
* const release = (res: MyResource) => Effect.promise(() => res.close())
|
||
*
|
||
* // Create the resource management workflow
|
||
* //
|
||
* // ┌─── Effect<MyResource, Error, Scope>
|
||
* // ▼
|
||
* const resource = Effect.acquireRelease(acquire, release)
|
||
* ```
|
||
*
|
||
* @see {@link acquireUseRelease} for a version that automatically handles the scoping of resources.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const acquireRelease = exports.acquireRelease = fiberRuntime.acquireRelease;
|
||
/**
|
||
* Creates a scoped resource with an interruptible acquire action.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function is similar to {@link acquireRelease}, but it allows the
|
||
* acquisition of the resource to be interrupted. The `acquire` effect, which
|
||
* represents the process of obtaining the resource, can be interrupted if
|
||
* necessary.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const acquireReleaseInterruptible = exports.acquireReleaseInterruptible = fiberRuntime.acquireReleaseInterruptible;
|
||
/**
|
||
* Many real-world operations involve working with resources that must be released when no longer needed, such as:
|
||
*
|
||
* - Database connections
|
||
* - File handles
|
||
* - Network requests
|
||
*
|
||
* This function ensures that a resource is:
|
||
*
|
||
* 1. **Acquired** properly.
|
||
* 2. **Used** for its intended purpose.
|
||
* 3. **Released** even if an error occurs.
|
||
*
|
||
* **Example** (Automatically Managing Resource Lifetime)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* // Define an interface for a resource
|
||
* interface MyResource {
|
||
* readonly contents: string
|
||
* readonly close: () => Promise<void>
|
||
* }
|
||
*
|
||
* // Simulate resource acquisition
|
||
* const getMyResource = (): Promise<MyResource> =>
|
||
* Promise.resolve({
|
||
* contents: "lorem ipsum",
|
||
* close: () =>
|
||
* new Promise((resolve) => {
|
||
* console.log("Resource released")
|
||
* resolve()
|
||
* })
|
||
* })
|
||
*
|
||
* // Define how the resource is acquired
|
||
* const acquire = Effect.tryPromise({
|
||
* try: () =>
|
||
* getMyResource().then((res) => {
|
||
* console.log("Resource acquired")
|
||
* return res
|
||
* }),
|
||
* catch: () => new Error("getMyResourceError")
|
||
* })
|
||
*
|
||
* // Define how the resource is released
|
||
* const release = (res: MyResource) => Effect.promise(() => res.close())
|
||
*
|
||
* const use = (res: MyResource) => Console.log(`content is ${res.contents}`)
|
||
*
|
||
* // ┌─── Effect<void, Error, never>
|
||
* // ▼
|
||
* const program = Effect.acquireUseRelease(acquire, use, release)
|
||
*
|
||
* Effect.runPromise(program)
|
||
* // Output:
|
||
* // Resource acquired
|
||
* // content is lorem ipsum
|
||
* // Resource released
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const acquireUseRelease = exports.acquireUseRelease = core.acquireUseRelease;
|
||
/**
|
||
* Ensures a finalizer is added to the scope of the calling effect, guaranteeing
|
||
* it runs when the scope is closed.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function adds a finalizer that will execute whenever the scope of the
|
||
* effect is closed, regardless of whether the effect succeeds, fails, or is
|
||
* interrupted. The finalizer receives the `Exit` value of the effect's scope,
|
||
* allowing it to react differently depending on how the effect concludes.
|
||
*
|
||
* Finalizers are a reliable way to manage resource cleanup, ensuring that
|
||
* resources such as file handles, network connections, or database transactions
|
||
* are properly closed even in the event of an unexpected interruption or error.
|
||
*
|
||
* Finalizers operate in conjunction with Effect's scoped resources. If an
|
||
* effect with a finalizer is wrapped in a scope, the finalizer will execute
|
||
* automatically when the scope ends.
|
||
*
|
||
* **Example** (Adding a Finalizer on Success)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* // ┌─── Effect<string, never, Scope>
|
||
* // ▼
|
||
* const program = Effect.gen(function* () {
|
||
* yield* Effect.addFinalizer((exit) =>
|
||
* Console.log(`Finalizer executed. Exit status: ${exit._tag}`)
|
||
* )
|
||
* return "some result"
|
||
* })
|
||
*
|
||
* // Wrapping the effect in a scope
|
||
* //
|
||
* // ┌─── Effect<string, never, never>
|
||
* // ▼
|
||
* const runnable = Effect.scoped(program)
|
||
*
|
||
* Effect.runPromiseExit(runnable).then(console.log)
|
||
* // Output:
|
||
* // Finalizer executed. Exit status: Success
|
||
* // { _id: 'Exit', _tag: 'Success', value: 'some result' }
|
||
* ```
|
||
*
|
||
* **Example** (Adding a Finalizer on Failure)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* // ┌─── Effect<never, string, Scope>
|
||
* // ▼
|
||
* const program = Effect.gen(function* () {
|
||
* yield* Effect.addFinalizer((exit) =>
|
||
* Console.log(`Finalizer executed. Exit status: ${exit._tag}`)
|
||
* )
|
||
* return yield* Effect.fail("Uh oh!")
|
||
* })
|
||
*
|
||
* // Wrapping the effect in a scope
|
||
* //
|
||
* // ┌─── Effect<never, string, never>
|
||
* // ▼
|
||
* const runnable = Effect.scoped(program)
|
||
*
|
||
* Effect.runPromiseExit(runnable).then(console.log)
|
||
* // Output:
|
||
* // Finalizer executed. Exit status: Failure
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: { _id: 'Cause', _tag: 'Fail', failure: 'Uh oh!' }
|
||
* // }
|
||
* ```
|
||
*
|
||
* **Example** (Adding a Finalizer on Interruption)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* // ┌─── Effect<never, never, Scope>
|
||
* // ▼
|
||
* const program = Effect.gen(function* () {
|
||
* yield* Effect.addFinalizer((exit) =>
|
||
* Console.log(`Finalizer executed. Exit status: ${exit._tag}`)
|
||
* )
|
||
* return yield* Effect.interrupt
|
||
* })
|
||
*
|
||
* // Wrapping the effect in a scope
|
||
* //
|
||
* // ┌─── Effect<never, never, never>
|
||
* // ▼
|
||
* const runnable = Effect.scoped(program)
|
||
*
|
||
* Effect.runPromiseExit(runnable).then(console.log)
|
||
* // Output:
|
||
* // Finalizer executed. Exit status: Failure
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: {
|
||
* // _id: 'Cause',
|
||
* // _tag: 'Interrupt',
|
||
* // fiberId: {
|
||
* // _id: 'FiberId',
|
||
* // _tag: 'Runtime',
|
||
* // id: 0,
|
||
* // startTimeMillis: ...
|
||
* // }
|
||
* // }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @see {@link onExit} for attaching a finalizer directly to an effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const addFinalizer = exports.addFinalizer = fiberRuntime.addFinalizer;
|
||
/**
|
||
* Guarantees the execution of a finalizer when an effect starts execution.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to specify a `finalizer` effect that will always be
|
||
* run once the effect starts execution, regardless of whether the effect
|
||
* succeeds, fails, or is interrupted.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful when you need to ensure that certain cleanup or final steps
|
||
* are executed in all cases, such as releasing resources or performing
|
||
* necessary logging.
|
||
*
|
||
* While this function provides strong guarantees about executing the finalizer,
|
||
* it is considered a low-level tool, which may not be ideal for more complex
|
||
* resource management. For higher-level resource management with automatic
|
||
* acquisition and release, see the {@link acquireRelease} family of functions.
|
||
* For use cases where you need access to the result of an effect, consider
|
||
* using {@link onExit}.
|
||
*
|
||
* **Example** (Running a Finalizer in All Outcomes)
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* // Define a cleanup effect
|
||
* const handler = Effect.ensuring(Console.log("Cleanup completed"))
|
||
*
|
||
* // Define a successful effect
|
||
* const success = Console.log("Task completed").pipe(
|
||
* Effect.as("some result"),
|
||
* handler
|
||
* )
|
||
*
|
||
* Effect.runFork(success)
|
||
* // Output:
|
||
* // Task completed
|
||
* // Cleanup completed
|
||
*
|
||
* // Define a failing effect
|
||
* const failure = Console.log("Task failed").pipe(
|
||
* Effect.andThen(Effect.fail("some error")),
|
||
* handler
|
||
* )
|
||
*
|
||
* Effect.runFork(failure)
|
||
* // Output:
|
||
* // Task failed
|
||
* // Cleanup completed
|
||
*
|
||
* // Define an interrupted effect
|
||
* const interruption = Console.log("Task interrupted").pipe(
|
||
* Effect.andThen(Effect.interrupt),
|
||
* handler
|
||
* )
|
||
*
|
||
* Effect.runFork(interruption)
|
||
* // Output:
|
||
* // Task interrupted
|
||
* // Cleanup completed
|
||
* ```
|
||
*
|
||
* @see {@link onExit} for a version that provides access to the result of an
|
||
* effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const ensuring = exports.ensuring = fiberRuntime.ensuring;
|
||
/**
|
||
* Ensures a cleanup effect runs whenever the calling effect fails, providing
|
||
* the failure cause to the cleanup effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to attach a cleanup effect that runs whenever the
|
||
* calling effect fails. The cleanup effect receives the cause of the failure,
|
||
* allowing you to perform actions such as logging, releasing resources, or
|
||
* executing additional recovery logic based on the error. The cleanup effect
|
||
* will execute even if the failure is due to interruption.
|
||
*
|
||
* Importantly, the cleanup effect itself is uninterruptible, ensuring that it
|
||
* completes regardless of external interruptions.
|
||
*
|
||
* **Example** (Running Cleanup Only on Failure)
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* // This handler logs the failure cause when the effect fails
|
||
* const handler = Effect.onError((cause) =>
|
||
* Console.log(`Cleanup completed: ${cause}`)
|
||
* )
|
||
*
|
||
* // Define a successful effect
|
||
* const success = Console.log("Task completed").pipe(
|
||
* Effect.as("some result"),
|
||
* handler
|
||
* )
|
||
*
|
||
* Effect.runFork(success)
|
||
* // Output:
|
||
* // Task completed
|
||
*
|
||
* // Define a failing effect
|
||
* const failure = Console.log("Task failed").pipe(
|
||
* Effect.andThen(Effect.fail("some error")),
|
||
* handler
|
||
* )
|
||
*
|
||
* Effect.runFork(failure)
|
||
* // Output:
|
||
* // Task failed
|
||
* // Cleanup completed: Error: some error
|
||
*
|
||
* // Define a failing effect
|
||
* const defect = Console.log("Task failed with defect").pipe(
|
||
* Effect.andThen(Effect.die("Boom!")),
|
||
* handler
|
||
* )
|
||
*
|
||
* Effect.runFork(defect)
|
||
* // Output:
|
||
* // Task failed with defect
|
||
* // Cleanup completed: Error: Boom!
|
||
*
|
||
* // Define an interrupted effect
|
||
* const interruption = Console.log("Task interrupted").pipe(
|
||
* Effect.andThen(Effect.interrupt),
|
||
* handler
|
||
* )
|
||
*
|
||
* Effect.runFork(interruption)
|
||
* // Output:
|
||
* // Task interrupted
|
||
* // Cleanup completed: All fibers interrupted without errors.
|
||
* ```
|
||
*
|
||
* @see {@link ensuring} for attaching a cleanup effect that runs on both success and failure.
|
||
* @see {@link onExit} for attaching a cleanup effect that runs on all possible exits.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const onError = exports.onError = core.onError;
|
||
/**
|
||
* Guarantees that a cleanup function runs regardless of whether the effect
|
||
* succeeds, fails, or is interrupted.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function ensures that a provided cleanup function is executed after the
|
||
* effect completes, regardless of the outcome. The cleanup function is given
|
||
* the `Exit` value of the effect, which provides detailed information about the
|
||
* result:
|
||
* - If the effect succeeds, the `Exit` contains the success value.
|
||
* - If the effect fails, the `Exit` contains the error or failure cause.
|
||
* - If the effect is interrupted, the `Exit` reflects the interruption.
|
||
*
|
||
* The cleanup function is guaranteed to run uninterruptibly, ensuring reliable
|
||
* resource management even in complex or high-concurrency scenarios.
|
||
*
|
||
* **Example** (Running a Cleanup Function with the Effect’s Result)
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect, Exit } from "effect"
|
||
*
|
||
* // Define a cleanup effect that logs the result
|
||
* const handler = Effect.onExit((exit) =>
|
||
* Console.log(`Cleanup completed: ${Exit.getOrElse(exit, String)}`)
|
||
* )
|
||
*
|
||
* // Define a successful effect
|
||
* const success = Console.log("Task completed").pipe(
|
||
* Effect.as("some result"),
|
||
* handler
|
||
* )
|
||
*
|
||
* Effect.runFork(success)
|
||
* // Output:
|
||
* // Task completed
|
||
* // Cleanup completed: some result
|
||
*
|
||
* // Define a failing effect
|
||
* const failure = Console.log("Task failed").pipe(
|
||
* Effect.andThen(Effect.fail("some error")),
|
||
* handler
|
||
* )
|
||
*
|
||
* Effect.runFork(failure)
|
||
* // Output:
|
||
* // Task failed
|
||
* // Cleanup completed: Error: some error
|
||
*
|
||
* // Define an interrupted effect
|
||
* const interruption = Console.log("Task interrupted").pipe(
|
||
* Effect.andThen(Effect.interrupt),
|
||
* handler
|
||
* )
|
||
*
|
||
* Effect.runFork(interruption)
|
||
* // Output:
|
||
* // Task interrupted
|
||
* // Cleanup completed: All fibers interrupted without errors.
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const onExit = exports.onExit = core.onExit;
|
||
/**
|
||
* Ensures that finalizers are run concurrently when the scope of an effect is
|
||
* closed.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function modifies the behavior of finalizers within a scoped workflow to
|
||
* allow them to run concurrently when the scope is closed.
|
||
*
|
||
* By default, finalizers are executed sequentially in reverse order of their
|
||
* addition, but this function changes that behavior to execute all finalizers
|
||
* concurrently.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Running finalizers concurrently can improve performance when multiple
|
||
* independent cleanup tasks need to be performed. However, it requires that
|
||
* these tasks do not depend on the order of execution or introduce race
|
||
* conditions.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* // Define a program that adds multiple finalizers
|
||
* const program = Effect.gen(function*() {
|
||
* yield* Effect.addFinalizer(() => Console.log("Finalizer 1 executed").pipe(Effect.delay("300 millis")))
|
||
* yield* Effect.addFinalizer(() => Console.log("Finalizer 2 executed").pipe(Effect.delay("100 millis")))
|
||
* yield* Effect.addFinalizer(() => Console.log("Finalizer 3 executed").pipe(Effect.delay("200 millis")))
|
||
* return "some result"
|
||
* })
|
||
*
|
||
* // Modify the program to ensure finalizers run in parallel
|
||
* const modified = program.pipe(Effect.parallelFinalizers)
|
||
*
|
||
* const runnable = Effect.scoped(modified)
|
||
*
|
||
* Effect.runFork(runnable)
|
||
* // Output:
|
||
* // Finalizer 2 executed
|
||
* // Finalizer 3 executed
|
||
* // Finalizer 1 executed
|
||
* ```
|
||
*
|
||
* @see {@link sequentialFinalizers} for a version that ensures finalizers are run sequentially.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const parallelFinalizers = exports.parallelFinalizers = fiberRuntime.parallelFinalizers;
|
||
/**
|
||
* Ensures that finalizers are run sequentially in reverse order of their
|
||
* addition.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function modifies the behavior of finalizers within a scoped workflow to
|
||
* ensure they are run sequentially in reverse order when the scope is closed.
|
||
*
|
||
* By default, finalizers are executed sequentially, so this only changes the
|
||
* behavior if the scope is configured to run finalizers concurrently.
|
||
*
|
||
* @see {@link parallelFinalizers} for a version that ensures finalizers are run concurrently.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const sequentialFinalizers = exports.sequentialFinalizers = fiberRuntime.sequentialFinalizers;
|
||
/**
|
||
* Applies a custom execution strategy to finalizers within a scoped workflow.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to control how finalizers are executed in a scope by
|
||
* applying a specified `ExecutionStrategy`. The `strategy` can dictate whether
|
||
* finalizers run (e.g., sequentially or in parallel).
|
||
*
|
||
* Additionally, the function provides a `restore` operation, which ensures that
|
||
* the effect passed to it is executed under the default execution strategy.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const finalizersMask = exports.finalizersMask = fiberRuntime.finalizersMask;
|
||
/**
|
||
* Provides access to the current scope in a scoped workflow.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const scope = exports.scope = fiberRuntime.scope;
|
||
/**
|
||
* Accesses the current scope and uses it to perform the specified effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const scopeWith = exports.scopeWith = fiberRuntime.scopeWith;
|
||
/**
|
||
* Creates a `Scope`, passes it to the specified effectful function, and closes
|
||
* the scope when the effect completes (whether through success, failure, or
|
||
* interruption).
|
||
*
|
||
* @since 3.11.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const scopedWith = exports.scopedWith = fiberRuntime.scopedWith;
|
||
/**
|
||
* Scopes all resources used in an effect to the lifetime of the effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function ensures that all resources used within an effect are tied to
|
||
* its lifetime. Finalizers for these resources are executed automatically when
|
||
* the effect completes, whether through success, failure, or interruption. This
|
||
* guarantees proper resource cleanup without requiring explicit management.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const scoped = exports.scoped = fiberRuntime.scopedEffect;
|
||
/**
|
||
* Scopes all resources acquired by one effect to the lifetime of another
|
||
* effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to scope the resources acquired by one effect
|
||
* (`self`) to the lifetime of another effect (`use`). This ensures that the
|
||
* resources are cleaned up as soon as the `use` effect completes, regardless of
|
||
* how the `use` effect ends (success, failure, or interruption).
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* const acquire = Console.log("Acquiring resource").pipe(
|
||
* Effect.as(1),
|
||
* Effect.tap(Effect.addFinalizer(() => Console.log("Releasing resource")))
|
||
* )
|
||
* const use = (resource: number) => Console.log(`Using resource: ${resource}`)
|
||
*
|
||
* const program = acquire.pipe(Effect.using(use))
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output:
|
||
* // Acquiring resource
|
||
* // Using resource: 1
|
||
* // Releasing resource
|
||
* ```
|
||
*
|
||
* @see {@link scopedWith} Manage scoped operations with a temporary scope.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const using = exports.using = fiberRuntime.using;
|
||
/**
|
||
* Returns the result of the effect and a finalizer to close its scope.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to retrieve both the result of an effect and a
|
||
* finalizer that can be used to manually close its scope. This is useful for
|
||
* workflows where you need early access to the result while retaining control
|
||
* over the resource cleanup process.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* const acquire = Console.log("Acquiring resource").pipe(
|
||
* Effect.as(1),
|
||
* Effect.tap(Effect.addFinalizer(() => Console.log("Releasing resource")))
|
||
* )
|
||
* const program = Effect.gen(function*() {
|
||
* const [finalizer, resource] = yield* Effect.withEarlyRelease(acquire)
|
||
* console.log(`Using resource: ${resource}`)
|
||
* yield* Effect.sleep("1 second")
|
||
* yield* finalizer
|
||
* })
|
||
*
|
||
* Effect.runFork(program.pipe(Effect.scoped))
|
||
* // Output:
|
||
* // Acquiring resource
|
||
* // Using resource: 1
|
||
* // Releasing resource
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scoping, Resources & Finalization
|
||
*/
|
||
const withEarlyRelease = exports.withEarlyRelease = fiberRuntime.withEarlyRelease;
|
||
/**
|
||
* Returns a new effect that will not succeed with its value before first
|
||
* waiting for the end of all child fibers forked by the effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const awaitAllChildren = exports.awaitAllChildren = circular.awaitAllChildren;
|
||
/**
|
||
* Returns a new workflow that will not supervise any fibers forked by this
|
||
* workflow.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const daemonChildren = exports.daemonChildren = fiberRuntime.daemonChildren;
|
||
/**
|
||
* Constructs an effect with information about the current `Fiber`.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const descriptor = exports.descriptor = effect.descriptor;
|
||
/**
|
||
* Constructs an effect based on information about the current `Fiber`.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const descriptorWith = exports.descriptorWith = effect.descriptorWith;
|
||
/**
|
||
* Returns a new workflow that executes this one and captures the changes in
|
||
* `FiberRef` values.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const diffFiberRefs = exports.diffFiberRefs = effect.diffFiberRefs;
|
||
/**
|
||
* Acts on the children of this fiber (collected into a single fiber),
|
||
* guaranteeing the specified callback will be invoked, whether or not this
|
||
* effect succeeds.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const ensuringChild = exports.ensuringChild = circular.ensuringChild;
|
||
/**
|
||
* Acts on the children of this fiber, guaranteeing the specified callback
|
||
* will be invoked, whether or not this effect succeeds.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const ensuringChildren = exports.ensuringChildren = circular.ensuringChildren;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const fiberId = exports.fiberId = core.fiberId;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const fiberIdWith = exports.fiberIdWith = core.fiberIdWith;
|
||
/**
|
||
* Creates a new fiber to run an effect concurrently.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function takes an effect and forks it into a separate fiber, allowing it
|
||
* to run concurrently without blocking the original effect. The new fiber
|
||
* starts execution immediately after being created, and the fiber object is
|
||
* returned immediately without waiting for the effect to begin. This is useful
|
||
* when you want to run tasks concurrently while continuing other tasks in the
|
||
* parent fiber.
|
||
*
|
||
* The forked fiber is attached to the parent fiber's scope. This means that
|
||
* when the parent fiber terminates, the child fiber will also be terminated
|
||
* automatically. This feature, known as "auto supervision," ensures that no
|
||
* fibers are left running unintentionally. If you prefer not to have this auto
|
||
* supervision behavior, you can use {@link forkDaemon} or {@link forkIn}.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you need to run an effect concurrently without
|
||
* blocking the current execution flow. For example, you might use it to launch
|
||
* background tasks or concurrent computations. However, working with fibers can
|
||
* be complex, so before using this function directly, you might want to explore
|
||
* higher-level functions like {@link raceWith}, {@link zip}, or others that can
|
||
* manage concurrency for you.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const fib = (n: number): Effect.Effect<number> =>
|
||
* n < 2
|
||
* ? Effect.succeed(n)
|
||
* : Effect.zipWith(fib(n - 1), fib(n - 2), (a, b) => a + b)
|
||
*
|
||
* // ┌─── Effect<RuntimeFiber<number, never>, never, never>
|
||
* // ▼
|
||
* const fib10Fiber = Effect.fork(fib(10))
|
||
* ```
|
||
*
|
||
* @see {@link forkWithErrorHandler} for a version that allows you to handle errors.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const fork = exports.fork = fiberRuntime.fork;
|
||
/**
|
||
* Creates a long-running background fiber that is independent of its parent.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function creates a "daemon" fiber that runs in the background and is not
|
||
* tied to the lifecycle of its parent fiber. Unlike normal fibers that stop
|
||
* when the parent fiber terminates, a daemon fiber will continue running until
|
||
* the global scope closes or the fiber completes naturally. This makes it
|
||
* useful for tasks that need to run in the background independently, such as
|
||
* periodic logging, monitoring, or background data processing.
|
||
*
|
||
* **Example** (Creating a Daemon Fiber)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console, Schedule } from "effect"
|
||
*
|
||
* // Daemon fiber that logs a message repeatedly every second
|
||
* const daemon = Effect.repeat(
|
||
* Console.log("daemon: still running!"),
|
||
* Schedule.fixed("1 second")
|
||
* )
|
||
*
|
||
* const parent = Effect.gen(function* () {
|
||
* console.log("parent: started!")
|
||
* // Daemon fiber running independently
|
||
* yield* Effect.forkDaemon(daemon)
|
||
* yield* Effect.sleep("3 seconds")
|
||
* console.log("parent: finished!")
|
||
* })
|
||
*
|
||
* Effect.runFork(parent)
|
||
* // Output:
|
||
* // parent: started!
|
||
* // daemon: still running!
|
||
* // daemon: still running!
|
||
* // daemon: still running!
|
||
* // parent: finished!
|
||
* // daemon: still running!
|
||
* // daemon: still running!
|
||
* // daemon: still running!
|
||
* // daemon: still running!
|
||
* // daemon: still running!
|
||
* // ...etc...
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const forkDaemon = exports.forkDaemon = fiberRuntime.forkDaemon;
|
||
/**
|
||
* Returns an effect that forks all of the specified values, and returns a
|
||
* composite fiber that produces a list of their results, in order.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const forkAll = exports.forkAll = circular.forkAll;
|
||
/**
|
||
* Forks an effect in a specific scope, allowing finer control over its
|
||
* execution.
|
||
*
|
||
* **Details**
|
||
*
|
||
* There are some cases where we need more fine-grained control, so we want to
|
||
* fork a fiber in a specific scope. We can use the `Effect.forkIn` operator
|
||
* which takes the target scope as an argument.
|
||
*
|
||
* The fiber will be interrupted when the scope is closed.
|
||
*
|
||
* **Example** (Forking a Fiber in a Specific Scope)
|
||
*
|
||
* In this example, the child fiber is forked into the outerScope,
|
||
* allowing it to outlive the inner scope but still be terminated
|
||
* when the outerScope is closed.
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect, Schedule } from "effect"
|
||
*
|
||
* // Child fiber that logs a message repeatedly every second
|
||
* const child = Effect.repeat(
|
||
* Console.log("child: still running!"),
|
||
* Schedule.fixed("1 second")
|
||
* )
|
||
*
|
||
* const program = Effect.scoped(
|
||
* Effect.gen(function* () {
|
||
* yield* Effect.addFinalizer(() =>
|
||
* Console.log("The outer scope is about to be closed!")
|
||
* )
|
||
*
|
||
* // Capture the outer scope
|
||
* const outerScope = yield* Effect.scope
|
||
*
|
||
* // Create an inner scope
|
||
* yield* Effect.scoped(
|
||
* Effect.gen(function* () {
|
||
* yield* Effect.addFinalizer(() =>
|
||
* Console.log("The inner scope is about to be closed!")
|
||
* )
|
||
* // Fork the child fiber in the outer scope
|
||
* yield* Effect.forkIn(child, outerScope)
|
||
* yield* Effect.sleep("3 seconds")
|
||
* })
|
||
* )
|
||
*
|
||
* yield* Effect.sleep("5 seconds")
|
||
* })
|
||
* )
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output:
|
||
* // child: still running!
|
||
* // child: still running!
|
||
* // child: still running!
|
||
* // The inner scope is about to be closed!
|
||
* // child: still running!
|
||
* // child: still running!
|
||
* // child: still running!
|
||
* // child: still running!
|
||
* // child: still running!
|
||
* // child: still running!
|
||
* // The outer scope is about to be closed!
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const forkIn = exports.forkIn = circular.forkIn;
|
||
/**
|
||
* Forks a fiber in a local scope, ensuring it outlives its parent.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function is used to create fibers that are tied to a local scope,
|
||
* meaning they are not dependent on their parent fiber's lifecycle. Instead,
|
||
* they will continue running until the scope they were created in is closed.
|
||
* This is particularly useful when you need a fiber to run independently of the
|
||
* parent fiber, but still want it to be terminated when the scope ends.
|
||
*
|
||
* Fibers created with this function are isolated from the parent fiber’s
|
||
* termination, so they can run for a longer period. This behavior is different
|
||
* from fibers created with {@link fork}, which are terminated when the parent fiber
|
||
* terminates. With `forkScoped`, the child fiber will keep running until the
|
||
* local scope ends, regardless of the state of the parent fiber.
|
||
*
|
||
* **Example** (Forking a Fiber in a Local Scope)
|
||
*
|
||
* In this example, the child fiber continues to run beyond the lifetime of the parent fiber.
|
||
* The child fiber is tied to the local scope and will be terminated only when the scope ends.
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console, Schedule } from "effect"
|
||
*
|
||
* // Child fiber that logs a message repeatedly every second
|
||
* const child = Effect.repeat(
|
||
* Console.log("child: still running!"),
|
||
* Schedule.fixed("1 second")
|
||
* )
|
||
*
|
||
* // ┌─── Effect<void, never, Scope>
|
||
* // ▼
|
||
* const parent = Effect.gen(function* () {
|
||
* console.log("parent: started!")
|
||
* // Child fiber attached to local scope
|
||
* yield* Effect.forkScoped(child)
|
||
* yield* Effect.sleep("3 seconds")
|
||
* console.log("parent: finished!")
|
||
* })
|
||
*
|
||
* // Program runs within a local scope
|
||
* const program = Effect.scoped(
|
||
* Effect.gen(function* () {
|
||
* console.log("Local scope started!")
|
||
* yield* Effect.fork(parent)
|
||
* // Scope lasts for 5 seconds
|
||
* yield* Effect.sleep("5 seconds")
|
||
* console.log("Leaving the local scope!")
|
||
* })
|
||
* )
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output:
|
||
* // Local scope started!
|
||
* // parent: started!
|
||
* // child: still running!
|
||
* // child: still running!
|
||
* // child: still running!
|
||
* // parent: finished!
|
||
* // child: still running!
|
||
* // child: still running!
|
||
* // Leaving the local scope!
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const forkScoped = exports.forkScoped = circular.forkScoped;
|
||
/**
|
||
* Like {@link fork} but handles an error with the provided handler.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const forkWithErrorHandler = exports.forkWithErrorHandler = fiberRuntime.forkWithErrorHandler;
|
||
/**
|
||
* Creates an `Effect` value that represents the exit value of the specified
|
||
* fiber.
|
||
*
|
||
* @see {@link fromFiberEffect} for creating an effect from a fiber obtained from an effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const fromFiber = exports.fromFiber = circular.fromFiber;
|
||
/**
|
||
* Creates an `Effect` value that represents the exit value of a fiber obtained
|
||
* from an effect.
|
||
*
|
||
* @see {@link fromFiber} for creating an effect from a fiber.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const fromFiberEffect = exports.fromFiberEffect = circular.fromFiberEffect;
|
||
/**
|
||
* Supervises child fibers by reporting them to a specified supervisor.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function takes a supervisor as an argument and returns an effect where
|
||
* all child fibers forked within it are supervised by the provided supervisor.
|
||
* This enables you to capture detailed information about these child fibers,
|
||
* such as their status, through the supervisor.
|
||
*
|
||
* **Example** (Monitoring Fiber Count)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Supervisor, Schedule, Fiber, FiberStatus } from "effect"
|
||
*
|
||
* // Main program that monitors fibers while calculating a Fibonacci number
|
||
* const program = Effect.gen(function* () {
|
||
* // Create a supervisor to track child fibers
|
||
* const supervisor = yield* Supervisor.track
|
||
*
|
||
* // Start a Fibonacci calculation, supervised by the supervisor
|
||
* const fibFiber = yield* fib(20).pipe(
|
||
* Effect.supervised(supervisor),
|
||
* // Fork the Fibonacci effect into a fiber
|
||
* Effect.fork
|
||
* )
|
||
*
|
||
* // Define a schedule to periodically monitor the fiber count every 500ms
|
||
* const policy = Schedule.spaced("500 millis").pipe(
|
||
* Schedule.whileInputEffect((_) =>
|
||
* Fiber.status(fibFiber).pipe(
|
||
* // Continue while the Fibonacci fiber is not done
|
||
* Effect.andThen((status) => status !== FiberStatus.done)
|
||
* )
|
||
* )
|
||
* )
|
||
*
|
||
* // Start monitoring the fibers, using the supervisor to track the count
|
||
* const monitorFiber = yield* monitorFibers(supervisor).pipe(
|
||
* // Repeat the monitoring according to the schedule
|
||
* Effect.repeat(policy),
|
||
* // Fork the monitoring into its own fiber
|
||
* Effect.fork
|
||
* )
|
||
*
|
||
* // Join the monitor and Fibonacci fibers to ensure they complete
|
||
* yield* Fiber.join(monitorFiber)
|
||
* const result = yield* Fiber.join(fibFiber)
|
||
*
|
||
* console.log(`fibonacci result: ${result}`)
|
||
* })
|
||
*
|
||
* // Function to monitor and log the number of active fibers
|
||
* const monitorFibers = (
|
||
* supervisor: Supervisor.Supervisor<Array<Fiber.RuntimeFiber<any, any>>>
|
||
* ): Effect.Effect<void> =>
|
||
* Effect.gen(function* () {
|
||
* const fibers = yield* supervisor.value // Get the current set of fibers
|
||
* console.log(`number of fibers: ${fibers.length}`)
|
||
* })
|
||
*
|
||
* // Recursive Fibonacci calculation, spawning fibers for each recursive step
|
||
* const fib = (n: number): Effect.Effect<number> =>
|
||
* Effect.gen(function* () {
|
||
* if (n <= 1) {
|
||
* return 1
|
||
* }
|
||
* yield* Effect.sleep("500 millis") // Simulate work by delaying
|
||
*
|
||
* // Fork two fibers for the recursive Fibonacci calls
|
||
* const fiber1 = yield* Effect.fork(fib(n - 2))
|
||
* const fiber2 = yield* Effect.fork(fib(n - 1))
|
||
*
|
||
* // Join the fibers to retrieve their results
|
||
* const v1 = yield* Fiber.join(fiber1)
|
||
* const v2 = yield* Fiber.join(fiber2)
|
||
*
|
||
* return v1 + v2 // Combine the results
|
||
* })
|
||
*
|
||
* Effect.runPromise(program)
|
||
* // Output:
|
||
* // number of fibers: 0
|
||
* // number of fibers: 2
|
||
* // number of fibers: 6
|
||
* // number of fibers: 14
|
||
* // number of fibers: 30
|
||
* // number of fibers: 62
|
||
* // number of fibers: 126
|
||
* // number of fibers: 254
|
||
* // number of fibers: 510
|
||
* // number of fibers: 1022
|
||
* // number of fibers: 2034
|
||
* // number of fibers: 3795
|
||
* // number of fibers: 5810
|
||
* // number of fibers: 6474
|
||
* // number of fibers: 4942
|
||
* // number of fibers: 2515
|
||
* // number of fibers: 832
|
||
* // number of fibers: 170
|
||
* // number of fibers: 18
|
||
* // number of fibers: 0
|
||
* // fibonacci result: 10946
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const supervised = exports.supervised = circular.supervised;
|
||
/**
|
||
* Transplants specified effects so that when those effects fork other
|
||
* effects, the forked effects will be governed by the scope of the fiber that
|
||
* executes this effect.
|
||
*
|
||
* This can be used to "graft" deep grandchildren onto a higher-level scope,
|
||
* effectively extending their lifespans into the parent scope.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const transplant = exports.transplant = core.transplant;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Supervision & Fibers
|
||
*/
|
||
const withConcurrency = exports.withConcurrency = core.withConcurrency;
|
||
/**
|
||
* Sets the provided scheduler for usage in the wrapped effect
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scheduler
|
||
*/
|
||
const withScheduler = exports.withScheduler = Scheduler.withScheduler;
|
||
/**
|
||
* Sets the scheduling priority used when yielding
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scheduler
|
||
*/
|
||
const withSchedulingPriority = exports.withSchedulingPriority = core.withSchedulingPriority;
|
||
/**
|
||
* Sets the maximum number of operations before yield by the default schedulers
|
||
*
|
||
* @since 2.0.0
|
||
* @category Scheduler
|
||
*/
|
||
const withMaxOpsBeforeYield = exports.withMaxOpsBeforeYield = core.withMaxOpsBeforeYield;
|
||
/**
|
||
* Retrieves the `Clock` service from the context.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* const clock = yield* Effect.clock
|
||
* const currentTime = yield* clock.currentTimeMillis
|
||
* console.log(`Current time in milliseconds: ${currentTime}`)
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Example Output:
|
||
* // Current time in milliseconds: 1735484796134
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Clock
|
||
*/
|
||
const clock = exports.clock = effect.clock;
|
||
/**
|
||
* Retrieves the `Clock` service from the context and provides it to the
|
||
* specified effectful function.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* const program = Effect.clockWith((clock) =>
|
||
* clock.currentTimeMillis.pipe(
|
||
* Effect.map((currentTime) => `Current time is: ${currentTime}`),
|
||
* Effect.tap(Console.log)
|
||
* )
|
||
* )
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Example Output:
|
||
* // Current time is: 1735484929744
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Clock
|
||
*/
|
||
const clockWith = exports.clockWith = effect.clockWith;
|
||
/**
|
||
* Sets the implementation of the `Clock` service to the specified value and
|
||
* restores it to its original value when the scope is closed.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Clock
|
||
*/
|
||
const withClockScoped = exports.withClockScoped = fiberRuntime.withClockScoped;
|
||
/**
|
||
* Executes the specified workflow with the specified implementation of the
|
||
* `Clock` service.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Clock
|
||
*/
|
||
const withClock = exports.withClock = defaultServices.withClock;
|
||
/**
|
||
* Retreives the `Console` service from the context
|
||
*
|
||
* @since 2.0.0
|
||
* @category Console
|
||
*/
|
||
const console = exports.console = console_.console;
|
||
/**
|
||
* Retreives the `Console` service from the context and provides it to the
|
||
* specified effectful function.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Console
|
||
*/
|
||
const consoleWith = exports.consoleWith = console_.consoleWith;
|
||
/**
|
||
* Sets the implementation of the console service to the specified value and
|
||
* restores it to its original value when the scope is closed.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Creating Effects
|
||
*/
|
||
const withConsoleScoped = exports.withConsoleScoped = console_.withConsoleScoped;
|
||
/**
|
||
* Executes the specified workflow with the specified implementation of the
|
||
* console service.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Console
|
||
*/
|
||
const withConsole = exports.withConsole = console_.withConsole;
|
||
/**
|
||
* Delays the execution of an effect by a specified `Duration`.
|
||
*
|
||
* **Details
|
||
*
|
||
* This function postpones the execution of the provided effect by the specified
|
||
* duration. The duration can be provided in various formats supported by the
|
||
* `Duration` module.
|
||
*
|
||
* Internally, this function does not block the thread; instead, it uses an
|
||
* efficient, non-blocking mechanism to introduce the delay.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* const task = Console.log("Task executed")
|
||
*
|
||
* const program = Console.log("start").pipe(
|
||
* Effect.andThen(
|
||
* // Delays the log message by 2 seconds
|
||
* task.pipe(Effect.delay("2 seconds"))
|
||
* )
|
||
* )
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output:
|
||
* // start
|
||
* // Task executed
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Delays & Timeouts
|
||
*/
|
||
const delay = exports.delay = effect.delay;
|
||
/**
|
||
* Suspends the execution of an effect for a specified `Duration`.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function pauses the execution of an effect for a given duration. It is
|
||
* asynchronous, meaning that it does not block the fiber executing the effect.
|
||
* Instead, the fiber is suspended during the delay period and can resume once
|
||
* the specified time has passed.
|
||
*
|
||
* The duration can be specified using various formats supported by the
|
||
* `Duration` module, such as a string (`"2 seconds"`) or numeric value
|
||
* representing milliseconds.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* console.log("Starting task...")
|
||
* yield* Effect.sleep("3 seconds") // Waits for 3 seconds
|
||
* console.log("Task completed!")
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output:
|
||
* // Starting task...
|
||
* // Task completed!
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Delays & Timeouts
|
||
*/
|
||
const sleep = exports.sleep = effect.sleep;
|
||
/**
|
||
* Executes an effect and measures the time it takes to complete.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function wraps the provided effect and returns a new effect that, when
|
||
* executed, performs the original effect and calculates its execution duration.
|
||
*
|
||
* The result of the new effect includes both the execution time (as a
|
||
* `Duration`) and the original effect's result. This is useful for monitoring
|
||
* performance or gaining insights into the time taken by specific operations.
|
||
*
|
||
* The original effect's behavior (success, failure, or interruption) remains
|
||
* unchanged, and the timing information is provided alongside the result in a
|
||
* tuple.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Duration, Effect } from "effect"
|
||
*
|
||
* const task = Effect.gen(function*() {
|
||
* yield* Effect.sleep("2 seconds") // Simulates some work
|
||
* return "some result"
|
||
* })
|
||
*
|
||
* const timedTask = task.pipe(Effect.timed)
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* const [duration, result] = yield* timedTask
|
||
* console.log(`Task completed in ${Duration.toMillis(duration)} ms with result: ${result}`)
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output: Task completed in 2003.749125 ms with result: some result
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Delays & Timeouts
|
||
*/
|
||
const timed = exports.timed = effect.timed;
|
||
/**
|
||
* Executes an effect and measures its execution time using a custom clock.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function extends the functionality of {@link timed} by allowing you to
|
||
* specify a custom clock for measuring the execution duration. The provided
|
||
* effect (`nanoseconds`) represents the clock and should return the current
|
||
* time in nanoseconds. The timing information is computed using this custom
|
||
* clock instead of the default system clock.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Delays & Timeouts
|
||
*/
|
||
const timedWith = exports.timedWith = effect.timedWith;
|
||
/**
|
||
* Adds a time limit to an effect, triggering a timeout if the effect exceeds
|
||
* the duration.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to enforce a time limit on the execution of an
|
||
* effect. If the effect does not complete within the given duration, it fails
|
||
* with a `TimeoutException`. This is useful for preventing tasks from hanging
|
||
* indefinitely, especially in scenarios where responsiveness or resource limits
|
||
* are critical.
|
||
*
|
||
* The returned effect will either:
|
||
* - Succeed with the original effect's result if it completes within the
|
||
* specified duration.
|
||
* - Fail with a `TimeoutException` if the time limit is exceeded.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const task = Effect.gen(function* () {
|
||
* console.log("Start processing...")
|
||
* yield* Effect.sleep("2 seconds") // Simulates a delay in processing
|
||
* console.log("Processing complete.")
|
||
* return "Result"
|
||
* })
|
||
*
|
||
* // Output will show a TimeoutException as the task takes longer
|
||
* // than the specified timeout duration
|
||
* const timedEffect = task.pipe(Effect.timeout("1 second"))
|
||
*
|
||
* Effect.runPromiseExit(timedEffect).then(console.log)
|
||
* // Output:
|
||
* // Start processing...
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: {
|
||
* // _id: 'Cause',
|
||
* // _tag: 'Fail',
|
||
* // failure: { _tag: 'TimeoutException' }
|
||
* // }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @see {@link timeoutFail} for a version that raises a custom error.
|
||
* @see {@link timeoutFailCause} for a version that raises a custom defect.
|
||
* @see {@link timeoutTo} for a version that allows specifying both success and
|
||
* timeout handlers.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Delays & Timeouts
|
||
*/
|
||
const timeout = exports.timeout = circular.timeout;
|
||
/**
|
||
* Gracefully handles timeouts by returning an `Option` that represents either
|
||
* the result or a timeout.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function wraps the outcome of an effect in an `Option` type. If the
|
||
* effect completes within the specified duration, it returns a `Some`
|
||
* containing the result. If the effect times out, it returns a `None`. Unlike
|
||
* other timeout methods, this approach does not raise errors or exceptions;
|
||
* instead, it allows you to treat timeouts as a regular outcome, simplifying
|
||
* the logic for handling delays.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful when you want to handle timeouts without causing the program
|
||
* to fail, making it easier to manage situations where you expect tasks might
|
||
* take too long but want to continue executing other tasks.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const task = Effect.gen(function* () {
|
||
* console.log("Start processing...")
|
||
* yield* Effect.sleep("2 seconds") // Simulates a delay in processing
|
||
* console.log("Processing complete.")
|
||
* return "Result"
|
||
* })
|
||
*
|
||
* const timedOutEffect = Effect.all([
|
||
* task.pipe(Effect.timeoutOption("3 seconds")),
|
||
* task.pipe(Effect.timeoutOption("1 second"))
|
||
* ])
|
||
*
|
||
* Effect.runPromise(timedOutEffect).then(console.log)
|
||
* // Output:
|
||
* // Start processing...
|
||
* // Processing complete.
|
||
* // Start processing...
|
||
* // [
|
||
* // { _id: 'Option', _tag: 'Some', value: 'Result' },
|
||
* // { _id: 'Option', _tag: 'None' }
|
||
* // ]
|
||
* ```
|
||
*
|
||
* @see {@link timeout} for a version that raises a `TimeoutException`.
|
||
* @see {@link timeoutFail} for a version that raises a custom error.
|
||
* @see {@link timeoutFailCause} for a version that raises a custom defect.
|
||
* @see {@link timeoutTo} for a version that allows specifying both success and
|
||
* timeout handlers.
|
||
*
|
||
* @since 3.1.0
|
||
* @category Delays & Timeouts
|
||
*/
|
||
const timeoutOption = exports.timeoutOption = circular.timeoutOption;
|
||
/**
|
||
* Specifies a custom error to be produced when a timeout occurs.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to handle timeouts in a customized way by defining a
|
||
* specific error to be raised when an effect exceeds the given duration. Unlike
|
||
* default timeout behaviors that use generic exceptions, this function gives
|
||
* you the flexibility to specify a meaningful error type that aligns with your
|
||
* application's needs.
|
||
*
|
||
* When you apply this function, you provide:
|
||
* - A `duration`: The time limit for the effect.
|
||
* - An `onTimeout` function: A lazy evaluation function that generates the
|
||
* custom error if the timeout occurs.
|
||
*
|
||
* If the effect completes within the time limit, its result is returned
|
||
* normally. Otherwise, the `onTimeout` function is triggered, and its output is
|
||
* used as the error for the effect.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const task = Effect.gen(function* () {
|
||
* console.log("Start processing...")
|
||
* yield* Effect.sleep("2 seconds") // Simulates a delay in processing
|
||
* console.log("Processing complete.")
|
||
* return "Result"
|
||
* })
|
||
*
|
||
* class MyTimeoutError {
|
||
* readonly _tag = "MyTimeoutError"
|
||
* }
|
||
*
|
||
* const program = task.pipe(
|
||
* Effect.timeoutFail({
|
||
* duration: "1 second",
|
||
* onTimeout: () => new MyTimeoutError() // Custom timeout error
|
||
* })
|
||
* )
|
||
*
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // Start processing...
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: {
|
||
* // _id: 'Cause',
|
||
* // _tag: 'Fail',
|
||
* // failure: MyTimeoutError { _tag: 'MyTimeoutError' }
|
||
* // }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @see {@link timeout} for a version that raises a `TimeoutException`.
|
||
* @see {@link timeoutFailCause} for a version that raises a custom defect.
|
||
* @see {@link timeoutTo} for a version that allows specifying both success and
|
||
* timeout handlers.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Delays & Timeouts
|
||
*/
|
||
const timeoutFail = exports.timeoutFail = circular.timeoutFail;
|
||
/**
|
||
* Specifies a custom defect to be thrown when a timeout occurs.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to handle timeouts as exceptional cases by
|
||
* generating a custom defect when an effect exceeds the specified duration. You
|
||
* provide:
|
||
* - A `duration`: The time limit for the effect.
|
||
* - An `onTimeout` function: A lazy evaluation function that generates the
|
||
* custom defect (typically created using `Cause.die`).
|
||
*
|
||
* If the effect completes within the time limit, its result is returned
|
||
* normally. Otherwise, the custom defect is triggered, and the effect fails
|
||
* with that defect.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is especially useful when you need to treat timeouts as critical
|
||
* failures in your application and wish to include meaningful information in
|
||
* the defect.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Cause } from "effect"
|
||
*
|
||
* const task = Effect.gen(function* () {
|
||
* console.log("Start processing...")
|
||
* yield* Effect.sleep("2 seconds") // Simulates a delay in processing
|
||
* console.log("Processing complete.")
|
||
* return "Result"
|
||
* })
|
||
*
|
||
* const program = task.pipe(
|
||
* Effect.timeoutFailCause({
|
||
* duration: "1 second",
|
||
* onTimeout: () => Cause.die("Timed out!") // Custom defect for timeout
|
||
* })
|
||
* )
|
||
*
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // Start processing...
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: { _id: 'Cause', _tag: 'Die', defect: 'Timed out!' }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @see {@link timeout} for a version that raises a `TimeoutException`.
|
||
* @see {@link timeoutFail} for a version that raises a custom error.
|
||
* @see {@link timeoutTo} for a version that allows specifying both success and
|
||
* timeout handlers.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Delays & Timeouts
|
||
*/
|
||
const timeoutFailCause = exports.timeoutFailCause = circular.timeoutFailCause;
|
||
/**
|
||
* Provides custom behavior for successful and timed-out operations.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to define distinct outcomes for an effect depending
|
||
* on whether it completes within a specified time frame or exceeds the timeout
|
||
* duration. You can provide:
|
||
* - `onSuccess`: A handler for processing the result of the effect if it
|
||
* completes successfully within the time limit.
|
||
* - `onTimeout`: A handler for generating a result when the effect times out.
|
||
* - `duration`: The maximum allowed time for the effect to complete.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Unlike {@link timeout}, which raises an exception for timeouts, this function
|
||
* gives you full control over the behavior for both success and timeout
|
||
* scenarios. It is particularly useful when you want to encapsulate timeouts
|
||
* and successes into a specific data structure, like an `Either` type, to
|
||
* represent these outcomes in a meaningful way.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Either } from "effect"
|
||
*
|
||
* const task = Effect.gen(function* () {
|
||
* console.log("Start processing...")
|
||
* yield* Effect.sleep("2 seconds") // Simulates a delay in processing
|
||
* console.log("Processing complete.")
|
||
* return "Result"
|
||
* })
|
||
*
|
||
* const program = task.pipe(
|
||
* Effect.timeoutTo({
|
||
* duration: "1 second",
|
||
* onSuccess: (result): Either.Either<string, string> =>
|
||
* Either.right(result),
|
||
* onTimeout: (): Either.Either<string, string> =>
|
||
* Either.left("Timed out!")
|
||
* })
|
||
* )
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output:
|
||
* // Start processing...
|
||
* // {
|
||
* // _id: "Either",
|
||
* // _tag: "Left",
|
||
* // left: "Timed out!"
|
||
* // }
|
||
* ```
|
||
*
|
||
* @see {@link timeout} for a version that raises a `TimeoutException`.
|
||
* @see {@link timeoutFail} for a version that raises a custom error.
|
||
* @see {@link timeoutFailCause} for a version that raises a custom defect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Delays & Timeouts
|
||
*/
|
||
const timeoutTo = exports.timeoutTo = circular.timeoutTo;
|
||
/**
|
||
* Allows working with the default configuration provider.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function retrieves the default configuration provider and passes it to
|
||
* the provided function, which can use it to perform computations or retrieve
|
||
* configuration values. The function can return an effect that leverages the
|
||
* configuration provider for its operations.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Config
|
||
*/
|
||
const configProviderWith = exports.configProviderWith = defaultServices.configProviderWith;
|
||
/**
|
||
* Executes an effect using a specific configuration provider.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function lets you run an effect with a specified configuration provider.
|
||
* The custom provider will override the default configuration provider for the
|
||
* duration of the effect's execution.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is particularly useful when you need to use a different set of
|
||
* configuration values or sources for specific parts of your application.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Config, ConfigProvider, Effect } from "effect"
|
||
*
|
||
* const customProvider: ConfigProvider.ConfigProvider = ConfigProvider.fromMap(
|
||
* new Map([["custom-key", "custom-value"]])
|
||
* )
|
||
*
|
||
* const program = Effect.withConfigProvider(customProvider)(
|
||
* Effect.gen(function*() {
|
||
* const value = yield* Config.string("custom-key")
|
||
* console.log(`Config value: ${value}`)
|
||
* })
|
||
* )
|
||
*
|
||
* Effect.runPromise(program)
|
||
* // Output:
|
||
* // Config value: custom-value
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Config
|
||
*/
|
||
const withConfigProvider = exports.withConfigProvider = defaultServices.withConfigProvider;
|
||
/**
|
||
* Sets a configuration provider within a scope.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function sets the configuration provider to a specified value and
|
||
* ensures that it is restored to its original value when the scope is closed.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Config
|
||
*/
|
||
const withConfigProviderScoped = exports.withConfigProviderScoped = fiberRuntime.withConfigProviderScoped;
|
||
/**
|
||
* Accesses the full context of the effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function provides the ability to access the entire context required by
|
||
* an effect. The context is a container that holds dependencies or environment
|
||
* values needed by an effect to run. By using this function, you can retrieve
|
||
* and work with the context directly within an effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const context = exports.context = core.context;
|
||
/**
|
||
* Accesses the context and applies a transformation function.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function retrieves the context of the effect and applies a pure
|
||
* transformation function to it. The result of the transformation is then
|
||
* returned within the effect.
|
||
*
|
||
* @see {@link contextWithEffect} for a version that allows effectful transformations.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const contextWith = exports.contextWith = effect.contextWith;
|
||
/**
|
||
* Accesses the context and performs an effectful transformation.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function retrieves the context and allows you to transform it
|
||
* effectually using another effect. It is useful when the transformation
|
||
* involves asynchronous or effectful operations.
|
||
*
|
||
* @see {@link contextWith} for a version that allows pure transformations.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const contextWithEffect = exports.contextWithEffect = core.contextWithEffect;
|
||
/**
|
||
* Provides part of the required context while leaving the rest unchanged.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to transform the context required by an effect,
|
||
* providing part of the context and leaving the rest to be fulfilled later.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Context, Effect } from "effect"
|
||
*
|
||
* class Service1 extends Context.Tag("Service1")<Service1, { readonly port: number }>() {}
|
||
* class Service2 extends Context.Tag("Service2")<Service2, { readonly connection: string }>() {}
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* const service1 = yield* Service1
|
||
* console.log(service1.port)
|
||
* const service2 = yield* Service2
|
||
* console.log(service2.connection)
|
||
* return "some result"
|
||
* })
|
||
*
|
||
* // ┌─── Effect<string, never, Service2>
|
||
* // ▼
|
||
* const programWithService1 = Effect.mapInputContext(
|
||
* program,
|
||
* (ctx: Context.Context<Service2>) => Context.add(ctx, Service1, { port: 3000 })
|
||
* )
|
||
*
|
||
* const runnable = programWithService1.pipe(
|
||
* Effect.provideService(Service2, { connection: "localhost" }),
|
||
* Effect.provideService(Service1, { port: 3001 })
|
||
* )
|
||
*
|
||
* Effect.runPromise(runnable)
|
||
* // Output:
|
||
* // 3000
|
||
* // localhost
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const mapInputContext = exports.mapInputContext = core.mapInputContext;
|
||
/**
|
||
* Provides necessary dependencies to an effect, removing its environmental
|
||
* requirements.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to supply the required environment for an effect.
|
||
* The environment can be provided in the form of one or more `Layer`s, a
|
||
* `Context`, a `Runtime`, or a `ManagedRuntime`. Once the environment is
|
||
* provided, the effect can run without requiring external dependencies.
|
||
*
|
||
* You can compose layers to create a modular and reusable way of setting up the
|
||
* environment for effects. For example, layers can be used to configure
|
||
* databases, logging services, or any other required dependencies.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Context, Effect, Layer } from "effect"
|
||
*
|
||
* class Database extends Context.Tag("Database")<
|
||
* Database,
|
||
* { readonly query: (sql: string) => Effect.Effect<Array<unknown>> }
|
||
* >() {}
|
||
*
|
||
* const DatabaseLive = Layer.succeed(
|
||
* Database,
|
||
* {
|
||
* // Simulate a database query
|
||
* query: (sql: string) => Effect.log(`Executing query: ${sql}`).pipe(Effect.as([]))
|
||
* }
|
||
* )
|
||
*
|
||
* // ┌─── Effect<unknown[], never, Database>
|
||
* // ▼
|
||
* const program = Effect.gen(function*() {
|
||
* const database = yield* Database
|
||
* const result = yield* database.query("SELECT * FROM users")
|
||
* return result
|
||
* })
|
||
*
|
||
* // ┌─── Effect<unknown[], never, never>
|
||
* // ▼
|
||
* const runnable = Effect.provide(program, DatabaseLive)
|
||
*
|
||
* Effect.runPromise(runnable).then(console.log)
|
||
* // Output:
|
||
* // timestamp=... level=INFO fiber=#0 message="Executing query: SELECT * FROM users"
|
||
* // []
|
||
* ```
|
||
*
|
||
* @see {@link provideService} for providing a service to an effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const provide = exports.provide = layer.effect_provide;
|
||
/**
|
||
* Provides an implementation for a service in the context of an effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to supply a specific implementation for a service
|
||
* required by an effect. Services are typically defined using `Context.Tag`,
|
||
* which acts as a unique identifier for the service. By using this function,
|
||
* you link the service to its concrete implementation, enabling the effect to
|
||
* execute successfully without additional requirements.
|
||
*
|
||
* For example, you can use this function to provide a random number generator,
|
||
* a logger, or any other service your effect depends on. Once the service is
|
||
* provided, all parts of the effect that rely on the service will automatically
|
||
* use the implementation you supplied.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Context } from "effect"
|
||
*
|
||
* // Declaring a tag for a service that generates random numbers
|
||
* class Random extends Context.Tag("MyRandomService")<
|
||
* Random,
|
||
* { readonly next: Effect.Effect<number> }
|
||
* >() {}
|
||
*
|
||
* // Using the service
|
||
* const program = Effect.gen(function* () {
|
||
* const random = yield* Random
|
||
* const randomNumber = yield* random.next
|
||
* console.log(`random number: ${randomNumber}`)
|
||
* })
|
||
*
|
||
* // Providing the implementation
|
||
* //
|
||
* // ┌─── Effect<void, never, never>
|
||
* // ▼
|
||
* const runnable = Effect.provideService(program, Random, {
|
||
* next: Effect.sync(() => Math.random())
|
||
* })
|
||
*
|
||
* // Run successfully
|
||
* Effect.runPromise(runnable)
|
||
* // Example Output:
|
||
* // random number: 0.8241872233134417
|
||
* ```
|
||
*
|
||
* @see {@link provide} for providing multiple layers to an effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const provideService = exports.provideService = effect.provideService;
|
||
/**
|
||
* Dynamically provides an implementation for a service using an effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to provide an implementation for a service
|
||
* dynamically by using another effect. The provided effect is executed to
|
||
* produce the service implementation, which is then made available to the
|
||
* consuming effect. This is particularly useful when the service implementation
|
||
* itself requires asynchronous or resource-intensive initialization.
|
||
*
|
||
* For example, you can use this function to lazily initialize a database
|
||
* connection or fetch configuration values from an external source before
|
||
* making the service available to your effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const provideServiceEffect = exports.provideServiceEffect = effect.provideServiceEffect;
|
||
/**
|
||
* Creates a function that uses a service from the context to produce a value.
|
||
*
|
||
* @see {@link serviceFunctionEffect} for a version that returns an effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const serviceFunction = exports.serviceFunction = effect.serviceFunction;
|
||
/**
|
||
* Creates a function that uses a service from the context to produce an effect.
|
||
*
|
||
* @see {@link serviceFunction} for a version that returns a value.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const serviceFunctionEffect = exports.serviceFunctionEffect = effect.serviceFunctionEffect;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const serviceFunctions = exports.serviceFunctions = effect.serviceFunctions;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const serviceConstants = exports.serviceConstants = effect.serviceConstants;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const serviceMembers = exports.serviceMembers = effect.serviceMembers;
|
||
/**
|
||
* Retrieves an optional service from the context as an `Option`.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function retrieves a service from the context and wraps it in an
|
||
* `Option`. If the service is available, it returns a `Some` containing the
|
||
* service. If the service is not found, it returns a `None`. This approach is
|
||
* useful when you want to handle the absence of a service gracefully without
|
||
* causing an error.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when:
|
||
* - You need to access a service that may or may not be present in the context.
|
||
* - You want to handle the absence of a service using the `Option` type instead
|
||
* of throwing an error.
|
||
*
|
||
* @see {@link serviceOptional} for a version that throws an error if the service is missing.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const serviceOption = exports.serviceOption = effect.serviceOption;
|
||
/**
|
||
* Retrieves a service from the context, throwing an error if it is missing.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function retrieves a required service from the context. If the service
|
||
* is available, it returns the service. If the service is missing, it throws a
|
||
* `NoSuchElementException`, which can be handled using Effect's error-handling
|
||
* mechanisms. This is useful for services that are critical to the execution of
|
||
* your effect.
|
||
*
|
||
* @see {@link serviceOption} for a version that returns an `Option` instead of throwing an error.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const serviceOptional = exports.serviceOptional = effect.serviceOptional;
|
||
/**
|
||
* Updates a service in the context with a new implementation.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function modifies the existing implementation of a service in the
|
||
* context. It retrieves the current service, applies the provided
|
||
* transformation function `f`, and replaces the old service with the
|
||
* transformed one.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful for adapting or extending a service's behavior during the
|
||
* execution of an effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const updateService = exports.updateService = effect.updateService;
|
||
/**
|
||
* The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
|
||
*
|
||
* Here's how the do simulation works:
|
||
*
|
||
* 1. Start the do simulation using the `Do` value
|
||
* 2. Within the do simulation scope, you can use the `bind` function to define variables and bind them to `Effect` values
|
||
* 3. You can accumulate multiple `bind` statements to define multiple variables within the scope
|
||
* 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import * as assert from "node:assert"
|
||
* import { Effect, pipe } from "effect"
|
||
*
|
||
* const result = pipe(
|
||
* Effect.Do,
|
||
* Effect.bind("x", () => Effect.succeed(2)),
|
||
* Effect.bind("y", () => Effect.succeed(3)),
|
||
* Effect.let("sum", ({ x, y }) => x + y)
|
||
* )
|
||
* assert.deepStrictEqual(Effect.runSync(result), { x: 2, y: 3, sum: 5 })
|
||
* ```
|
||
*
|
||
* @see {@link bind}
|
||
* @see {@link bindTo}
|
||
* @see {@link let_ let}
|
||
*
|
||
* @category Do notation
|
||
* @since 2.0.0
|
||
*/
|
||
const Do = exports.Do = effect.Do;
|
||
/**
|
||
* The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
|
||
*
|
||
* Here's how the do simulation works:
|
||
*
|
||
* 1. Start the do simulation using the `Do` value
|
||
* 2. Within the do simulation scope, you can use the `bind` function to define variables and bind them to `Effect` values
|
||
* 3. You can accumulate multiple `bind` statements to define multiple variables within the scope
|
||
* 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import * as assert from "node:assert"
|
||
* import { Effect, pipe } from "effect"
|
||
*
|
||
* const result = pipe(
|
||
* Effect.Do,
|
||
* Effect.bind("x", () => Effect.succeed(2)),
|
||
* Effect.bind("y", () => Effect.succeed(3)),
|
||
* Effect.let("sum", ({ x, y }) => x + y)
|
||
* )
|
||
* assert.deepStrictEqual(Effect.runSync(result), { x: 2, y: 3, sum: 5 })
|
||
* ```
|
||
*
|
||
* @see {@link Do}
|
||
* @see {@link bindTo}
|
||
* @see {@link let_ let}
|
||
*
|
||
* @category Do notation
|
||
* @since 2.0.0
|
||
*/
|
||
const bind = exports.bind = effect.bind;
|
||
/**
|
||
* `bindAll` combines `all` with `bind`. It is useful
|
||
* when you want to concurrently run multiple effects and then combine their
|
||
* results in a Do notation pipeline.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import * as assert from "node:assert"
|
||
* import { Effect, Either, pipe } from "effect"
|
||
*
|
||
* const result = pipe(
|
||
* Effect.Do,
|
||
* Effect.bind("x", () => Effect.succeed(2)),
|
||
* Effect.bindAll(({ x }) => ({
|
||
* a: Effect.succeed(x),
|
||
* b: Effect.fail("oops"),
|
||
* }), { concurrency: 2, mode: "either" })
|
||
* )
|
||
* assert.deepStrictEqual(Effect.runSync(result), { x: 2, a: Either.right(2), b: Either.left("oops") })
|
||
* ```
|
||
*
|
||
* @category Do notation
|
||
* @since 3.7.0
|
||
*/
|
||
const bindAll = exports.bindAll = circular.bindAll;
|
||
/**
|
||
* The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
|
||
*
|
||
* Here's how the do simulation works:
|
||
*
|
||
* 1. Start the do simulation using the `Do` value
|
||
* 2. Within the do simulation scope, you can use the `bind` function to define variables and bind them to `Effect` values
|
||
* 3. You can accumulate multiple `bind` statements to define multiple variables within the scope
|
||
* 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import * as assert from "node:assert"
|
||
* import { Effect, pipe } from "effect"
|
||
*
|
||
* const result = pipe(
|
||
* Effect.Do,
|
||
* Effect.bind("x", () => Effect.succeed(2)),
|
||
* Effect.bind("y", () => Effect.succeed(3)),
|
||
* Effect.let("sum", ({ x, y }) => x + y)
|
||
* )
|
||
* assert.deepStrictEqual(Effect.runSync(result), { x: 2, y: 3, sum: 5 })
|
||
* ```
|
||
*
|
||
* @see {@link Do}
|
||
* @see {@link bind}
|
||
* @see {@link let_ let}
|
||
*
|
||
* @category Do notation
|
||
* @since 2.0.0
|
||
*/
|
||
const bindTo = exports.bindTo = effect.bindTo;
|
||
const let_ = exports.let = effect.let_;
|
||
/**
|
||
* Encapsulates the result of an effect in an `Option`.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function wraps the outcome of an effect in an `Option` type. If the
|
||
* original effect succeeds, the success value is wrapped in `Option.some`. If
|
||
* the effect fails, the failure is converted to `Option.none`.
|
||
*
|
||
* This is particularly useful for scenarios where you want to represent the
|
||
* absence of a value explicitly, without causing the resulting effect to fail.
|
||
* The resulting effect has an error type of `never`, meaning it cannot fail
|
||
* directly. However, unrecoverable errors, also referred to as defects, are
|
||
* not captured and will still result in failure.
|
||
*
|
||
* **Example** (Using Effect.option to Handle Errors)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const maybe1 = Effect.option(Effect.succeed(1))
|
||
*
|
||
* Effect.runPromiseExit(maybe1).then(console.log)
|
||
* // Output:
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Success',
|
||
* // value: { _id: 'Option', _tag: 'Some', value: 1 }
|
||
* // }
|
||
*
|
||
* const maybe2 = Effect.option(Effect.fail("Uh oh!"))
|
||
*
|
||
* Effect.runPromiseExit(maybe2).then(console.log)
|
||
* // Output:
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Success',
|
||
* // value: { _id: 'Option', _tag: 'None' }
|
||
* // }
|
||
*
|
||
* const maybe3 = Effect.option(Effect.die("Boom!"))
|
||
*
|
||
* Effect.runPromiseExit(maybe3).then(console.log)
|
||
* // Output:
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: { _id: 'Cause', _tag: 'Die', defect: 'Boom!' }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @see {@link either} for a version that uses `Either` instead.
|
||
* @see {@link exit} for a version that encapsulates both recoverable errors and defects in an `Exit`.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Outcome Encapsulation
|
||
*/
|
||
const option = exports.option = effect.option;
|
||
/**
|
||
* Encapsulates both success and failure of an `Effect` into an `Either` type.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function converts an effect that may fail into an effect that always
|
||
* succeeds, wrapping the outcome in an `Either` type. The result will be
|
||
* `Either.Left` if the effect fails, containing the recoverable error, or
|
||
* `Either.Right` if it succeeds, containing the result.
|
||
*
|
||
* Using this function, you can handle recoverable errors explicitly without
|
||
* causing the effect to fail. This is particularly useful in scenarios where
|
||
* you want to chain effects and manage both success and failure in the same
|
||
* logical flow.
|
||
*
|
||
* It's important to note that unrecoverable errors, often referred to as
|
||
* "defects," are still thrown and not captured within the `Either` type. Only
|
||
* failures that are explicitly represented as recoverable errors in the effect
|
||
* are encapsulated.
|
||
*
|
||
* The resulting effect cannot fail directly because all recoverable failures
|
||
* are represented inside the `Either` type.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Either, Random } from "effect"
|
||
*
|
||
* class HttpError {
|
||
* readonly _tag = "HttpError"
|
||
* }
|
||
*
|
||
* class ValidationError {
|
||
* readonly _tag = "ValidationError"
|
||
* }
|
||
*
|
||
* // ┌─── Effect<string, HttpError | ValidationError, never>
|
||
* // ▼
|
||
* const program = Effect.gen(function* () {
|
||
* const n1 = yield* Random.next
|
||
* const n2 = yield* Random.next
|
||
* if (n1 < 0.5) {
|
||
* yield* Effect.fail(new HttpError())
|
||
* }
|
||
* if (n2 < 0.5) {
|
||
* yield* Effect.fail(new ValidationError())
|
||
* }
|
||
* return "some result"
|
||
* })
|
||
*
|
||
* // ┌─── Effect<string, never, never>
|
||
* // ▼
|
||
* const recovered = Effect.gen(function* () {
|
||
* // ┌─── Either<string, HttpError | ValidationError>
|
||
* // ▼
|
||
* const failureOrSuccess = yield* Effect.either(program)
|
||
* return Either.match(failureOrSuccess, {
|
||
* onLeft: (error) => `Recovering from ${error._tag}`,
|
||
* onRight: (value) => value // Do nothing in case of success
|
||
* })
|
||
* })
|
||
* ```
|
||
*
|
||
* @see {@link option} for a version that uses `Option` instead.
|
||
* @see {@link exit} for a version that encapsulates both recoverable errors and defects in an `Exit`.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Outcome Encapsulation
|
||
*/
|
||
const either = exports.either = core.either;
|
||
/**
|
||
* Encapsulates both success and failure of an `Effect` using the `Exit` type.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function converts an effect into one that always succeeds, wrapping its
|
||
* outcome in the `Exit` type. The `Exit` type provides explicit handling of
|
||
* both success (`Exit.Success`) and failure (`Exit.Failure`) cases, including
|
||
* defects (unrecoverable errors).
|
||
*
|
||
* Unlike {@link either} or {@link option}, this function also encapsulates
|
||
* defects, which are typically unrecoverable and would otherwise terminate the
|
||
* effect. With the `Exit` type, defects are represented in `Exit.Failure`,
|
||
* allowing for detailed introspection and structured error handling.
|
||
*
|
||
* This makes the resulting effect robust and incapable of direct failure (its
|
||
* error type is `never`). It is particularly useful for workflows where all
|
||
* outcomes, including unexpected defects, must be managed and analyzed.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Cause, Console, Exit } from "effect"
|
||
*
|
||
* // Simulating a runtime error
|
||
* const task = Effect.dieMessage("Boom!")
|
||
*
|
||
* const program = Effect.gen(function* () {
|
||
* const exit = yield* Effect.exit(task)
|
||
* if (Exit.isFailure(exit)) {
|
||
* const cause = exit.cause
|
||
* if (
|
||
* Cause.isDieType(cause) &&
|
||
* Cause.isRuntimeException(cause.defect)
|
||
* ) {
|
||
* yield* Console.log(
|
||
* `RuntimeException defect caught: ${cause.defect.message}`
|
||
* )
|
||
* } else {
|
||
* yield* Console.log("Unknown failure caught.")
|
||
* }
|
||
* }
|
||
* })
|
||
*
|
||
* // We get an Exit.Success because we caught all failures
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // RuntimeException defect caught: Boom!
|
||
* // {
|
||
* // _id: "Exit",
|
||
* // _tag: "Success",
|
||
* // value: undefined
|
||
* // }
|
||
* ```
|
||
*
|
||
* @see {@link option} for a version that uses `Option` instead.
|
||
* @see {@link either} for a version that uses `Either` instead.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Outcome Encapsulation
|
||
*/
|
||
const exit = exports.exit = core.exit;
|
||
/**
|
||
* Converts an `Effect` into an operation that completes a `Deferred` with its result.
|
||
*
|
||
* **Details**
|
||
*
|
||
* The `intoDeferred` function takes an effect and a `Deferred` and ensures that the `Deferred`
|
||
* is completed based on the outcome of the effect. If the effect succeeds, the `Deferred` is
|
||
* completed with the success value. If the effect fails, the `Deferred` is completed with the
|
||
* failure. Additionally, if the effect is interrupted, the `Deferred` will also be interrupted.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Deferred, Effect } from "effect"
|
||
*
|
||
* // Define an effect that succeeds
|
||
* const successEffect = Effect.succeed(42)
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* // Create a deferred
|
||
* const deferred = yield* Deferred.make<number, string>()
|
||
*
|
||
* // Complete the deferred using the successEffect
|
||
* const isCompleted = yield* Effect.intoDeferred(successEffect, deferred)
|
||
*
|
||
* // Access the value of the deferred
|
||
* const value = yield* Deferred.await(deferred)
|
||
* console.log(value)
|
||
*
|
||
* return isCompleted
|
||
* })
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output:
|
||
* // 42
|
||
* // true
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Synchronization Utilities
|
||
*/
|
||
const intoDeferred = exports.intoDeferred = core.intoDeferred;
|
||
const if_ = exports.if = core.if_;
|
||
/**
|
||
* Filters an effect, dying with a custom defect if the predicate fails.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function applies a predicate to the result of an effect. If the
|
||
* predicate evaluates to `false`, the effect dies with a custom defect
|
||
* generated by the `orDieWith` function.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful for enforcing constraints on values and treating violations as
|
||
* fatal program errors.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Filtering
|
||
*/
|
||
const filterOrDie = exports.filterOrDie = effect.filterOrDie;
|
||
/**
|
||
* Filters an effect, dying with a custom message if the predicate fails.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function works like {@link filterOrDie} but allows you to specify a
|
||
* custom error message to describe the reason for the failure. The message is
|
||
* included in the defect when the predicate evaluates to `false`.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Filtering
|
||
*/
|
||
const filterOrDieMessage = exports.filterOrDieMessage = effect.filterOrDieMessage;
|
||
/**
|
||
* Filters an effect, providing an alternative effect if the predicate fails.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function applies a predicate to the result of an effect. If the
|
||
* predicate evaluates to `false`, it executes the `orElse` effect instead. The
|
||
* `orElse` effect can produce an alternative value or perform additional
|
||
* computations.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Filtering
|
||
*/
|
||
const filterOrElse = exports.filterOrElse = effect.filterOrElse;
|
||
/**
|
||
* Filters an effect, failing with a custom error if the predicate fails.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function applies a predicate to the result of an effect. If the
|
||
* predicate evaluates to `false`, the effect fails with a custom error
|
||
* generated by the `orFailWith` function.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful for enforcing constraints and treating violations as
|
||
* recoverable errors.
|
||
*
|
||
* **Providing a Guard**
|
||
*
|
||
* In addition to the filtering capabilities discussed earlier, you have the
|
||
* option to further refine and narrow down the type of the success channel by
|
||
* providing a [user-defined type
|
||
* guard](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates).
|
||
* Let's explore this concept through an example:
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, pipe } from "effect"
|
||
*
|
||
* // Define a user interface
|
||
* interface User {
|
||
* readonly name: string
|
||
* }
|
||
*
|
||
* // Simulate an asynchronous authentication function
|
||
* declare const auth: () => Promise<User | null>
|
||
*
|
||
* const program = pipe(
|
||
* Effect.promise(() => auth()),
|
||
* // Use filterOrFail with a custom type guard to ensure user is not null
|
||
* Effect.filterOrFail(
|
||
* (user): user is User => user !== null, // Type guard
|
||
* () => new Error("Unauthorized")
|
||
* ),
|
||
* // 'user' now has the type `User` (not `User | null`)
|
||
* Effect.andThen((user) => user.name)
|
||
* )
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Filtering
|
||
*/
|
||
const filterOrFail = exports.filterOrFail = effect.filterOrFail;
|
||
/**
|
||
* Filters an effect with an effectful predicate, falling back to an alternative
|
||
* effect if the predicate fails.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function applies a predicate to the result of an effect. If the
|
||
* predicate evaluates to `false`, the effect falls back to the `orElse`
|
||
* effect. The `orElse` effect can produce an alternative value or perform
|
||
* additional computations.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, pipe } from "effect"
|
||
*
|
||
* // Define a user interface
|
||
* interface User {
|
||
* readonly name: string
|
||
* }
|
||
*
|
||
* // Simulate an asynchronous authentication function
|
||
* declare const auth: () => Promise<User | null>
|
||
*
|
||
* const program = pipe(
|
||
* Effect.promise(() => auth()),
|
||
* // Use filterEffectOrElse with an effectful predicate
|
||
* Effect.filterEffectOrElse({
|
||
* predicate: (user) => Effect.succeed(user !== null),
|
||
* orElse: (user) => Effect.fail(new Error(`Unauthorized user: ${user}`))
|
||
* }),
|
||
* )
|
||
* ```
|
||
*
|
||
* @since 3.13.0
|
||
* @category Filtering
|
||
*/
|
||
const filterEffectOrElse = exports.filterEffectOrElse = core.filterEffectOrElse;
|
||
/**
|
||
* Filters an effect with an effectful predicate, failing with a custom error if the predicate fails.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function applies a predicate to the result of an effect. If the
|
||
* predicate evaluates to `false`, the effect fails with a custom error
|
||
* generated by the `orFailWith` function.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful for enforcing constraints and treating violations as
|
||
* recoverable errors.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, pipe } from "effect"
|
||
*
|
||
* // Define a user interface
|
||
* interface User {
|
||
* readonly name: string
|
||
* }
|
||
*
|
||
* // Simulate an asynchronous authentication function
|
||
* declare const auth: () => Promise<User | null>
|
||
*
|
||
* const program = pipe(
|
||
* Effect.promise(() => auth()),
|
||
* // Use filterEffectOrFail with an effectful predicate
|
||
* Effect.filterEffectOrFail({
|
||
* predicate: (user) => Effect.succeed(user !== null),
|
||
* orFailWith: () => new Error("Unauthorized")
|
||
* }),
|
||
* )
|
||
* ```
|
||
*
|
||
* @since 3.13.0
|
||
* @category Filtering
|
||
*/
|
||
const filterEffectOrFail = exports.filterEffectOrFail = core.filterEffectOrFail;
|
||
/**
|
||
* Executes an effect only if the condition is `false`.
|
||
*
|
||
* @see {@link unlessEffect} for a version that allows the condition to be an effect.
|
||
* @see {@link when} for a version that executes the effect when the condition is `true`.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Conditional Operators
|
||
*/
|
||
const unless = exports.unless = effect.unless;
|
||
/**
|
||
* Conditionally execute an effect based on the result of another effect.
|
||
*
|
||
* @see {@link unless} for a version that allows the condition to be a boolean.
|
||
* @see {@link whenEffect} for a version that executes the effect when the condition is `true`.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Conditional Operators
|
||
*/
|
||
const unlessEffect = exports.unlessEffect = effect.unlessEffect;
|
||
/**
|
||
* Conditionally executes an effect based on a boolean condition.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to run an effect only if a given condition evaluates
|
||
* to `true`. If the condition is `true`, the effect is executed, and its result
|
||
* is wrapped in an `Option.some`. If the condition is `false`, the effect is
|
||
* skipped, and the result is `Option.none`.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function is useful for scenarios where you need to dynamically decide
|
||
* whether to execute an effect based on runtime logic, while also representing
|
||
* the skipped case explicitly.
|
||
*
|
||
* **Example** (Conditional Effect Execution)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Option } from "effect"
|
||
*
|
||
* const validateWeightOption = (
|
||
* weight: number
|
||
* ): Effect.Effect<Option.Option<number>> =>
|
||
* // Conditionally execute the effect if the weight is non-negative
|
||
* Effect.succeed(weight).pipe(Effect.when(() => weight >= 0))
|
||
*
|
||
* // Run with a valid weight
|
||
* Effect.runPromise(validateWeightOption(100)).then(console.log)
|
||
* // Output:
|
||
* // {
|
||
* // _id: "Option",
|
||
* // _tag: "Some",
|
||
* // value: 100
|
||
* // }
|
||
*
|
||
* // Run with an invalid weight
|
||
* Effect.runPromise(validateWeightOption(-5)).then(console.log)
|
||
* // Output:
|
||
* // {
|
||
* // _id: "Option",
|
||
* // _tag: "None"
|
||
* // }
|
||
* ```
|
||
*
|
||
* @see {@link whenEffect} for a version that allows the condition to be an effect.
|
||
* @see {@link unless} for a version that executes the effect when the condition is `false`.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Conditional Operators
|
||
*/
|
||
const when = exports.when = effect.when;
|
||
/**
|
||
* Conditionally executes an effect based on the result of another effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to run an effect only if a conditional effect
|
||
* evaluating to a boolean resolves to `true`. If the conditional effect
|
||
* evaluates to `true`, the specified effect is executed, and its result is
|
||
* wrapped in `Option.some`. If the conditional effect evaluates to `false`, the
|
||
* effect is skipped, and the result is `Option.none`.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function is particularly useful when the decision to execute an effect
|
||
* depends on the result of another effect, such as a random value, a
|
||
* user-provided input, or a network request result.
|
||
*
|
||
* **Example** (Using an Effect as a Condition)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Random } from "effect"
|
||
*
|
||
* const randomIntOption = Random.nextInt.pipe(
|
||
* Effect.whenEffect(Random.nextBoolean)
|
||
* )
|
||
*
|
||
* console.log(Effect.runSync(randomIntOption))
|
||
* // Example Output:
|
||
* // { _id: 'Option', _tag: 'Some', value: 8609104974198840 }
|
||
* ```
|
||
*
|
||
* @see {@link when} for a version that allows the condition to be a boolean.
|
||
* @see {@link unlessEffect} for a version that executes the effect when the condition is `false`.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Conditional Operators
|
||
*/
|
||
const whenEffect = exports.whenEffect = core.whenEffect;
|
||
/**
|
||
* Executes an effect conditionally based on the value of a `FiberRef` that
|
||
* satisfies a predicate.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function enables you to execute an effect only when the value of a
|
||
* specified `FiberRef` meets a certain condition defined by a predicate. If the
|
||
* value satisfies the predicate, the effect is executed, and the result is
|
||
* wrapped in an `Option.some`. If the predicate is not satisfied, the effect is
|
||
* skipped, and the result is `Option.none`. In both cases, the current value of
|
||
* the `FiberRef` is included in the result.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Conditional Operators
|
||
*/
|
||
const whenFiberRef = exports.whenFiberRef = effect.whenFiberRef;
|
||
/**
|
||
* Executes an effect conditionally based on the value of a `Ref` that satisfies
|
||
* a predicate.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to execute an effect only when the value of a
|
||
* specified `Ref` meets a condition defined by a predicate. If the value
|
||
* satisfies the predicate, the effect is executed, and the result is wrapped in
|
||
* an `Option.some`. If the predicate is not satisfied, the effect is skipped,
|
||
* and the result is `Option.none`. In both cases, the current value of the
|
||
* `Ref` is included in the result.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Conditional Operators
|
||
*/
|
||
const whenRef = exports.whenRef = effect.whenRef;
|
||
/**
|
||
* Chains effects to produce new `Effect` instances, useful for combining
|
||
* operations that depend on previous results.
|
||
*
|
||
* **Syntax**
|
||
*
|
||
* ```ts skip-type-checking
|
||
* const flatMappedEffect = pipe(myEffect, Effect.flatMap(transformation))
|
||
* // or
|
||
* const flatMappedEffect = Effect.flatMap(myEffect, transformation)
|
||
* // or
|
||
* const flatMappedEffect = myEffect.pipe(Effect.flatMap(transformation))
|
||
* ```
|
||
*
|
||
* **Details**
|
||
*
|
||
* `flatMap` lets you sequence effects so that the result of one effect can be
|
||
* used in the next step. It is similar to `flatMap` used with arrays but works
|
||
* specifically with `Effect` instances, allowing you to avoid deeply nested
|
||
* effect structures.
|
||
*
|
||
* Since effects are immutable, `flatMap` always returns a new effect instead of
|
||
* changing the original one.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use `flatMap` when you need to chain multiple effects, ensuring that each
|
||
* step produces a new `Effect` while flattening any nested effects that may
|
||
* occur.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { pipe, Effect } from "effect"
|
||
*
|
||
* // Function to apply a discount safely to a transaction amount
|
||
* const applyDiscount = (
|
||
* total: number,
|
||
* discountRate: number
|
||
* ): Effect.Effect<number, Error> =>
|
||
* discountRate === 0
|
||
* ? Effect.fail(new Error("Discount rate cannot be zero"))
|
||
* : Effect.succeed(total - (total * discountRate) / 100)
|
||
*
|
||
* // Simulated asynchronous task to fetch a transaction amount from database
|
||
* const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))
|
||
*
|
||
* // Chaining the fetch and discount application using `flatMap`
|
||
* const finalAmount = pipe(
|
||
* fetchTransactionAmount,
|
||
* Effect.flatMap((amount) => applyDiscount(amount, 5))
|
||
* )
|
||
*
|
||
* Effect.runPromise(finalAmount).then(console.log)
|
||
* // Output: 95
|
||
* ```
|
||
*
|
||
* @see {@link tap} for a version that ignores the result of the effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Sequencing
|
||
*/
|
||
const flatMap = exports.flatMap = core.flatMap;
|
||
/**
|
||
* Chains two actions, where the second action can depend on the result of the
|
||
* first.
|
||
*
|
||
* **Syntax**
|
||
*
|
||
* ```ts skip-type-checking
|
||
* const transformedEffect = pipe(myEffect, Effect.andThen(anotherEffect))
|
||
* // or
|
||
* const transformedEffect = Effect.andThen(myEffect, anotherEffect)
|
||
* // or
|
||
* const transformedEffect = myEffect.pipe(Effect.andThen(anotherEffect))
|
||
* ```
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use `andThen` when you need to run multiple actions in sequence, with the
|
||
* second action depending on the result of the first. This is useful for
|
||
* combining effects or handling computations that must happen in order.
|
||
*
|
||
* **Details**
|
||
*
|
||
* The second action can be:
|
||
*
|
||
* - A constant value (similar to {@link as})
|
||
* - A function returning a value (similar to {@link map})
|
||
* - A `Promise`
|
||
* - A function returning a `Promise`
|
||
* - An `Effect`
|
||
* - A function returning an `Effect` (similar to {@link flatMap})
|
||
*
|
||
* **Note:** `andThen` works well with both `Option` and `Either` types,
|
||
* treating them as effects.
|
||
*
|
||
* **Example** (Applying a Discount Based on Fetched Amount)
|
||
*
|
||
* ```ts
|
||
* import { pipe, Effect } from "effect"
|
||
*
|
||
* // Function to apply a discount safely to a transaction amount
|
||
* const applyDiscount = (
|
||
* total: number,
|
||
* discountRate: number
|
||
* ): Effect.Effect<number, Error> =>
|
||
* discountRate === 0
|
||
* ? Effect.fail(new Error("Discount rate cannot be zero"))
|
||
* : Effect.succeed(total - (total * discountRate) / 100)
|
||
*
|
||
* // Simulated asynchronous task to fetch a transaction amount from database
|
||
* const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))
|
||
*
|
||
* // Using Effect.map and Effect.flatMap
|
||
* const result1 = pipe(
|
||
* fetchTransactionAmount,
|
||
* Effect.map((amount) => amount * 2),
|
||
* Effect.flatMap((amount) => applyDiscount(amount, 5))
|
||
* )
|
||
*
|
||
* Effect.runPromise(result1).then(console.log)
|
||
* // Output: 190
|
||
*
|
||
* // Using Effect.andThen
|
||
* const result2 = pipe(
|
||
* fetchTransactionAmount,
|
||
* Effect.andThen((amount) => amount * 2),
|
||
* Effect.andThen((amount) => applyDiscount(amount, 5))
|
||
* )
|
||
*
|
||
* Effect.runPromise(result2).then(console.log)
|
||
* // Output: 190
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Sequencing
|
||
*/
|
||
const andThen = exports.andThen = core.andThen;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Sequencing
|
||
*/
|
||
const flatten = exports.flatten = core.flatten;
|
||
/**
|
||
* Races two effects and returns the result of the first successful one.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function takes two effects and runs them concurrently. The first effect
|
||
* that successfully completes will determine the result of the race, and the
|
||
* other effect will be interrupted.
|
||
*
|
||
* If neither effect succeeds, the function will fail with a `Cause`
|
||
* containing all the errors.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful when you want to run two effects concurrently, but only care
|
||
* about the first one to succeed. It is commonly used in cases like timeouts,
|
||
* retries, or when you want to optimize for the faster response without
|
||
* worrying about the other effect.
|
||
*
|
||
* **Handling Success or Failure with Either**
|
||
*
|
||
* If you want to handle the result of whichever task completes first, whether
|
||
* it succeeds or fails, you can use the `Effect.either` function. This function
|
||
* wraps the result in an `Either` type, allowing you to see if the result
|
||
* was a success (`Right`) or a failure (`Left`).
|
||
*
|
||
* **Example** (Both Tasks Succeed)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const task1 = Effect.succeed("task1").pipe(
|
||
* Effect.delay("200 millis"),
|
||
* Effect.tap(Console.log("task1 done")),
|
||
* Effect.onInterrupt(() => Console.log("task1 interrupted"))
|
||
* )
|
||
* const task2 = Effect.succeed("task2").pipe(
|
||
* Effect.delay("100 millis"),
|
||
* Effect.tap(Console.log("task2 done")),
|
||
* Effect.onInterrupt(() => Console.log("task2 interrupted"))
|
||
* )
|
||
*
|
||
* const program = Effect.race(task1, task2)
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output:
|
||
* // task1 done
|
||
* // task2 interrupted
|
||
* ```
|
||
*
|
||
* **Example** (One Task Fails, One Succeeds)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const task1 = Effect.fail("task1").pipe(
|
||
* Effect.delay("100 millis"),
|
||
* Effect.tap(Console.log("task1 done")),
|
||
* Effect.onInterrupt(() => Console.log("task1 interrupted"))
|
||
* )
|
||
* const task2 = Effect.succeed("task2").pipe(
|
||
* Effect.delay("200 millis"),
|
||
* Effect.tap(Console.log("task2 done")),
|
||
* Effect.onInterrupt(() => Console.log("task2 interrupted"))
|
||
* )
|
||
*
|
||
* const program = Effect.race(task1, task2)
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output:
|
||
* // task2 done
|
||
* ```
|
||
*
|
||
* **Example** (Both Tasks Fail)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const task1 = Effect.fail("task1").pipe(
|
||
* Effect.delay("100 millis"),
|
||
* Effect.tap(Console.log("task1 done")),
|
||
* Effect.onInterrupt(() => Console.log("task1 interrupted"))
|
||
* )
|
||
* const task2 = Effect.fail("task2").pipe(
|
||
* Effect.delay("200 millis"),
|
||
* Effect.tap(Console.log("task2 done")),
|
||
* Effect.onInterrupt(() => Console.log("task2 interrupted"))
|
||
* )
|
||
*
|
||
* const program = Effect.race(task1, task2)
|
||
*
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: {
|
||
* // _id: 'Cause',
|
||
* // _tag: 'Parallel',
|
||
* // left: { _id: 'Cause', _tag: 'Fail', failure: 'task1' },
|
||
* // right: { _id: 'Cause', _tag: 'Fail', failure: 'task2' }
|
||
* // }
|
||
* // }
|
||
* ```
|
||
*
|
||
* **Example** (Handling Success or Failure with Either)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const task1 = Effect.fail("task1").pipe(
|
||
* Effect.delay("100 millis"),
|
||
* Effect.tap(Console.log("task1 done")),
|
||
* Effect.onInterrupt(() => Console.log("task1 interrupted"))
|
||
* )
|
||
* const task2 = Effect.succeed("task2").pipe(
|
||
* Effect.delay("200 millis"),
|
||
* Effect.tap(Console.log("task2 done")),
|
||
* Effect.onInterrupt(() => Console.log("task2 interrupted"))
|
||
* )
|
||
*
|
||
* // Run both tasks concurrently, wrapping the result
|
||
* // in Either to capture success or failure
|
||
* const program = Effect.race(Effect.either(task1), Effect.either(task2))
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output:
|
||
* // task2 interrupted
|
||
* // { _id: 'Either', _tag: 'Left', left: 'task1' }
|
||
* ```
|
||
*
|
||
* @see {@link raceAll} for a version that handles multiple effects.
|
||
* @see {@link raceFirst} for a version that returns the result of the first effect to complete.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Racing
|
||
*/
|
||
const race = exports.race = fiberRuntime.race;
|
||
/**
|
||
* Races multiple effects and returns the first successful result.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function runs multiple effects concurrently and returns the result of
|
||
* the first one to succeed. If one effect succeeds, the others will be
|
||
* interrupted.
|
||
*
|
||
* If none of the effects succeed, the function will fail with the last error
|
||
* encountered.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful when you want to race multiple effects, but only care about
|
||
* the first one to succeed. It is commonly used in cases like timeouts,
|
||
* retries, or when you want to optimize for the faster response without
|
||
* worrying about the other effects.
|
||
*
|
||
* **Example** (All Tasks Succeed)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const task1 = Effect.succeed("task1").pipe(
|
||
* Effect.delay("100 millis"),
|
||
* Effect.tap(Console.log("task1 done")),
|
||
* Effect.onInterrupt(() => Console.log("task1 interrupted"))
|
||
* )
|
||
* const task2 = Effect.succeed("task2").pipe(
|
||
* Effect.delay("200 millis"),
|
||
* Effect.tap(Console.log("task2 done")),
|
||
* Effect.onInterrupt(() => Console.log("task2 interrupted"))
|
||
* )
|
||
*
|
||
* const task3 = Effect.succeed("task3").pipe(
|
||
* Effect.delay("150 millis"),
|
||
* Effect.tap(Console.log("task3 done")),
|
||
* Effect.onInterrupt(() => Console.log("task3 interrupted"))
|
||
* )
|
||
*
|
||
* const program = Effect.raceAll([task1, task2, task3])
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output:
|
||
* // task1 done
|
||
* // task2 interrupted
|
||
* // task3 interrupted
|
||
* ```
|
||
*
|
||
* **Example** (One Task Fails, Two Tasks Succeed)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const task1 = Effect.fail("task1").pipe(
|
||
* Effect.delay("100 millis"),
|
||
* Effect.tap(Console.log("task1 done")),
|
||
* Effect.onInterrupt(() => Console.log("task1 interrupted"))
|
||
* )
|
||
* const task2 = Effect.succeed("task2").pipe(
|
||
* Effect.delay("200 millis"),
|
||
* Effect.tap(Console.log("task2 done")),
|
||
* Effect.onInterrupt(() => Console.log("task2 interrupted"))
|
||
* )
|
||
*
|
||
* const task3 = Effect.succeed("task3").pipe(
|
||
* Effect.delay("150 millis"),
|
||
* Effect.tap(Console.log("task3 done")),
|
||
* Effect.onInterrupt(() => Console.log("task3 interrupted"))
|
||
* )
|
||
*
|
||
* const program = Effect.raceAll([task1, task2, task3])
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output:
|
||
* // task3 done
|
||
* // task2 interrupted
|
||
* ```
|
||
*
|
||
* **Example** (All Tasks Fail)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const task1 = Effect.fail("task1").pipe(
|
||
* Effect.delay("100 millis"),
|
||
* Effect.tap(Console.log("task1 done")),
|
||
* Effect.onInterrupt(() => Console.log("task1 interrupted"))
|
||
* )
|
||
* const task2 = Effect.fail("task2").pipe(
|
||
* Effect.delay("200 millis"),
|
||
* Effect.tap(Console.log("task2 done")),
|
||
* Effect.onInterrupt(() => Console.log("task2 interrupted"))
|
||
* )
|
||
*
|
||
* const task3 = Effect.fail("task3").pipe(
|
||
* Effect.delay("150 millis"),
|
||
* Effect.tap(Console.log("task3 done")),
|
||
* Effect.onInterrupt(() => Console.log("task3 interrupted"))
|
||
* )
|
||
*
|
||
* const program = Effect.raceAll([task1, task2, task3])
|
||
*
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: { _id: 'Cause', _tag: 'Fail', failure: 'task2' }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @see {@link race} for a version that handles only two effects.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Racing
|
||
*/
|
||
const raceAll = exports.raceAll = fiberRuntime.raceAll;
|
||
/**
|
||
* Races two effects and returns the result of the first one to complete.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function takes two effects and runs them concurrently, returning the
|
||
* result of the first one that completes, regardless of whether it succeeds or
|
||
* fails.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function is useful when you want to race two operations, and you want to
|
||
* proceed with whichever one finishes first, regardless of whether it succeeds
|
||
* or fails.
|
||
*
|
||
* **Disconnecting Effects**
|
||
*
|
||
* The `Effect.raceFirst` function safely interrupts the “loser” effect once the other completes, but it will not resume until the loser is cleanly terminated.
|
||
*
|
||
* If you want a quicker return, you can disconnect the interrupt signal for both effects. Instead of calling:
|
||
*
|
||
* ```ts skip-type-checking
|
||
* Effect.raceFirst(task1, task2)
|
||
* ```
|
||
*
|
||
* You can use:
|
||
*
|
||
* ```ts skip-type-checking
|
||
* Effect.raceFirst(Effect.disconnect(task1), Effect.disconnect(task2))
|
||
* ```
|
||
*
|
||
* This allows both effects to complete independently while still terminating the losing effect in the background.
|
||
*
|
||
* **Example** (Both Tasks Succeed)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const task1 = Effect.succeed("task1").pipe(
|
||
* Effect.delay("100 millis"),
|
||
* Effect.tap(Console.log("task1 done")),
|
||
* Effect.onInterrupt(() =>
|
||
* Console.log("task1 interrupted").pipe(Effect.delay("100 millis"))
|
||
* )
|
||
* )
|
||
* const task2 = Effect.succeed("task2").pipe(
|
||
* Effect.delay("200 millis"),
|
||
* Effect.tap(Console.log("task2 done")),
|
||
* Effect.onInterrupt(() =>
|
||
* Console.log("task2 interrupted").pipe(Effect.delay("100 millis"))
|
||
* )
|
||
* )
|
||
*
|
||
* const program = Effect.raceFirst(task1, task2).pipe(
|
||
* Effect.tap(Console.log("more work..."))
|
||
* )
|
||
*
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // task1 done
|
||
* // task2 interrupted
|
||
* // more work...
|
||
* // { _id: 'Exit', _tag: 'Success', value: 'task1' }
|
||
* ```
|
||
*
|
||
* **Example** (One Task Fails, One Succeeds)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const task1 = Effect.fail("task1").pipe(
|
||
* Effect.delay("100 millis"),
|
||
* Effect.tap(Console.log("task1 done")),
|
||
* Effect.onInterrupt(() =>
|
||
* Console.log("task1 interrupted").pipe(Effect.delay("100 millis"))
|
||
* )
|
||
* )
|
||
* const task2 = Effect.succeed("task2").pipe(
|
||
* Effect.delay("200 millis"),
|
||
* Effect.tap(Console.log("task2 done")),
|
||
* Effect.onInterrupt(() =>
|
||
* Console.log("task2 interrupted").pipe(Effect.delay("100 millis"))
|
||
* )
|
||
* )
|
||
*
|
||
* const program = Effect.raceFirst(task1, task2).pipe(
|
||
* Effect.tap(Console.log("more work..."))
|
||
* )
|
||
*
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // task2 interrupted
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: { _id: 'Cause', _tag: 'Fail', failure: 'task1' }
|
||
* // }
|
||
* ```
|
||
*
|
||
* **Example** (Using Effect.disconnect for Quicker Return)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const task1 = Effect.succeed("task1").pipe(
|
||
* Effect.delay("100 millis"),
|
||
* Effect.tap(Console.log("task1 done")),
|
||
* Effect.onInterrupt(() =>
|
||
* Console.log("task1 interrupted").pipe(Effect.delay("100 millis"))
|
||
* )
|
||
* )
|
||
* const task2 = Effect.succeed("task2").pipe(
|
||
* Effect.delay("200 millis"),
|
||
* Effect.tap(Console.log("task2 done")),
|
||
* Effect.onInterrupt(() =>
|
||
* Console.log("task2 interrupted").pipe(Effect.delay("100 millis"))
|
||
* )
|
||
* )
|
||
*
|
||
* // Race the two tasks with disconnect to allow quicker return
|
||
* const program = Effect.raceFirst(
|
||
* Effect.disconnect(task1),
|
||
* Effect.disconnect(task2)
|
||
* ).pipe(Effect.tap(Console.log("more work...")))
|
||
*
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // task1 done
|
||
* // more work...
|
||
* // { _id: 'Exit', _tag: 'Success', value: 'task1' }
|
||
* // task2 interrupted
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Racing
|
||
*/
|
||
const raceFirst = exports.raceFirst = circular.raceFirst;
|
||
/**
|
||
* Races two effects and calls a finisher when the first one completes.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function runs two effects concurrently and calls a specified “finisher”
|
||
* function once one of the effects completes, regardless of whether it succeeds
|
||
* or fails.
|
||
*
|
||
* The finisher functions for each effect allow you to handle the results of
|
||
* each effect as soon as they complete.
|
||
*
|
||
* The function takes two finisher callbacks, one for each effect, and allows
|
||
* you to specify how to handle the result of the race.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function is useful when you need to react to the completion of either
|
||
* effect without waiting for both to finish. It can be used whenever you want
|
||
* to take action based on the first available result.
|
||
*
|
||
* **Example** (Handling Results of Concurrent Tasks)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const task1 = Effect.succeed("task1").pipe(
|
||
* Effect.delay("100 millis"),
|
||
* Effect.tap(Console.log("task1 done")),
|
||
* Effect.onInterrupt(() =>
|
||
* Console.log("task1 interrupted").pipe(Effect.delay("100 millis"))
|
||
* )
|
||
* )
|
||
* const task2 = Effect.succeed("task2").pipe(
|
||
* Effect.delay("200 millis"),
|
||
* Effect.tap(Console.log("task2 done")),
|
||
* Effect.onInterrupt(() =>
|
||
* Console.log("task2 interrupted").pipe(Effect.delay("100 millis"))
|
||
* )
|
||
* )
|
||
*
|
||
* const program = Effect.raceWith(task1, task2, {
|
||
* onSelfDone: (exit) => Console.log(`task1 exited with ${exit}`),
|
||
* onOtherDone: (exit) => Console.log(`task2 exited with ${exit}`)
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output:
|
||
* // task1 done
|
||
* // task1 exited with {
|
||
* // "_id": "Exit",
|
||
* // "_tag": "Success",
|
||
* // "value": "task1"
|
||
* // }
|
||
* // task2 interrupted
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Racing
|
||
*/
|
||
const raceWith = exports.raceWith = fiberRuntime.raceWith;
|
||
/**
|
||
* Summarizes a effect by computing some value before and after execution, and
|
||
* then combining the values to produce a summary, together with the result of
|
||
* execution.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Sequencing
|
||
*/
|
||
const summarized = exports.summarized = effect.summarized;
|
||
/**
|
||
* Runs a side effect with the result of an effect without changing the original
|
||
* value.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function works similarly to `flatMap`, but it ignores the result of the
|
||
* function passed to it. The value from the previous effect remains available
|
||
* for the next part of the chain. Note that if the side effect fails, the
|
||
* entire chain will fail too.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you want to perform a side effect, like logging or
|
||
* tracking, without modifying the main value. This is useful when you need to
|
||
* observe or record an action but want the original value to be passed to the
|
||
* next step.
|
||
*
|
||
* **Example** (Logging a step in a pipeline)
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect, pipe } from "effect"
|
||
*
|
||
* // Function to apply a discount safely to a transaction amount
|
||
* const applyDiscount = (
|
||
* total: number,
|
||
* discountRate: number
|
||
* ): Effect.Effect<number, Error> =>
|
||
* discountRate === 0
|
||
* ? Effect.fail(new Error("Discount rate cannot be zero"))
|
||
* : Effect.succeed(total - (total * discountRate) / 100)
|
||
*
|
||
* // Simulated asynchronous task to fetch a transaction amount from database
|
||
* const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))
|
||
*
|
||
* const finalAmount = pipe(
|
||
* fetchTransactionAmount,
|
||
* // Log the fetched transaction amount
|
||
* Effect.tap((amount) => Console.log(`Apply a discount to: ${amount}`)),
|
||
* // `amount` is still available!
|
||
* Effect.flatMap((amount) => applyDiscount(amount, 5))
|
||
* )
|
||
*
|
||
* Effect.runPromise(finalAmount).then(console.log)
|
||
* // Output:
|
||
* // Apply a discount to: 100
|
||
* // 95
|
||
* ```
|
||
*
|
||
* @see {@link flatMap} for a version that allows you to change the value.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Sequencing
|
||
*/
|
||
const tap = exports.tap = core.tap;
|
||
/**
|
||
* Allows you to inspect both success and failure outcomes of an effect and
|
||
* perform side effects for each.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function enables you to handle both success and failure cases
|
||
* separately, without modifying the main effect's result. It is particularly
|
||
* useful for scenarios where you need to log, monitor, or perform additional
|
||
* actions depending on whether the effect succeeded or failed.
|
||
*
|
||
* When the effect succeeds, the `onSuccess` handler is executed with the
|
||
* success value. When the effect fails, the `onFailure` handler is executed
|
||
* with the failure value. Both handlers can include side effects such as
|
||
* logging or analytics, and neither modifies the original effect's output.
|
||
*
|
||
* If either the success or failure handler fails, the overall effect will also
|
||
* fail.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Random, Console } from "effect"
|
||
*
|
||
* // Simulate a task that might fail
|
||
* const task = Effect.filterOrFail(
|
||
* Random.nextRange(-1, 1),
|
||
* (n) => n >= 0,
|
||
* () => "random number is negative"
|
||
* )
|
||
*
|
||
* // Use tapBoth to log both success and failure outcomes
|
||
* 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
|
||
*/
|
||
const tapBoth = exports.tapBoth = effect.tapBoth;
|
||
/**
|
||
* Inspect severe errors or defects (non-recoverable failures) in an effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function is specifically designed to handle and inspect defects, which
|
||
* are critical failures in your program, such as unexpected runtime exceptions
|
||
* or system-level errors. Unlike normal recoverable errors, defects typically
|
||
* indicate serious issues that cannot be addressed through standard error
|
||
* handling.
|
||
*
|
||
* When a defect occurs in an effect, the function you provide to this function
|
||
* will be executed, allowing you to log, monitor, or handle the defect in some
|
||
* way. Importantly, this does not alter the main result of the effect. If no
|
||
* defect occurs, the effect behaves as if this function was not used.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* // Simulate a task that fails with a recoverable error
|
||
* const task1: Effect.Effect<number, string> = Effect.fail("NetworkError")
|
||
*
|
||
* // tapDefect won't log anything because NetworkError 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
|
||
* const task2: Effect.Effect<number, string> = Effect.dieMessage(
|
||
* "Something went wrong"
|
||
* )
|
||
*
|
||
* // Log the defect using tapDefect
|
||
* 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
|
||
*/
|
||
const tapDefect = exports.tapDefect = effect.tapDefect;
|
||
/**
|
||
* Execute a side effect on failure without modifying the original effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to inspect and react to the failure of an effect by
|
||
* executing an additional effect. The failure value is passed to the provided
|
||
* function, enabling you to log it, track it, or perform any other operation.
|
||
* Importantly, the original failure remains intact and is re-propagated, so the
|
||
* effect's behavior is unchanged.
|
||
*
|
||
* The side effect you provide is only executed when the effect fails. If the
|
||
* effect succeeds, the function is ignored, and the success value is propagated
|
||
* as usual.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* // Simulate a task that fails with an error
|
||
* const task: Effect.Effect<number, string> = Effect.fail("NetworkError")
|
||
*
|
||
* // Use tapError to log the error message when the task fails
|
||
* const tapping = Effect.tapError(task, (error) =>
|
||
* Console.log(`expected error: ${error}`)
|
||
* )
|
||
*
|
||
* Effect.runFork(tapping)
|
||
* // Output:
|
||
* // expected error: NetworkError
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Sequencing
|
||
*/
|
||
const tapError = exports.tapError = effect.tapError;
|
||
/**
|
||
* Inspect errors matching a specific tag without altering the original effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to inspect and handle specific error types based on
|
||
* their `_tag` property. It is particularly useful in applications where errors
|
||
* are modeled with tagged types (e.g., union types with discriminating tags).
|
||
* By targeting errors with a specific `_tag`, you can log or perform actions on
|
||
* them while leaving the error channel and overall effect unchanged.
|
||
*
|
||
* If the error doesn't match the specified tag, this function does nothing, and
|
||
* the effect proceeds as usual.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* class NetworkError {
|
||
* readonly _tag = "NetworkError"
|
||
* constructor(readonly statusCode: number) {}
|
||
* }
|
||
*
|
||
* class ValidationError {
|
||
* readonly _tag = "ValidationError"
|
||
* constructor(readonly field: string) {}
|
||
* }
|
||
*
|
||
* // Create a task that fails with a NetworkError
|
||
* const task: Effect.Effect<number, NetworkError | ValidationError> =
|
||
* Effect.fail(new NetworkError(504))
|
||
*
|
||
* // Use tapErrorTag to inspect only NetworkError types and log the status code
|
||
* 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
|
||
*/
|
||
const tapErrorTag = exports.tapErrorTag = effect.tapErrorTag;
|
||
/**
|
||
* Inspect the complete cause of an error, including failures and defects.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function provides access to the full cause of an error, including both
|
||
* recoverable failures and irrecoverable defects. It allows you to handle, log,
|
||
* or monitor specific error causes without modifying the result of the effect.
|
||
* The full `Cause` object encapsulates the error and its contextual
|
||
* information, making it useful for debugging and understanding failure
|
||
* scenarios in complex workflows.
|
||
*
|
||
* The effect itself is not modified, and any errors or defects remain in the
|
||
* error channel of the original effect.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* // Create a task that fails with a NetworkError
|
||
* const task1: Effect.Effect<number, string> = Effect.fail("NetworkError")
|
||
*
|
||
* 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
|
||
* const task2: Effect.Effect<number, string> = Effect.dieMessage(
|
||
* "Something went wrong"
|
||
* )
|
||
*
|
||
* 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
|
||
*/
|
||
const tapErrorCause = exports.tapErrorCause = effect.tapErrorCause;
|
||
/**
|
||
* Repeats an effect indefinitely until an error occurs.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function executes an effect repeatedly in an infinite loop. Each
|
||
* iteration is executed sequentially, and the loop continues until the first
|
||
* error occurs. If the effect succeeds, it starts over from the beginning. If
|
||
* the effect fails, the error is propagated, and the loop stops.
|
||
*
|
||
* Be cautious when using this function, as it will run indefinitely unless an
|
||
* error interrupts it. This makes it suitable for long-running processes or
|
||
* continuous polling tasks, but you should ensure proper error handling or
|
||
* combine it with other operators like `timeout` or `schedule` to prevent
|
||
* unintentional infinite loops.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Repetition / Recursion
|
||
*/
|
||
const forever = exports.forever = effect.forever;
|
||
/**
|
||
* Repeatedly updates a state through an effectful operation until a condition
|
||
* is no longer met.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function provides a way to implement effectful loops, similar to a
|
||
* `while` loop in JavaScript.
|
||
*
|
||
* ```ts skip-type-checking
|
||
* let result = initial
|
||
*
|
||
* while (options.while(result)) {
|
||
* result = options.body(result)
|
||
* }
|
||
*
|
||
* return result
|
||
* ```
|
||
*
|
||
* It starts with an initial state, checks a
|
||
* condition (`while`), and executes a body operation to update the state if the
|
||
* condition evaluates to `true`. The process repeats until the condition
|
||
* returns `false`.
|
||
*
|
||
* The state is passed between iterations, allowing the body operation to modify
|
||
* it dynamically. The final state after the loop ends is returned as the result
|
||
* of the effect.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is particularly useful for scenarios where looping logic involves
|
||
* asynchronous or side-effectful operations, such as polling or iterative
|
||
* computations that depend on external factors.
|
||
*
|
||
* **Example** (Effectful Iteration)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const result = Effect.iterate(
|
||
* // Initial result
|
||
* 1,
|
||
* {
|
||
* // Condition to continue iterating
|
||
* while: (result) => result <= 5,
|
||
* // Operation to change the result
|
||
* body: (result) => Effect.succeed(result + 1)
|
||
* }
|
||
* )
|
||
*
|
||
* Effect.runPromise(result).then(console.log)
|
||
* // Output: 6
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Looping
|
||
*/
|
||
const iterate = exports.iterate = effect.iterate;
|
||
/**
|
||
* Repeatedly executes a loop with a state, collecting results or discarding
|
||
* them based on configuration.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function performs an effectful loop, starting with an initial state and
|
||
* iterating as long as the `while` condition evaluates to `true`, similar to a
|
||
* `while` loop in JavaScript.
|
||
*
|
||
* ```ts skip-type-checking
|
||
* let state = initial
|
||
* const result = []
|
||
*
|
||
* while (options.while(state)) {
|
||
* result.push(options.body(state)) // Perform the effectful operation
|
||
* state = options.step(state) // Update the state
|
||
* }
|
||
*
|
||
* return result
|
||
* ```
|
||
*
|
||
* During each iteration, the `step` function updates the state, and the `body`
|
||
* effect is executed.
|
||
*
|
||
* The results of the body effect can be collected in an array or discarded
|
||
* based on the `discard` option.
|
||
*
|
||
* **Discarding Intermediate Results**
|
||
*
|
||
* - If `discard` is `false` or not provided, the intermediate results are
|
||
* collected into an array and returned as the final result.
|
||
* - If `discard` is `true`, the intermediate results are ignored, and the
|
||
* effect returns `void`.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful for implementing loops where you need to perform effectful
|
||
* computations repeatedly, such as processing items in a list, generating
|
||
* values, or performing iterative updates.
|
||
*
|
||
* **Example** (Looping with Collected Results)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // A loop that runs 5 times, collecting each iteration's result
|
||
* const result = Effect.loop(
|
||
* // Initial state
|
||
* 1,
|
||
* {
|
||
* // Condition to continue looping
|
||
* while: (state) => state <= 5,
|
||
* // State update function
|
||
* step: (state) => state + 1,
|
||
* // Effect to be performed on each iteration
|
||
* body: (state) => Effect.succeed(state)
|
||
* }
|
||
* )
|
||
*
|
||
* Effect.runPromise(result).then(console.log)
|
||
* // Output: [1, 2, 3, 4, 5]
|
||
* ```
|
||
*
|
||
* **Example** (Loop with Discarded Results)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const result = Effect.loop(
|
||
* // Initial state
|
||
* 1,
|
||
* {
|
||
* // Condition to continue looping
|
||
* while: (state) => state <= 5,
|
||
* // State update function
|
||
* step: (state) => state + 1,
|
||
* // Effect to be performed on each iteration
|
||
* body: (state) => Console.log(`Currently at state ${state}`),
|
||
* // Discard intermediate results
|
||
* discard: true
|
||
* }
|
||
* )
|
||
*
|
||
* Effect.runPromise(result).then(console.log)
|
||
* // Output:
|
||
* // Currently at state 1
|
||
* // Currently at state 2
|
||
* // Currently at state 3
|
||
* // Currently at state 4
|
||
* // Currently at state 5
|
||
* // undefined
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Looping
|
||
*/
|
||
const loop = exports.loop = effect.loop;
|
||
/**
|
||
* Repeats an effect based on a specified schedule or until the first failure.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function executes an effect repeatedly according to the given schedule.
|
||
* Each repetition occurs after the initial execution of the effect, meaning
|
||
* that the schedule determines the number of additional repetitions. For
|
||
* example, using `Schedule.once` will result in the effect being executed twice
|
||
* (once initially and once as part of the repetition).
|
||
*
|
||
* If the effect succeeds, it is repeated according to the schedule. If it
|
||
* fails, the repetition stops immediately, and the failure is returned.
|
||
*
|
||
* The schedule can also specify delays between repetitions, making it useful
|
||
* for tasks like retrying operations with backoff, periodic execution, or
|
||
* performing a series of dependent actions.
|
||
*
|
||
* You can combine schedules for more advanced repetition logic, such as adding
|
||
* delays, limiting recursions, or dynamically adjusting based on the outcome of
|
||
* each execution.
|
||
*
|
||
* **Example** (Success Example)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Schedule, Console } from "effect"
|
||
*
|
||
* const action = Console.log("success")
|
||
* const policy = Schedule.addDelay(Schedule.recurs(2), () => "100 millis")
|
||
* const program = Effect.repeat(action, policy)
|
||
*
|
||
* Effect.runPromise(program).then((n) => console.log(`repetitions: ${n}`))
|
||
* ```
|
||
*
|
||
* **Example** (Failure Example)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Schedule } from "effect"
|
||
*
|
||
* let count = 0
|
||
*
|
||
* // Define an async effect that simulates an action with possible failures
|
||
* const action = Effect.async<string, string>((resume) => {
|
||
* if (count > 1) {
|
||
* console.log("failure")
|
||
* resume(Effect.fail("Uh oh!"))
|
||
* } else {
|
||
* count++
|
||
* console.log("success")
|
||
* resume(Effect.succeed("yay!"))
|
||
* }
|
||
* })
|
||
*
|
||
* const policy = Schedule.addDelay(Schedule.recurs(2), () => "100 millis")
|
||
* const program = Effect.repeat(action, policy)
|
||
*
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Repetition / Recursion
|
||
*/
|
||
const repeat = exports.repeat = schedule_.repeat_combined;
|
||
/**
|
||
* Repeats an effect a specified number of times or until the first failure.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function executes an effect initially and then repeats it the specified
|
||
* number of times, as long as it succeeds. For example, calling
|
||
* `repeatN(action, 2)` will execute `action` once initially and then repeat it
|
||
* two additional times if there are no failures.
|
||
*
|
||
* If the effect fails during any repetition, the failure is returned, and no
|
||
* further repetitions are attempted.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function is useful for tasks that need to be retried a fixed number of
|
||
* times or for performing repeated actions without requiring a schedule.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const action = Console.log("success")
|
||
* const program = Effect.repeatN(action, 2)
|
||
*
|
||
* Effect.runPromise(program)
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Repetition / Recursion
|
||
*/
|
||
const repeatN = exports.repeatN = effect.repeatN;
|
||
/**
|
||
* Repeats an effect with a schedule, handling failures using a custom handler.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to execute an effect repeatedly based on a specified
|
||
* schedule. If the effect fails at any point, a custom failure handler is
|
||
* invoked. The handler is provided with both the failure value and the output
|
||
* of the schedule at the time of failure. This enables advanced error recovery
|
||
* or alternative fallback logic while maintaining flexibility in how
|
||
* repetitions are handled.
|
||
*
|
||
* For example, using a schedule with `recurs(2)` will allow for two additional
|
||
* repetitions after the initial execution, provided the effect succeeds. If a
|
||
* failure occurs during any iteration, the failure handler is invoked to handle
|
||
* the situation.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Schedule } from "effect"
|
||
*
|
||
* let count = 0
|
||
*
|
||
* // Define an async effect that simulates an action with possible failures
|
||
* const action = Effect.async<string, string>((resume) => {
|
||
* if (count > 1) {
|
||
* console.log("failure")
|
||
* resume(Effect.fail("Uh oh!"))
|
||
* } else {
|
||
* count++
|
||
* console.log("success")
|
||
* resume(Effect.succeed("yay!"))
|
||
* }
|
||
* })
|
||
*
|
||
* const policy = Schedule.addDelay(
|
||
* Schedule.recurs(2), // Repeat for a maximum of 2 times
|
||
* () => "100 millis" // Add a delay of 100 milliseconds between repetitions
|
||
* )
|
||
*
|
||
* const program = Effect.repeatOrElse(action, policy, () =>
|
||
* Effect.sync(() => {
|
||
* console.log("orElse")
|
||
* return count - 1
|
||
* })
|
||
* )
|
||
*
|
||
* Effect.runPromise(program).then((n) => console.log(`repetitions: ${n}`))
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Repetition / Recursion
|
||
*/
|
||
const repeatOrElse = exports.repeatOrElse = schedule_.repeatOrElse_Effect;
|
||
/**
|
||
* Repeats an effect based on a specified schedule.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to execute an effect repeatedly according to a given
|
||
* schedule. The schedule determines the timing and number of repetitions. Each
|
||
* repetition can also depend on the decision of the schedule, providing
|
||
* flexibility for complex workflows. This function does not modify the effect's
|
||
* success or failure; it only controls its repetition.
|
||
*
|
||
* For example, you can use a schedule that recurs a specific number of times,
|
||
* adds delays between repetitions, or customizes repetition behavior based on
|
||
* external inputs. The effect runs initially and is repeated according to the
|
||
* schedule.
|
||
*
|
||
* @see {@link scheduleFrom} for a variant that allows the schedule's decision
|
||
* to depend on the result of this effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Repetition / Recursion
|
||
*/
|
||
const schedule = exports.schedule = schedule_.schedule_Effect;
|
||
/**
|
||
* Runs an effect repeatedly on a new fiber according to a given schedule.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function starts the provided effect on a new fiber and runs it
|
||
* repeatedly based on the specified schedule. The repetitions are managed by
|
||
* the schedule's rules, which define the timing and number of iterations. The
|
||
* fiber is attached to the current scope, meaning it is automatically managed
|
||
* and cleaned up when the scope is closed.
|
||
*
|
||
* The function returns a `RuntimeFiber` that allows you to monitor or interact
|
||
* with the running fiber.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is particularly useful for concurrent execution of scheduled tasks or
|
||
* when you want to continue processing without waiting for the repetitions to
|
||
* complete.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Repetition / Recursion
|
||
*/
|
||
const scheduleForked = exports.scheduleForked = schedule_.scheduleForked;
|
||
/**
|
||
* Runs an effect repeatedly according to a schedule, starting from a specified
|
||
* input value.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to repeatedly execute an effect based on a schedule.
|
||
* The schedule starts with the given `initial` input value, which is passed to
|
||
* the first execution. Subsequent executions of the effect are controlled by
|
||
* the schedule's rules, using the output of the previous iteration as the input
|
||
* for the next one.
|
||
*
|
||
* The returned effect will complete when the schedule ends or the effect fails,
|
||
* propagating the error.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Repetition / Recursion
|
||
*/
|
||
const scheduleFrom = exports.scheduleFrom = schedule_.scheduleFrom_Effect;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Repetition / Recursion
|
||
*/
|
||
const whileLoop = exports.whileLoop = core.whileLoop;
|
||
/**
|
||
* Returns a collection of all `FiberRef` values for the fiber running this
|
||
* effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Fiber Refs
|
||
*/
|
||
const getFiberRefs = exports.getFiberRefs = effect.fiberRefs;
|
||
/**
|
||
* Inherits values from all `FiberRef` instances into current fiber.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Fiber Refs
|
||
*/
|
||
const inheritFiberRefs = exports.inheritFiberRefs = effect.inheritFiberRefs;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Fiber Refs
|
||
*/
|
||
const locally = exports.locally = core.fiberRefLocally;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Fiber Refs
|
||
*/
|
||
const locallyWith = exports.locallyWith = core.fiberRefLocallyWith;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Fiber Refs
|
||
*/
|
||
const locallyScoped = exports.locallyScoped = fiberRuntime.fiberRefLocallyScoped;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Fiber Refs
|
||
*/
|
||
const locallyScopedWith = exports.locallyScopedWith = fiberRuntime.fiberRefLocallyScopedWith;
|
||
/**
|
||
* Applies the specified changes to the `FiberRef` values for the fiber
|
||
* running this workflow.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Fiber Refs
|
||
*/
|
||
const patchFiberRefs = exports.patchFiberRefs = effect.patchFiberRefs;
|
||
/**
|
||
* Sets the `FiberRef` values for the fiber running this effect to the values
|
||
* in the specified collection of `FiberRef` values.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Fiber Refs
|
||
*/
|
||
const setFiberRefs = exports.setFiberRefs = effect.setFiberRefs;
|
||
/**
|
||
* Updates the `FiberRef` values for the fiber running this effect using the
|
||
* specified function.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Fiber Refs
|
||
*/
|
||
const updateFiberRefs = exports.updateFiberRefs = effect.updateFiberRefs;
|
||
/**
|
||
* Checks if an effect has failed.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function evaluates whether an effect has resulted in a failure. It
|
||
* returns a boolean value wrapped in an effect, with `true` indicating the
|
||
* effect failed and `false` otherwise.
|
||
*
|
||
* The resulting effect cannot fail (`never` in the error channel) but retains
|
||
* the context of the original effect.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const failure = Effect.fail("Uh oh!")
|
||
*
|
||
* console.log(Effect.runSync(Effect.isFailure(failure)))
|
||
* // Output: true
|
||
*
|
||
* const defect = Effect.dieMessage("BOOM!")
|
||
*
|
||
* Effect.runSync(Effect.isFailure(defect))
|
||
* // throws: BOOM!
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Condition Checking
|
||
*/
|
||
const isFailure = exports.isFailure = effect.isFailure;
|
||
/**
|
||
* Checks if an effect has succeeded.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function evaluates whether an effect has resulted in a success. It
|
||
* returns a boolean value wrapped in an effect, with `true` indicating the
|
||
* effect succeeded and `false` otherwise.
|
||
*
|
||
* The resulting effect cannot fail (`never` in the error channel) but retains
|
||
* the context of the original effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Condition Checking
|
||
*/
|
||
const isSuccess = exports.isSuccess = effect.isSuccess;
|
||
/**
|
||
* Handles both success and failure cases of an effect without performing side
|
||
* effects.
|
||
*
|
||
* **Details**
|
||
*
|
||
* `match` lets you define custom handlers for both success and failure
|
||
* scenarios. You provide separate functions to handle each case, allowing you
|
||
* to process the result if the effect succeeds, or handle the error if the
|
||
* effect fails.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful for structuring your code to respond differently to success or
|
||
* failure without triggering side effects.
|
||
*
|
||
* **Example** (Handling Both Success and Failure Cases)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const success: Effect.Effect<number, Error> = Effect.succeed(42)
|
||
*
|
||
* const program1 = Effect.match(success, {
|
||
* onFailure: (error) => `failure: ${error.message}`,
|
||
* onSuccess: (value) => `success: ${value}`
|
||
* })
|
||
*
|
||
* // Run and log the result of the successful effect
|
||
* Effect.runPromise(program1).then(console.log)
|
||
* // Output: "success: 42"
|
||
*
|
||
* const failure: Effect.Effect<number, Error> = Effect.fail(
|
||
* new Error("Uh oh!")
|
||
* )
|
||
*
|
||
* const program2 = Effect.match(failure, {
|
||
* onFailure: (error) => `failure: ${error.message}`,
|
||
* onSuccess: (value) => `success: ${value}`
|
||
* })
|
||
*
|
||
* // Run and log the result of the failed effect
|
||
* Effect.runPromise(program2).then(console.log)
|
||
* // Output: "failure: Uh oh!"
|
||
* ```
|
||
*
|
||
* @see {@link matchEffect} if you need to perform side effects in the handlers.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Matching
|
||
*/
|
||
const match = exports.match = effect.match;
|
||
/**
|
||
* Handles failures by matching the cause of failure.
|
||
*
|
||
* **Details**
|
||
*
|
||
* The `matchCause` function allows you to handle failures with access to the
|
||
* full cause of the failure within a fiber.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful for differentiating between different types of errors, such as
|
||
* regular failures, defects, or interruptions. You can provide specific
|
||
* handling logic for each failure type based on the cause.
|
||
*
|
||
* **Example** (Handling Different Failure Causes)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const task: Effect.Effect<number, Error> = Effect.die("Uh oh!")
|
||
*
|
||
* const program = Effect.matchCause(task, {
|
||
* onFailure: (cause) => {
|
||
* switch (cause._tag) {
|
||
* case "Fail":
|
||
* // Handle standard failure
|
||
* return `Fail: ${cause.error.message}`
|
||
* case "Die":
|
||
* // Handle defects (unexpected errors)
|
||
* return `Die: ${cause.defect}`
|
||
* case "Interrupt":
|
||
* // Handle interruption
|
||
* return `${cause.fiberId} interrupted!`
|
||
* }
|
||
* // Fallback for other causes
|
||
* return "failed due to other causes"
|
||
* },
|
||
* onSuccess: (value) =>
|
||
* // task completes successfully
|
||
* `succeeded with ${value} value`
|
||
* })
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output: "Die: Uh oh!"
|
||
* ```
|
||
*
|
||
* @see {@link matchCauseEffect} if you need to perform side effects in the
|
||
* handlers.
|
||
* @see {@link match} if you don't need to handle the cause of the failure.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Matching
|
||
*/
|
||
const matchCause = exports.matchCause = core.matchCause;
|
||
/**
|
||
* Handles failures with access to the cause and allows performing side effects.
|
||
*
|
||
* **Details**
|
||
*
|
||
* The `matchCauseEffect` function works similarly to {@link matchCause}, but it
|
||
* also allows you to perform additional side effects based on the failure
|
||
* cause. This function provides access to the complete cause of the failure,
|
||
* making it possible to differentiate between various failure types, and allows
|
||
* you to respond accordingly while performing side effects (like logging or
|
||
* other operations).
|
||
*
|
||
* **Example** (Handling Different Failure Causes with Side Effects)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const task: Effect.Effect<number, Error> = Effect.die("Uh oh!")
|
||
*
|
||
* const program = Effect.matchCauseEffect(task, {
|
||
* onFailure: (cause) => {
|
||
* switch (cause._tag) {
|
||
* case "Fail":
|
||
* // Handle standard failure with a logged message
|
||
* return Console.log(`Fail: ${cause.error.message}`)
|
||
* case "Die":
|
||
* // Handle defects (unexpected errors) by logging the defect
|
||
* return Console.log(`Die: ${cause.defect}`)
|
||
* case "Interrupt":
|
||
* // Handle interruption and log the fiberId that was interrupted
|
||
* return Console.log(`${cause.fiberId} interrupted!`)
|
||
* }
|
||
* // Fallback for other causes
|
||
* return Console.log("failed due to other causes")
|
||
* },
|
||
* onSuccess: (value) =>
|
||
* // Log success if the task completes successfully
|
||
* Console.log(`succeeded with ${value} value`)
|
||
* })
|
||
*
|
||
* Effect.runPromise(program)
|
||
* // Output: "Die: Uh oh!"
|
||
* ```
|
||
*
|
||
* @see {@link matchCause} if you don't need side effects and only want to handle the result or failure.
|
||
* @see {@link matchEffect} if you don't need to handle the cause of the failure.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Matching
|
||
*/
|
||
const matchCauseEffect = exports.matchCauseEffect = core.matchCauseEffect;
|
||
/**
|
||
* Handles both success and failure cases of an effect, allowing for additional
|
||
* side effects.
|
||
*
|
||
* **Details**
|
||
*
|
||
* The `matchEffect` function is similar to {@link match}, but it enables you to
|
||
* perform side effects in the handlers for both success and failure outcomes.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful when you need to execute additional actions, like logging or
|
||
* notifying users, based on whether an effect succeeds or fails.
|
||
*
|
||
* **Example** (Handling Both Success and Failure Cases with Side Effects)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const success: Effect.Effect<number, Error> = Effect.succeed(42)
|
||
* const failure: Effect.Effect<number, Error> = Effect.fail(
|
||
* new Error("Uh oh!")
|
||
* )
|
||
*
|
||
* const program1 = Effect.matchEffect(success, {
|
||
* onFailure: (error) =>
|
||
* Effect.succeed(`failure: ${error.message}`).pipe(
|
||
* Effect.tap(Effect.log)
|
||
* ),
|
||
* onSuccess: (value) =>
|
||
* Effect.succeed(`success: ${value}`).pipe(Effect.tap(Effect.log))
|
||
* })
|
||
*
|
||
* console.log(Effect.runSync(program1))
|
||
* // Output:
|
||
* // timestamp=... level=INFO fiber=#0 message="success: 42"
|
||
* // success: 42
|
||
*
|
||
* const program2 = Effect.matchEffect(failure, {
|
||
* onFailure: (error) =>
|
||
* Effect.succeed(`failure: ${error.message}`).pipe(
|
||
* Effect.tap(Effect.log)
|
||
* ),
|
||
* onSuccess: (value) =>
|
||
* Effect.succeed(`success: ${value}`).pipe(Effect.tap(Effect.log))
|
||
* })
|
||
*
|
||
* console.log(Effect.runSync(program2))
|
||
* // Output:
|
||
* // timestamp=... level=INFO fiber=#1 message="failure: Uh oh!"
|
||
* // failure: Uh oh!
|
||
* ```
|
||
*
|
||
* @see {@link match} if you don't need side effects and only want to handle the
|
||
* result or failure.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Matching
|
||
*/
|
||
const matchEffect = exports.matchEffect = core.matchEffect;
|
||
/**
|
||
* Logs one or more messages or error causes at the current log level.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function provides a simple way to log messages or error causes during
|
||
* the execution of your effects. By default, logs are recorded at the `INFO`
|
||
* level, but this can be adjusted using other logging utilities
|
||
* (`Logger.withMinimumLogLevel`). Multiple items, including `Cause` instances,
|
||
* can be logged in a single call. When logging `Cause` instances, detailed
|
||
* error information is included in the log output.
|
||
*
|
||
* The log output includes useful metadata like the current timestamp, log
|
||
* level, and fiber ID, making it suitable for debugging and tracking purposes.
|
||
* This function does not interrupt or alter the effect's execution flow.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Cause, Effect } from "effect"
|
||
*
|
||
* const program = Effect.log(
|
||
* "message1",
|
||
* "message2",
|
||
* Cause.die("Oh no!"),
|
||
* Cause.die("Oh uh!")
|
||
* )
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output:
|
||
* // timestamp=... level=INFO fiber=#0 message=message1 message=message2 cause="Error: Oh no!
|
||
* // Error: Oh uh!"
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Logging
|
||
*/
|
||
const log = exports.log = effect.log;
|
||
/**
|
||
* Logs messages or error causes at a specified log level.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to log one or more messages or error causes while
|
||
* specifying the desired log level (e.g., DEBUG, INFO, ERROR). It provides
|
||
* flexibility in categorizing logs based on their importance or severity,
|
||
* making it easier to filter logs during debugging or production monitoring.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Cause, Effect, LogLevel } from "effect"
|
||
*
|
||
* const program = Effect.logWithLevel(
|
||
* LogLevel.Error,
|
||
* "Critical error encountered",
|
||
* Cause.die("System failure!")
|
||
* )
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output:
|
||
* // timestamp=... level=ERROR fiber=#0 message=Critical error encountered cause="Error: System failure!"
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Logging
|
||
*/
|
||
const logWithLevel = (level, ...message) => effect.logWithLevel(level)(...message);
|
||
/**
|
||
* Logs messages at the TRACE log level.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function logs the specified messages at the TRACE level. TRACE logs are
|
||
* typically used for very detailed diagnostic information. These messages are
|
||
* not displayed by default. To view them, you must adjust the logging
|
||
* configuration by setting the minimum log level to `LogLevel.Trace` using
|
||
* `Logger.withMinimumLogLevel`.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Logger, LogLevel } from "effect"
|
||
*
|
||
* const program = Effect.logTrace("message1").pipe(Logger.withMinimumLogLevel(LogLevel.Trace))
|
||
*
|
||
* Effect.runFork(program)
|
||
* // timestamp=... level=TRACE fiber=#0 message=message1
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Logging
|
||
*/
|
||
exports.logWithLevel = logWithLevel;
|
||
const logTrace = exports.logTrace = effect.logTrace;
|
||
/**
|
||
* Logs messages at the DEBUG log level.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function logs messages at the DEBUG level, which is typically used for
|
||
* diagnosing application behavior during development. DEBUG messages provide
|
||
* less detailed information than TRACE logs but are still not shown by default.
|
||
* To view these logs, adjust the log level using `Logger.withMinimumLogLevel`.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Logger, LogLevel } from "effect"
|
||
*
|
||
* const program = Effect.logDebug("message1").pipe(Logger.withMinimumLogLevel(LogLevel.Debug))
|
||
*
|
||
* Effect.runFork(program)
|
||
* // timestamp=... level=DEBUG fiber=#0 message=message1
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Logging
|
||
*/
|
||
const logDebug = exports.logDebug = effect.logDebug;
|
||
/**
|
||
* Logs messages at the INFO log level.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function logs messages at the INFO level, suitable for general
|
||
* application events or operational messages. INFO logs are shown by default
|
||
* and are commonly used for highlighting normal, non-error operations.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Logging
|
||
*/
|
||
const logInfo = exports.logInfo = effect.logInfo;
|
||
/**
|
||
* Logs messages at the WARNING log level.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function logs messages at the WARNING level, suitable for highlighting
|
||
* potential issues that are not errors but may require attention. These
|
||
* messages indicate that something unexpected occurred or might lead to errors
|
||
* in the future.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Logging
|
||
*/
|
||
const logWarning = exports.logWarning = effect.logWarning;
|
||
/**
|
||
* Logs messages at the ERROR log level.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function logs messages at the ERROR level, suitable for reporting
|
||
* application errors or failures. These logs are typically used for unexpected
|
||
* issues that need immediate attention.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Logging
|
||
*/
|
||
const logError = exports.logError = effect.logError;
|
||
/**
|
||
* Logs messages at the FATAL log level.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function logs messages at the FATAL level, suitable for reporting
|
||
* critical errors that cause the application to terminate or stop functioning.
|
||
* These logs are typically used for unrecoverable errors that require immediate
|
||
* attention.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Logging
|
||
*/
|
||
const logFatal = exports.logFatal = effect.logFatal;
|
||
/**
|
||
* Adds a log span to an effect for tracking and logging its execution duration.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function wraps an effect with a log span, providing performance
|
||
* monitoring and debugging capabilities. The log span tracks the duration of
|
||
* the wrapped effect and logs it with the specified label. This is particularly
|
||
* useful when analyzing time-sensitive operations or understanding the
|
||
* execution time of specific tasks in your application.
|
||
*
|
||
* The logged output will include the label and the total time taken for the
|
||
* operation. The span information is included in the log metadata, making it
|
||
* easy to trace performance metrics in logs.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* yield* Effect.sleep("1 second")
|
||
* yield* Effect.log("The job is finished!")
|
||
* }).pipe(Effect.withLogSpan("myspan"))
|
||
*
|
||
* Effect.runFork(program)
|
||
* // timestamp=... level=INFO fiber=#0 message="The job is finished!" myspan=1011ms
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Logging
|
||
*/
|
||
const withLogSpan = exports.withLogSpan = effect.withLogSpan;
|
||
/**
|
||
* Adds custom annotations to log entries generated within an effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to enhance log messages by appending additional
|
||
* context in the form of key-value pairs. These annotations are included in
|
||
* every log message created during the execution of the effect, making the logs
|
||
* more informative and easier to trace.
|
||
*
|
||
* The annotations can be specified as a single key-value pair or as a record of
|
||
* multiple key-value pairs. This is particularly useful for tracking
|
||
* operations, debugging, or associating specific metadata with logs for better
|
||
* observability.
|
||
*
|
||
* The annotated key-value pairs will appear alongside the log message in the
|
||
* output.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* yield* Effect.log("message1")
|
||
* yield* Effect.log("message2")
|
||
* }).pipe(Effect.annotateLogs("taskId", "1234")) // Annotation as key/value pair
|
||
*
|
||
* Effect.runFork(program)
|
||
* // timestamp=... level=INFO fiber=#0 message=message1 taskId=1234
|
||
* // timestamp=... level=INFO fiber=#0 message=message2 taskId=1234
|
||
* ```
|
||
*
|
||
* @see {@link annotateLogsScoped} to add log annotations with a limited scope.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Logging
|
||
*/
|
||
const annotateLogs = exports.annotateLogs = effect.annotateLogs;
|
||
/**
|
||
* Adds log annotations with a limited scope to enhance contextual logging.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to apply key-value annotations to log entries
|
||
* generated within a specific scope of your effect computations. The
|
||
* annotations are restricted to the defined `Scope`, ensuring that they are
|
||
* only applied to logs produced during that scope. Once the scope ends, the
|
||
* annotations are automatically removed, making it easier to manage
|
||
* context-specific logging without affecting other parts of your application.
|
||
*
|
||
* The annotations can be provided as a single key-value pair or as a record of
|
||
* multiple key-value pairs. This flexibility enables fine-grained control over
|
||
* the additional metadata included in logs for specific tasks or operations.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* yield* Effect.log("no annotations")
|
||
* yield* Effect.annotateLogsScoped({ key: "value" })
|
||
* yield* Effect.log("message1") // Annotation is applied to this log
|
||
* yield* Effect.log("message2") // Annotation is applied to this log
|
||
* }).pipe(Effect.scoped, Effect.andThen(Effect.log("no annotations again")))
|
||
*
|
||
* Effect.runFork(program)
|
||
* // timestamp=... level=INFO fiber=#0 message="no annotations"
|
||
* // timestamp=... level=INFO fiber=#0 message=message1 key=value
|
||
* // timestamp=... level=INFO fiber=#0 message=message2 key=value
|
||
* // timestamp=... level=INFO fiber=#0 message="no annotations again"
|
||
* ```
|
||
*
|
||
* @see {@link annotateLogs} to add custom annotations to log entries generated within an effect.
|
||
*
|
||
* @since 3.1.0
|
||
* @category Logging
|
||
*/
|
||
const annotateLogsScoped = exports.annotateLogsScoped = fiberRuntime.annotateLogsScoped;
|
||
/**
|
||
* Retrieves the current log annotations for the current scope.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function provides access to the log annotations associated with the
|
||
* current scope. Log annotations are key-value pairs that provide additional
|
||
* context to log entries. They are often used to add metadata such as tags,
|
||
* identifiers, or extra debugging information to logs.
|
||
*
|
||
* By using this function, you can inspect or utilize the annotations applied to
|
||
* the current scope, making it easier to trace and debug specific sections of
|
||
* your application.
|
||
*
|
||
* @see {@link annotateLogs} to add custom annotations to log entries generated within an effect.
|
||
* @see {@link annotateLogsScoped} to add log annotations with a limited scope.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Logging
|
||
*/
|
||
const logAnnotations = exports.logAnnotations = effect.logAnnotations;
|
||
/**
|
||
* Configures whether child fibers will log unhandled errors and at what log
|
||
* level.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to control whether unhandled errors from child
|
||
* fibers are logged and to specify the log level for these errors. By default,
|
||
* unhandled errors are reported via the logger. However, using this function,
|
||
* you can choose to suppress these logs by passing `Option.none` or adjust the
|
||
* log level to a specific severity, such as `Error`, `Warning`, or `Info`.
|
||
*
|
||
* This configuration is scoped to the effect it is applied to, meaning the
|
||
* changes only apply to the child fibers created within that effect's context.
|
||
* It is especially useful when you want to reduce noise in logs or prioritize
|
||
* certain types of errors.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Fiber, LogLevel, Option } from "effect"
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* const fiber = yield* Effect.fork(Effect.fail("Unhandled error!"))
|
||
* yield* Fiber.join(fiber)
|
||
* })
|
||
*
|
||
* Effect.runFork(program.pipe(Effect.withUnhandledErrorLogLevel(Option.some(LogLevel.Error))))
|
||
* // Output:
|
||
* // timestamp=... level=ERROR fiber=#1 message="Fiber terminated with an unhandled error" cause="Error: Unhandled error!"
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Logging
|
||
*/
|
||
const withUnhandledErrorLogLevel = exports.withUnhandledErrorLogLevel = core.withUnhandledErrorLogLevel;
|
||
/**
|
||
* Conditionally executes an effect based on the specified log level and currently enabled log level.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function runs the provided effect only if the specified log level is
|
||
* enabled. If the log level is enabled, the effect is executed and its result
|
||
* is wrapped in `Some`. If the log level is not enabled, the effect is not
|
||
* executed and `None` is returned.
|
||
*
|
||
* This function is useful for conditionally executing logging-related effects
|
||
* or other operations that depend on the current log level configuration.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Logger, LogLevel } from "effect"
|
||
*
|
||
* const program = Effect.gen(function* () {
|
||
* yield* Effect.whenLogLevel(Effect.logTrace("message1"), LogLevel.Trace); // returns `None`
|
||
* yield* Effect.whenLogLevel(Effect.logDebug("message2"), LogLevel.Debug); // returns `Some`
|
||
* }).pipe(Logger.withMinimumLogLevel(LogLevel.Debug));
|
||
*
|
||
* Effect.runFork(program)
|
||
* // timestamp=... level=DEBUG fiber=#0 message=message2
|
||
* ```
|
||
*
|
||
* @see {@link FiberRef.currentMinimumLogLevel} to retrieve the current minimum log level.
|
||
*
|
||
* @since 3.13.0
|
||
* @category Logging
|
||
*/
|
||
const whenLogLevel = exports.whenLogLevel = fiberRuntime.whenLogLevel;
|
||
/**
|
||
* Converts an effect's failure into a fiber termination, removing the error
|
||
* from the effect's type.
|
||
*
|
||
* **Details**
|
||
*
|
||
* The `orDie` function is used when you encounter errors that you do not want
|
||
* to handle or recover from. It removes the error type from the effect and
|
||
* ensures that any failure will terminate the fiber. This is useful for
|
||
* propagating failures as defects, signaling that they should not be handled
|
||
* within the effect.
|
||
*
|
||
* **When to Use*
|
||
*
|
||
* Use `orDie` when failures should be treated as unrecoverable defects and no
|
||
* error handling is required.
|
||
*
|
||
* **Example** (Propagating an Error as a Defect)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const divide = (a: number, b: number) =>
|
||
* b === 0
|
||
* ? Effect.fail(new Error("Cannot divide by zero"))
|
||
* : Effect.succeed(a / b)
|
||
*
|
||
* // ┌─── Effect<number, never, never>
|
||
* // ▼
|
||
* const program = Effect.orDie(divide(1, 0))
|
||
*
|
||
* Effect.runPromise(program).catch(console.error)
|
||
* // Output:
|
||
* // (FiberFailure) Error: Cannot divide by zero
|
||
* // ...stack trace...
|
||
* ```
|
||
*
|
||
* @see {@link orDieWith} if you need to customize the error.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Converting Failures to Defects
|
||
*/
|
||
const orDie = exports.orDie = core.orDie;
|
||
/**
|
||
* Converts an effect's failure into a fiber termination with a custom error.
|
||
*
|
||
* **Details**
|
||
*
|
||
* The `orDieWith` function behaves like {@link orDie}, but it allows you to provide a mapping
|
||
* function to transform the error before terminating the fiber. This is useful for cases where
|
||
* you want to include a more detailed or user-friendly error when the failure is propagated
|
||
* as a defect.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use `orDieWith` when failures should terminate the fiber as defects, and you want to customize
|
||
* the error for clarity or debugging purposes.
|
||
*
|
||
* **Example** (Customizing Defect)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const divide = (a: number, b: number) =>
|
||
* b === 0
|
||
* ? Effect.fail(new Error("Cannot divide by zero"))
|
||
* : Effect.succeed(a / b)
|
||
*
|
||
* // ┌─── Effect<number, never, never>
|
||
* // ▼
|
||
* const program = Effect.orDieWith(
|
||
* divide(1, 0),
|
||
* (error) => new Error(`defect: ${error.message}`)
|
||
* )
|
||
*
|
||
* Effect.runPromise(program).catch(console.error)
|
||
* // Output:
|
||
* // (FiberFailure) Error: defect: Cannot divide by zero
|
||
* // ...stack trace...
|
||
* ```
|
||
*
|
||
* @see {@link orDie} if you don't need to customize the error.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Converting Failures to Defects
|
||
*/
|
||
const orDieWith = exports.orDieWith = core.orDieWith;
|
||
/**
|
||
* Attempts one effect, and if it fails, falls back to another effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to try executing an effect, and if it fails
|
||
* (produces an error), a fallback effect is executed instead. The fallback
|
||
* effect is defined as a lazy argument, meaning it will only be evaluated if
|
||
* the first effect fails. This provides a way to recover from errors by
|
||
* specifying an alternative path of execution.
|
||
*
|
||
* The error type of the resulting effect will be that of the fallback effect,
|
||
* as the first effect's error is replaced when the fallback is executed.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const success = Effect.succeed("success")
|
||
* const failure = Effect.fail("failure")
|
||
* const fallback = Effect.succeed("fallback")
|
||
*
|
||
* // Try the success effect first, fallback is not used
|
||
* const program1 = Effect.orElse(success, () => fallback)
|
||
* console.log(Effect.runSync(program1))
|
||
* // Output: "success"
|
||
*
|
||
* // Try the failure effect first, fallback is used
|
||
* const program2 = Effect.orElse(failure, () => fallback)
|
||
* console.log(Effect.runSync(program2))
|
||
* // Output: "fallback"
|
||
* ```
|
||
*
|
||
* @see {@link catchAll} if you need to access the error in the fallback effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Fallback
|
||
*/
|
||
const orElse = exports.orElse = core.orElse;
|
||
/**
|
||
* Replaces the failure of an effect with a custom failure value.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to handle the failure of an effect by replacing it
|
||
* with a predefined failure value. If the effect fails, the new failure value
|
||
* provided by the `evaluate` function will be returned instead of the original
|
||
* failure. If the effect succeeds, the original success value is returned
|
||
* unchanged.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is particularly useful when you want to standardize error handling or
|
||
* provide a consistent failure value for specific operations. It simplifies
|
||
* error management by ensuring that all failures are replaced with a controlled
|
||
* alternative.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const validate = (age: number): Effect.Effect<number, string> => {
|
||
* if (age < 0) {
|
||
* return Effect.fail("NegativeAgeError")
|
||
* } else if (age < 18) {
|
||
* return Effect.fail("IllegalAgeError")
|
||
* } else {
|
||
* return Effect.succeed(age)
|
||
* }
|
||
* }
|
||
*
|
||
* const program = Effect.orElseFail(validate(-1), () => "invalid age")
|
||
*
|
||
* console.log(Effect.runSyncExit(program))
|
||
* // Output:
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: { _id: 'Cause', _tag: 'Fail', failure: 'invalid age' }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @see {@link mapError} if you need to access the error to transform it.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Fallback
|
||
*/
|
||
const orElseFail = exports.orElseFail = effect.orElseFail;
|
||
/**
|
||
* Ensures the effect always succeeds by replacing failures with a default
|
||
* success value.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function transforms an effect that may fail into one that cannot fail by
|
||
* replacing any failure with a provided success value. If the original effect
|
||
* fails, the failure is "swallowed," and the specified success value is
|
||
* returned instead. If the original effect succeeds, its value remains
|
||
* unchanged.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is especially useful for providing default values in case of failure,
|
||
* ensuring that an effect always completes successfully. By using this
|
||
* function, you can avoid the need for complex error handling and guarantee a
|
||
* fallback result.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const validate = (age: number): Effect.Effect<number, string> => {
|
||
* if (age < 0) {
|
||
* return Effect.fail("NegativeAgeError")
|
||
* } else if (age < 18) {
|
||
* return Effect.fail("IllegalAgeError")
|
||
* } else {
|
||
* return Effect.succeed(age)
|
||
* }
|
||
* }
|
||
*
|
||
* const program = Effect.orElseSucceed(validate(-1), () => 18)
|
||
*
|
||
* console.log(Effect.runSyncExit(program))
|
||
* // Output:
|
||
* // { _id: 'Exit', _tag: 'Success', value: 18 }
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Fallback
|
||
*/
|
||
const orElseSucceed = exports.orElseSucceed = effect.orElseSucceed;
|
||
/**
|
||
* Runs a sequence of effects and returns the result of the first successful
|
||
* one.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to execute a collection of effects in sequence,
|
||
* stopping at the first success. If an effect succeeds, its result is
|
||
* immediately returned, and no further effects in the sequence are executed.
|
||
* However, if all the effects fail, the function will return the error of the
|
||
* last effect.
|
||
*
|
||
* The execution is sequential, meaning that effects are evaluated one at a time
|
||
* in the order they are provided. This ensures predictable behavior and avoids
|
||
* unnecessary computations.
|
||
*
|
||
* If the collection of effects is empty, an `IllegalArgumentException` is
|
||
* thrown, indicating that the operation is invalid without any effects to try.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is particularly useful when you have multiple fallback strategies or
|
||
* alternative sources to obtain a result, such as attempting multiple APIs,
|
||
* retrieving configurations, or accessing resources in a prioritized manner.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* interface Config {
|
||
* host: string
|
||
* port: number
|
||
* apiKey: string
|
||
* }
|
||
*
|
||
* // Create a configuration object with sample values
|
||
* const makeConfig = (name: string): Config => ({
|
||
* host: `${name}.example.com`,
|
||
* port: 8080,
|
||
* apiKey: "12345-abcde"
|
||
* })
|
||
*
|
||
* // Simulate retrieving configuration from a remote node
|
||
* const remoteConfig = (name: string): Effect.Effect<Config, Error> =>
|
||
* Effect.gen(function* () {
|
||
* // Simulate node3 being the only one with available config
|
||
* if (name === "node3") {
|
||
* yield* Console.log(`Config for ${name} found`)
|
||
* return makeConfig(name)
|
||
* } else {
|
||
* yield* Console.log(`Unavailable config for ${name}`)
|
||
* return yield* Effect.fail(new Error(`Config not found for ${name}`))
|
||
* }
|
||
* })
|
||
*
|
||
* // Define the master configuration and potential fallback nodes
|
||
* const masterConfig = remoteConfig("master")
|
||
* const nodeConfigs = ["node1", "node2", "node3", "node4"].map(remoteConfig)
|
||
*
|
||
* // Attempt to find a working configuration,
|
||
* // starting with the master and then falling back to other nodes
|
||
* const config = Effect.firstSuccessOf([masterConfig, ...nodeConfigs])
|
||
*
|
||
* // Run the effect to retrieve the configuration
|
||
* const result = Effect.runSync(config)
|
||
*
|
||
* console.log(result)
|
||
* // Output:
|
||
* // Unavailable config for master
|
||
* // Unavailable config for node1
|
||
* // Unavailable config for node2
|
||
* // Config for node3 found
|
||
* // { host: 'node3.example.com', port: 8080, apiKey: '12345-abcde' }
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Fallback
|
||
*/
|
||
const firstSuccessOf = exports.firstSuccessOf = effect.firstSuccessOf;
|
||
/**
|
||
* Retrieves the `Random` service from the context.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Random
|
||
*/
|
||
const random = exports.random = effect.random;
|
||
/**
|
||
* Retrieves the `Random` service from the context and uses it to run the
|
||
* specified effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Random
|
||
*/
|
||
const randomWith = exports.randomWith = defaultServices.randomWith;
|
||
/**
|
||
* Executes the specified effect with the specified implementation of the
|
||
* `Random` service.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Random
|
||
*/
|
||
const withRandom = exports.withRandom = defaultServices.withRandom;
|
||
/**
|
||
* Sets the implementation of the `Random` service to the specified value and
|
||
* restores it to its original value when the scope is closed.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Random
|
||
*/
|
||
const withRandomScoped = exports.withRandomScoped = fiberRuntime.withRandomScoped;
|
||
/**
|
||
* Returns an effect that accesses the runtime, which can be used to (unsafely)
|
||
* execute tasks.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This is useful for integration with legacy code that must call back into
|
||
* Effect code.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Runtime
|
||
*/
|
||
const runtime = exports.runtime = runtime_.runtime;
|
||
/**
|
||
* Retrieves an effect that succeeds with the current runtime flags, which
|
||
* govern behavior and features of the runtime system.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Runtime
|
||
*/
|
||
const getRuntimeFlags = exports.getRuntimeFlags = core.runtimeFlags;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Runtime
|
||
*/
|
||
const patchRuntimeFlags = exports.patchRuntimeFlags = core.updateRuntimeFlags;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Runtime
|
||
*/
|
||
const withRuntimeFlagsPatch = exports.withRuntimeFlagsPatch = core.withRuntimeFlags;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Runtime
|
||
*/
|
||
const withRuntimeFlagsPatchScoped = exports.withRuntimeFlagsPatchScoped = fiberRuntime.withRuntimeFlagsScoped;
|
||
/**
|
||
* Tags each metric in an effect with specific key-value pairs.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to tag all metrics in an effect with a set of
|
||
* key-value pairs or a single key-value pair. Tags help you add metadata to
|
||
* metrics, making it easier to filter and categorize them in monitoring
|
||
* systems. The provided tags will apply to all metrics generated within the
|
||
* effect's scope.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Metrics
|
||
*/
|
||
const tagMetrics = exports.tagMetrics = effect.tagMetrics;
|
||
/**
|
||
* Adds labels to metrics within an effect using `MetricLabel` objects.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to label metrics using `MetricLabel` objects. Labels
|
||
* help add structured metadata to metrics for categorization and filtering in
|
||
* monitoring systems. The provided labels will apply to all metrics within the
|
||
* effect's execution.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Metrics
|
||
*/
|
||
const labelMetrics = exports.labelMetrics = effect.labelMetrics;
|
||
/**
|
||
* Tags metrics within a scope with a specific key-value pair.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function tags all metrics within a scope with the provided key-value
|
||
* pair. Once the scope is closed, the tag is automatically removed. This is
|
||
* useful for applying temporary context-specific tags to metrics during scoped
|
||
* operations.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Metrics
|
||
*/
|
||
const tagMetricsScoped = exports.tagMetricsScoped = fiberRuntime.tagMetricsScoped;
|
||
/**
|
||
* Adds labels to metrics within a scope using `MetricLabel` objects.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to apply labels to all metrics generated within a
|
||
* specific scope using an array of `MetricLabel` objects. These labels provide
|
||
* additional metadata to metrics, which can be used for categorization,
|
||
* filtering, or monitoring purposes. The labels are scoped and will be removed
|
||
* automatically once the scope is closed, ensuring they are only applied
|
||
* temporarily within the defined context.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Metrics
|
||
*/
|
||
const labelMetricsScoped = exports.labelMetricsScoped = fiberRuntime.labelMetricsScoped;
|
||
/**
|
||
* Retrieves the metric labels associated with the current scope.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Metrics
|
||
*/
|
||
const metricLabels = exports.metricLabels = core.metricLabels;
|
||
/**
|
||
* Associates a metric with the current effect, updating it as the effect progresses.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Metrics
|
||
*/
|
||
const withMetric = exports.withMetric = effect.withMetric;
|
||
/**
|
||
* Unsafely creates a new Semaphore.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Semaphore
|
||
*/
|
||
const unsafeMakeSemaphore = exports.unsafeMakeSemaphore = circular.unsafeMakeSemaphore;
|
||
/**
|
||
* Creates a new semaphore with the specified number of permits.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function initializes a semaphore that controls concurrent access to a
|
||
* shared resource. The number of permits determines how many tasks can access
|
||
* the resource concurrently.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // Create a semaphore with 3 permits
|
||
* const mutex = Effect.makeSemaphore(3)
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Semaphore
|
||
*/
|
||
const makeSemaphore = exports.makeSemaphore = circular.makeSemaphore;
|
||
/**
|
||
* @category Latch
|
||
* @since 3.8.0
|
||
*/
|
||
const unsafeMakeLatch = exports.unsafeMakeLatch = circular.unsafeMakeLatch;
|
||
/**
|
||
* Creates a new `Latch`, starting in the specified state.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function initializes a `Latch` safely, ensuring proper runtime
|
||
* guarantees. By default, the latch starts in the closed state.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Console, Effect } from "effect"
|
||
*
|
||
* const program = Effect.gen(function*() {
|
||
* // Create a latch, starting in the closed state
|
||
* const latch = yield* Effect.makeLatch(false)
|
||
*
|
||
* // Fork a fiber that logs "open sesame" when the latch is opened
|
||
* const fiber = yield* Console.log("open sesame").pipe(
|
||
* latch.whenOpen,
|
||
* Effect.fork
|
||
* )
|
||
*
|
||
* yield* Effect.sleep("1 second")
|
||
*
|
||
* // Open the latch
|
||
* yield* latch.open
|
||
* yield* fiber.await
|
||
* })
|
||
*
|
||
* Effect.runFork(program)
|
||
* // Output: open sesame (after 1 second)
|
||
* ```
|
||
*
|
||
* @category Latch
|
||
* @since 3.8.0
|
||
*/
|
||
const makeLatch = exports.makeLatch = circular.makeLatch;
|
||
/**
|
||
* Runs an effect in the background, returning a fiber that can be observed or
|
||
* interrupted.
|
||
*
|
||
* Unless you specifically need a `Promise` or synchronous operation, `runFork`
|
||
* is a good default choice.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function is the foundational way to execute an effect in the background.
|
||
* It creates a "fiber," a lightweight, cooperative thread of execution that can
|
||
* be observed (to access its result), interrupted, or joined. Fibers are useful
|
||
* for concurrent programming and allow effects to run independently of the main
|
||
* program flow.
|
||
*
|
||
* Once the effect is running in a fiber, you can monitor its progress, cancel
|
||
* it if necessary, or retrieve its result when it completes. If the effect
|
||
* fails, the fiber will propagate the failure, which you can observe and
|
||
* handle.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you need to run an effect in the background,
|
||
* especially if the effect is long-running or performs periodic tasks. It's
|
||
* suitable for tasks that need to run independently but might still need
|
||
* observation or management, like logging, monitoring, or scheduled tasks.
|
||
*
|
||
* This function is ideal if you don't need the result immediately or if the
|
||
* effect is part of a larger concurrent workflow.
|
||
*
|
||
* **Example** (Running an Effect in the Background)
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console, Schedule, Fiber } from "effect"
|
||
*
|
||
* // ┌─── Effect<number, never, never>
|
||
* // ▼
|
||
* const program = Effect.repeat(
|
||
* Console.log("running..."),
|
||
* Schedule.spaced("200 millis")
|
||
* )
|
||
*
|
||
* // ┌─── RuntimeFiber<number, never>
|
||
* // ▼
|
||
* const fiber = Effect.runFork(program)
|
||
*
|
||
* setTimeout(() => {
|
||
* Effect.runFork(Fiber.interrupt(fiber))
|
||
* }, 500)
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Running Effects
|
||
*/
|
||
const runFork = exports.runFork = runtime_.unsafeForkEffect;
|
||
/**
|
||
* Executes an effect asynchronously and handles the result using a callback.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function runs an effect asynchronously and passes the result (`Exit`) to
|
||
* a specified callback. The callback is invoked with the outcome of the effect:
|
||
* - On success, the callback receives the successful result.
|
||
* - On failure, the callback receives the failure information.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* This function is effectful and should only be invoked at the edges of your
|
||
* program.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Running Effects
|
||
*/
|
||
const runCallback = exports.runCallback = runtime_.unsafeRunEffect;
|
||
/**
|
||
* Executes an effect and returns the result as a `Promise`.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function runs an effect and converts its result into a `Promise`. If the
|
||
* effect succeeds, the `Promise` will resolve with the successful result. If
|
||
* the effect fails, the `Promise` will reject with an error, which includes the
|
||
* failure details of the effect.
|
||
*
|
||
* The optional `options` parameter allows you to pass an `AbortSignal` for
|
||
* cancellation, enabling more fine-grained control over asynchronous tasks.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you need to execute an effect and work with its result
|
||
* in a promise-based system, such as when integrating with third-party
|
||
* libraries that expect `Promise` results.
|
||
*
|
||
* **Example** (Running a Successful Effect as a Promise)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* Effect.runPromise(Effect.succeed(1)).then(console.log)
|
||
* // Output: 1
|
||
* ```
|
||
*
|
||
* **Example** (Handling a Failing Effect as a Rejected Promise)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* Effect.runPromise(Effect.fail("my error")).catch(console.error)
|
||
* // Output:
|
||
* // (FiberFailure) Error: my error
|
||
* ```
|
||
*
|
||
* @see {@link runPromiseExit} for a version that returns an `Exit` type instead
|
||
* of rejecting.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Running Effects
|
||
*/
|
||
const runPromise = exports.runPromise = runtime_.unsafeRunPromiseEffect;
|
||
/**
|
||
* Runs an effect and returns a `Promise` that resolves to an `Exit`,
|
||
* representing the outcome.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function executes an effect and resolves to an `Exit` object. The `Exit`
|
||
* type provides detailed information about the result of the effect:
|
||
* - If the effect succeeds, the `Exit` will be of type `Success` and include
|
||
* the value produced by the effect.
|
||
* - If the effect fails, the `Exit` will be of type `Failure` and contain a
|
||
* `Cause` object, detailing the failure.
|
||
*
|
||
* Using this function allows you to examine both successful results and failure
|
||
* cases in a unified way, while still leveraging `Promise` for handling the
|
||
* asynchronous behavior of the effect.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you need to understand the outcome of an effect,
|
||
* whether it succeeded or failed, and want to work with this result using
|
||
* `Promise` syntax. This is particularly useful when integrating with systems
|
||
* that rely on promises but need more detailed error handling than a simple
|
||
* rejection.
|
||
*
|
||
* **Example** (Handling Results as Exit)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // Execute a successful effect and get the Exit result as a Promise
|
||
* Effect.runPromiseExit(Effect.succeed(1)).then(console.log)
|
||
* // Output:
|
||
* // {
|
||
* // _id: "Exit",
|
||
* // _tag: "Success",
|
||
* // value: 1
|
||
* // }
|
||
*
|
||
* // Execute a failing effect and get the Exit result as a Promise
|
||
* Effect.runPromiseExit(Effect.fail("my error")).then(console.log)
|
||
* // Output:
|
||
* // {
|
||
* // _id: "Exit",
|
||
* // _tag: "Failure",
|
||
* // cause: {
|
||
* // _id: "Cause",
|
||
* // _tag: "Fail",
|
||
* // failure: "my error"
|
||
* // }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Running Effects
|
||
*/
|
||
const runPromiseExit = exports.runPromiseExit = runtime_.unsafeRunPromiseExitEffect;
|
||
/**
|
||
* Executes an effect synchronously, running it immediately and returning the
|
||
* result.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function evaluates the provided effect synchronously, returning its
|
||
* result directly. It is ideal for effects that do not fail or include
|
||
* asynchronous operations. If the effect does fail or involves async tasks, it
|
||
* will throw an error. Execution stops at the point of failure or asynchronous
|
||
* operation, making it unsuitable for effects that require asynchronous
|
||
* handling.
|
||
*
|
||
* **Important**: Attempting to run effects that involve asynchronous operations
|
||
* or failures will result in exceptions being thrown, so use this function with
|
||
* care for purely synchronous and error-free effects.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when:
|
||
* - You are sure that the effect will not fail or involve asynchronous
|
||
* operations.
|
||
* - You need a direct, synchronous result from the effect.
|
||
* - You are working within a context where asynchronous effects are not
|
||
* allowed.
|
||
*
|
||
* Avoid using this function for effects that can fail or require asynchronous
|
||
* handling. For such cases, consider using {@link runPromise} or
|
||
* {@link runSyncExit}.
|
||
*
|
||
* **Example** (Synchronous Logging)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const program = Effect.sync(() => {
|
||
* console.log("Hello, World!")
|
||
* return 1
|
||
* })
|
||
*
|
||
* const result = Effect.runSync(program)
|
||
* // Output: Hello, World!
|
||
*
|
||
* console.log(result)
|
||
* // Output: 1
|
||
* ```
|
||
*
|
||
* **Example** (Incorrect Usage with Failing or Async Effects)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* try {
|
||
* // Attempt to run an effect that fails
|
||
* Effect.runSync(Effect.fail("my error"))
|
||
* } catch (e) {
|
||
* console.error(e)
|
||
* }
|
||
* // Output:
|
||
* // (FiberFailure) Error: my error
|
||
*
|
||
* try {
|
||
* // Attempt to run an effect that involves async work
|
||
* Effect.runSync(Effect.promise(() => Promise.resolve(1)))
|
||
* } catch (e) {
|
||
* console.error(e)
|
||
* }
|
||
* // Output:
|
||
* // (FiberFailure) AsyncFiberException: Fiber #0 cannot be resolved synchronously. This is caused by using runSync on an effect that performs async work
|
||
* ```
|
||
*
|
||
* @see {@link runSyncExit} for a version that returns an `Exit` type instead of
|
||
* throwing an error.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Running Effects
|
||
*/
|
||
const runSync = exports.runSync = runtime_.unsafeRunSyncEffect;
|
||
/**
|
||
* Runs an effect synchronously and returns the result as an `Exit` type.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function executes the provided effect synchronously and returns an `Exit`
|
||
* type that encapsulates the outcome of the effect:
|
||
* - If the effect succeeds, the result is wrapped in a `Success`.
|
||
* - If the effect fails, it returns a `Failure` containing a `Cause` that explains
|
||
* the failure.
|
||
*
|
||
* If the effect involves asynchronous operations, this function will return a `Failure`
|
||
* with a `Die` cause, indicating that it cannot resolve the effect synchronously.
|
||
* This makes the function suitable for use only with effects that are synchronous
|
||
* in nature.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when:
|
||
* - You want to handle both success and failure outcomes in a structured way using the `Exit` type.
|
||
* - You are working with effects that are purely synchronous and do not involve asynchronous operations.
|
||
* - You need to debug or inspect failures, including their causes, in a detailed manner.
|
||
*
|
||
* Avoid using this function for effects that involve asynchronous operations, as it will fail with a `Die` cause.
|
||
*
|
||
* **Example** (Handling Results as Exit)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* console.log(Effect.runSyncExit(Effect.succeed(1)))
|
||
* // Output:
|
||
* // {
|
||
* // _id: "Exit",
|
||
* // _tag: "Success",
|
||
* // value: 1
|
||
* // }
|
||
*
|
||
* console.log(Effect.runSyncExit(Effect.fail("my error")))
|
||
* // Output:
|
||
* // {
|
||
* // _id: "Exit",
|
||
* // _tag: "Failure",
|
||
* // cause: {
|
||
* // _id: "Cause",
|
||
* // _tag: "Fail",
|
||
* // failure: "my error"
|
||
* // }
|
||
* // }
|
||
* ```
|
||
*
|
||
* **Example** (Asynchronous Operation Resulting in Die)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* console.log(Effect.runSyncExit(Effect.promise(() => Promise.resolve(1))))
|
||
* // Output:
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: {
|
||
* // _id: 'Cause',
|
||
* // _tag: 'Die',
|
||
* // defect: [Fiber #0 cannot be resolved synchronously. This is caused by using runSync on an effect that performs async work] {
|
||
* // fiber: [FiberRuntime],
|
||
* // _tag: 'AsyncFiberException',
|
||
* // name: 'AsyncFiberException'
|
||
* // }
|
||
* // }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Running Effects
|
||
*/
|
||
const runSyncExit = exports.runSyncExit = runtime_.unsafeRunSyncExitEffect;
|
||
/**
|
||
* Combines multiple effects and accumulates both successes and failures.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to combine multiple effects, continuing through all
|
||
* effects even if some of them fail. Unlike other functions that stop execution
|
||
* upon encountering an error, this function collects all errors into a `Cause`.
|
||
* The final result includes all successes and the accumulated failures.
|
||
*
|
||
* By default, effects are executed sequentially, but you can control
|
||
* concurrency and batching behavior using the `options` parameter. This
|
||
* provides flexibility in scenarios where you want to maximize performance or
|
||
* ensure specific ordering.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Console } from "effect"
|
||
*
|
||
* const task1 = Console.log("task1").pipe(Effect.as(1))
|
||
* const task2 = Effect.fail("Oh uh!").pipe(Effect.as(2))
|
||
* const task3 = Console.log("task2").pipe(Effect.as(3))
|
||
* const task4 = Effect.fail("Oh no!").pipe(Effect.as(4))
|
||
*
|
||
* const program = task1.pipe(
|
||
* Effect.validate(task2),
|
||
* Effect.validate(task3),
|
||
* Effect.validate(task4)
|
||
* )
|
||
*
|
||
* Effect.runPromiseExit(program).then(console.log)
|
||
* // Output:
|
||
* // task1
|
||
* // task2
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: {
|
||
* // _id: 'Cause',
|
||
* // _tag: 'Sequential',
|
||
* // left: { _id: 'Cause', _tag: 'Fail', failure: 'Oh uh!' },
|
||
* // right: { _id: 'Cause', _tag: 'Fail', failure: 'Oh no!' }
|
||
* // }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @see {@link zip} for a version that stops at the first error.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error Accumulation
|
||
*/
|
||
const validate = exports.validate = fiberRuntime.validate;
|
||
/**
|
||
* Sequentially combines two effects using a specified combiner function while
|
||
* accumulating errors.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function combines two effects, `self` and `that`, into a single effect
|
||
* by applying the provided combiner function to their results. If both effects
|
||
* succeed, the combiner function is applied to their results to produce the
|
||
* final value. If either effect fails, the failures are accumulated into a
|
||
* combined `Cause`.
|
||
*
|
||
* By default, effects are executed sequentially. However, the execution mode
|
||
* can be controlled using the `options` parameter to enable concurrency,
|
||
* batching, or customized finalizer behavior.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Error Accumulation
|
||
*/
|
||
const validateWith = exports.validateWith = fiberRuntime.validateWith;
|
||
/**
|
||
* Combines two effects into a single effect, producing a tuple of their
|
||
* results.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function combines two effects, `self` and `that`, into one. It executes
|
||
* the first effect (`self`) and then the second effect (`that`), collecting
|
||
* their results into a tuple. Both effects must succeed for the resulting
|
||
* effect to succeed. If either effect fails, the entire operation fails.
|
||
*
|
||
* By default, the effects are executed sequentially. If the `concurrent` option
|
||
* is set to `true`, the effects will run concurrently, potentially improving
|
||
* performance for independent operations.
|
||
*
|
||
* **Example** (Combining Two Effects Sequentially)
|
||
*
|
||
* ```ts
|
||
* 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"))
|
||
* )
|
||
*
|
||
* // Combine the two effects together
|
||
* //
|
||
* // ┌─── Effect<[number, string], never, never>
|
||
* // ▼
|
||
* const program = Effect.zip(task1, task2)
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output:
|
||
* // timestamp=... level=INFO fiber=#0 message="task1 done"
|
||
* // timestamp=... level=INFO fiber=#0 message="task2 done"
|
||
* // [ 1, 'hello' ]
|
||
* ```
|
||
*
|
||
* **Example** (Combining Two Effects Concurrently)
|
||
*
|
||
* ```ts
|
||
* 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"))
|
||
* )
|
||
*
|
||
* // Run both effects concurrently using the concurrent option
|
||
* const program = Effect.zip(task1, task2, { concurrent: true })
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output:
|
||
* // timestamp=... level=INFO fiber=#0 message="task2 done"
|
||
* // timestamp=... level=INFO fiber=#0 message="task1 done"
|
||
* // [ 1, 'hello' ]
|
||
* ```
|
||
*
|
||
* @see {@link zipWith} for a version that combines the results with a custom
|
||
* function.
|
||
* @see {@link validate} for a version that accumulates errors.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Zipping
|
||
*/
|
||
const zip = exports.zip = fiberRuntime.zipOptions;
|
||
/**
|
||
* Executes two effects sequentially, returning the result of the first effect
|
||
* and ignoring the result of the second.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to run two effects in sequence, where the result of
|
||
* the first effect is preserved, and the result of the second effect is
|
||
* discarded. By default, the two effects are executed sequentially. If you need
|
||
* them to run concurrently, you can pass the `{ concurrent: true }` option.
|
||
*
|
||
* The second effect will always be executed, even though its result is ignored.
|
||
* This makes it useful for cases where you want to execute an effect for its
|
||
* side effects while keeping the result of another effect.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you are only interested in the result of the first
|
||
* effect but still need to run the second effect for its side effects, such as
|
||
* logging or performing a cleanup action.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* 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 program = Effect.zipLeft(task1, task2)
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output:
|
||
* // timestamp=... level=INFO fiber=#0 message="task1 done"
|
||
* // timestamp=... level=INFO fiber=#0 message="task2 done"
|
||
* // 1
|
||
* ```
|
||
*
|
||
* @see {@link zipRight} for a version that returns the result of the second
|
||
* effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Zipping
|
||
*/
|
||
const zipLeft = exports.zipLeft = fiberRuntime.zipLeftOptions;
|
||
/**
|
||
* Executes two effects sequentially, returning the result of the second effect
|
||
* while ignoring the result of the first.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to run two effects in sequence, keeping the result
|
||
* of the second effect and discarding the result of the first. By default, the
|
||
* two effects are executed sequentially. If you need them to run concurrently,
|
||
* you can pass the `{ concurrent: true }` option.
|
||
*
|
||
* The first effect will always be executed, even though its result is ignored.
|
||
* This makes it useful for scenarios where the first effect is needed for its
|
||
* side effects, but only the result of the second effect is important.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you are only interested in the result of the second
|
||
* effect but still need to run the first effect for its side effects, such as
|
||
* initialization or setup tasks.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* 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 program = Effect.zipRight(task1, task2)
|
||
*
|
||
* Effect.runPromise(program).then(console.log)
|
||
* // Output:
|
||
* // timestamp=... level=INFO fiber=#0 message="task1 done"
|
||
* // timestamp=... level=INFO fiber=#0 message="task2 done"
|
||
* // hello
|
||
* ```
|
||
*
|
||
* @see {@link zipLeft} for a version that returns the result of the first
|
||
* effect.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Zipping
|
||
*/
|
||
const zipRight = exports.zipRight = fiberRuntime.zipRightOptions;
|
||
/**
|
||
* Combines two effects sequentially and applies a function to their results to
|
||
* produce a single value.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function runs two effects in sequence (or concurrently, if the `{
|
||
* concurrent: true }` option is provided) and combines their results using a
|
||
* provided function. Unlike {@link zip}, which returns a tuple of the results,
|
||
* this function processes the results with a custom function to produce a
|
||
* single output.
|
||
*
|
||
* **Example** (Combining Effects with a Custom Function)
|
||
*
|
||
* ```ts
|
||
* 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,
|
||
* // Combines results into a single value
|
||
* (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
|
||
*/
|
||
const zipWith = exports.zipWith = fiberRuntime.zipWithOptions;
|
||
/**
|
||
* Applies the function produced by one effect to the value produced by another effect.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function combines two effects:
|
||
* - The first effect produces a function of type `(a: A) => B`.
|
||
* - The second effect produces a value of type `A`.
|
||
*
|
||
* Once both effects complete successfully, the function is applied to the value, resulting in an effect that produces a value of type `B`.
|
||
*
|
||
* @since 2.0.0
|
||
*/
|
||
const ap = exports.ap = /*#__PURE__*/(0, _Function.dual)(2, (self, that) => zipWith(self, that, (f, a) => f(a)));
|
||
/**
|
||
* @category Requests & Batching
|
||
* @since 2.0.0
|
||
*/
|
||
const blocked = exports.blocked = core.blocked;
|
||
/**
|
||
* @category Requests & Batching
|
||
* @since 2.0.0
|
||
*/
|
||
const runRequestBlock = exports.runRequestBlock = core.runRequestBlock;
|
||
/**
|
||
* @category Requests & Batching
|
||
* @since 2.0.0
|
||
*/
|
||
const step = exports.step = core.step;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Requests & Batching
|
||
*/
|
||
const request = exports.request = /*#__PURE__*/(0, _Function.dual)(args => Request.isRequest(args[0]), query.fromRequest);
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Requests & Batching
|
||
*/
|
||
const cacheRequestResult = exports.cacheRequestResult = query.cacheRequest;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Requests & Batching
|
||
*/
|
||
const withRequestBatching = exports.withRequestBatching = core.withRequestBatching;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Requests & Batching
|
||
*/
|
||
const withRequestCaching = exports.withRequestCaching = query.withRequestCaching;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Requests & Batching
|
||
*/
|
||
const withRequestCache = exports.withRequestCache = query.withRequestCache;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const tracer = exports.tracer = effect.tracer;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const tracerWith = exports.tracerWith = defaultServices.tracerWith;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const withTracer = exports.withTracer = defaultServices.withTracer;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const withTracerScoped = exports.withTracerScoped = fiberRuntime.withTracerScoped;
|
||
/**
|
||
* Disable the tracer for the given Effect.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* Effect.succeed(42).pipe(
|
||
* Effect.withSpan("my-span"),
|
||
* // the span will not be registered with the tracer
|
||
* Effect.withTracerEnabled(false)
|
||
* )
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const withTracerEnabled = exports.withTracerEnabled = core.withTracerEnabled;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const withTracerTiming = exports.withTracerTiming = core.withTracerTiming;
|
||
/**
|
||
* Adds annotations to each span in the effect for enhanced traceability.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function lets you attach key-value annotations to all spans generated
|
||
* during the execution of an effect. Annotations provide additional context,
|
||
* such as metadata or labels, which can help you understand and debug
|
||
* asynchronous workflows more effectively.
|
||
*
|
||
* You can either pass a single key-value pair or a record of key-value pairs to
|
||
* annotate the spans. These annotations can then be visualized in tracing tools
|
||
* that support span annotations.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const annotateSpans = exports.annotateSpans = effect.annotateSpans;
|
||
/**
|
||
* Adds annotations to the currently active span for traceability.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function adds key-value annotations to the currently active span in the
|
||
* effect's trace. These annotations help provide more context about the
|
||
* operation being executed at a specific point in time. Unlike
|
||
* {@link annotateSpans}, which applies to all spans in an effect, this function
|
||
* focuses solely on the active span.
|
||
*
|
||
* You can either pass a single key-value pair or a record of key-value pairs to
|
||
* annotate the span. These annotations are useful for adding metadata to
|
||
* operations, especially in systems with detailed observability requirements.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const annotateCurrentSpan = exports.annotateCurrentSpan = effect.annotateCurrentSpan;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const currentSpan = exports.currentSpan = effect.currentSpan;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const currentParentSpan = exports.currentParentSpan = effect.currentParentSpan;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const spanAnnotations = exports.spanAnnotations = effect.spanAnnotations;
|
||
/**
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const spanLinks = exports.spanLinks = effect.spanLinks;
|
||
/**
|
||
* For all spans in this effect, add a link with the provided span.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const linkSpans = exports.linkSpans = effect.linkSpans;
|
||
/**
|
||
* Add span links to the current span.
|
||
*
|
||
* @since 3.14.0
|
||
* @category Tracing
|
||
*/
|
||
const linkSpanCurrent = exports.linkSpanCurrent = effect.linkSpanCurrent;
|
||
/**
|
||
* Create a new span for tracing.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const makeSpan = exports.makeSpan = effect.makeSpan;
|
||
/**
|
||
* Create a new span for tracing, and automatically close it when the Scope
|
||
* finalizes.
|
||
*
|
||
* The span is not added to the current span stack, so no child spans will be
|
||
* created for it.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const makeSpanScoped = exports.makeSpanScoped = fiberRuntime.makeSpanScoped;
|
||
/**
|
||
* Create a new span for tracing, and automatically close it when the effect
|
||
* completes.
|
||
*
|
||
* The span is not added to the current span stack, so no child spans will be
|
||
* created for it.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const useSpan = exports.useSpan = effect.useSpan;
|
||
/**
|
||
* Wraps the effect with a new span for tracing.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const withSpan = exports.withSpan = effect.withSpan;
|
||
/**
|
||
* Wraps a function that returns an effect with a new span for tracing.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const getTodo = Effect.functionWithSpan({
|
||
* body: (id: number) => Effect.succeed(`Got todo ${id}!`),
|
||
* options: (id) => ({
|
||
* name: `getTodo-${id}`,
|
||
* attributes: { id }
|
||
* })
|
||
* })
|
||
* ```
|
||
*
|
||
* @since 3.2.0
|
||
* @category Tracing
|
||
*/
|
||
const functionWithSpan = exports.functionWithSpan = effect.functionWithSpan;
|
||
/**
|
||
* Wraps the effect with a new span for tracing.
|
||
*
|
||
* The span is ended when the Scope is finalized.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const withSpanScoped = exports.withSpanScoped = fiberRuntime.withSpanScoped;
|
||
/**
|
||
* Adds the provided span to the current span stack.
|
||
*
|
||
* @since 2.0.0
|
||
* @category Tracing
|
||
*/
|
||
const withParentSpan = exports.withParentSpan = effect.withParentSpan;
|
||
/**
|
||
* Safely handles nullable values by creating an effect that fails for `null` or
|
||
* `undefined`.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function ensures that an input value is non-null and non-undefined
|
||
* before processing it. If the value is valid, the effect succeeds with the
|
||
* value. If the value is `null` or `undefined`, the effect fails with a
|
||
* `NoSuchElementException`. This is particularly useful for avoiding
|
||
* null-related errors by clearly separating valid values from invalid ones in
|
||
* effectful computations.
|
||
*
|
||
* The failure with `NoSuchElementException` allows you to explicitly handle
|
||
* cases where a value is expected but not provided, leading to safer and more
|
||
* predictable code.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when working with values that may be `null` or `undefined`
|
||
* and you want to ensure that only non-null values are processed. It helps
|
||
* enforce null-safety and makes error handling more explicit.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // ┌─── Effect<number, NoSuchElementException, never>
|
||
* // ▼
|
||
* const maybe1 = Effect.fromNullable(1)
|
||
*
|
||
* Effect.runPromiseExit(maybe1).then(console.log)
|
||
* // Output:
|
||
* // { _id: 'Exit', _tag: 'Success', value: 1 }
|
||
*
|
||
* // ┌─── Effect<number, NoSuchElementException, never>
|
||
* // ▼
|
||
* const maybe2 = Effect.fromNullable(null as number | null)
|
||
*
|
||
* Effect.runPromiseExit(maybe2).then(console.log)
|
||
* // Output:
|
||
* // {
|
||
* // _id: 'Exit',
|
||
* // _tag: 'Failure',
|
||
* // cause: {
|
||
* // _id: 'Cause',
|
||
* // _tag: 'Fail',
|
||
* // failure: { _tag: 'NoSuchElementException' }
|
||
* // }
|
||
* // }
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Optional Wrapping & Unwrapping
|
||
*/
|
||
const fromNullable = exports.fromNullable = effect.fromNullable;
|
||
/**
|
||
* Converts an effect that may fail with a `NoSuchElementException` into an
|
||
* effect that succeeds with an `Option`.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function transforms an effect that might fail with
|
||
* `Cause.NoSuchElementException` into an effect that succeeds with an `Option`
|
||
* type. If the original effect succeeds, its value is wrapped in `Option.some`.
|
||
* If it fails specifically due to a `NoSuchElementException`, the failure is
|
||
* mapped to `Option.none`. Other types of failures remain unchanged and are
|
||
* passed through as they are.
|
||
*
|
||
* This is useful when working with effects where you want to gracefully handle
|
||
* the absence of a value while preserving other potential failures.
|
||
*
|
||
* **When to Use**
|
||
*
|
||
* Use this function when you need to handle missing values as `Option.none`
|
||
* rather than throwing or propagating errors like `NoSuchElementException`.
|
||
* It’s ideal for scenarios where you want to explicitly represent optionality
|
||
* in a type-safe way while retaining other failure information.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* // ┌─── Effect<number, NoSuchElementException, never>
|
||
* // ▼
|
||
* const maybe1 = Effect.fromNullable(1)
|
||
*
|
||
* // ┌─── Effect<Option<number>, never, never>
|
||
* // ▼
|
||
* const option1 = Effect.optionFromOptional(maybe1)
|
||
*
|
||
* Effect.runPromise(option1).then(console.log)
|
||
* // Output: { _id: 'Option', _tag: 'Some', value: 1 }
|
||
*
|
||
* // ┌─── Effect<number, NoSuchElementException, never>
|
||
* // ▼
|
||
* const maybe2 = Effect.fromNullable(null as number | null)
|
||
*
|
||
* // ┌─── Effect<Option<number>, never, never>
|
||
* // ▼
|
||
* const option2 = Effect.optionFromOptional(maybe2)
|
||
*
|
||
* Effect.runPromise(option2).then(console.log)
|
||
* // Output: { _tag: 'None' }
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Optional Wrapping & Unwrapping
|
||
*/
|
||
const optionFromOptional = exports.optionFromOptional = effect.optionFromOptional;
|
||
/**
|
||
* Converts an `Option` of an `Effect` into an `Effect` of an `Option`.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function transforms an `Option<Effect<A, E, R>>` into an
|
||
* `Effect<Option<A>, E, R>`. If the `Option` is `None`, the resulting `Effect`
|
||
* will immediately succeed with a `None` value. If the `Option` is `Some`, the
|
||
* inner `Effect` will be executed, and its result wrapped in a `Some`.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect, Option } from "effect"
|
||
*
|
||
* // ┌─── Option<Effect<number, never, never>>
|
||
* // ▼
|
||
* const maybe = Option.some(Effect.succeed(42))
|
||
*
|
||
* // ┌─── Effect<Option<number>, never, never>
|
||
* // ▼
|
||
* const result = Effect.transposeOption(maybe)
|
||
*
|
||
* console.log(Effect.runSync(result))
|
||
* // Output: { _id: 'Option', _tag: 'Some', value: 42 }
|
||
* ```
|
||
*
|
||
* @since 3.13.0
|
||
* @category Optional Wrapping & Unwrapping
|
||
*/
|
||
const transposeOption = self => {
|
||
return option_.isNone(self) ? succeedNone : map(self.value, option_.some);
|
||
};
|
||
/**
|
||
* Applies an `Effect` on an `Option` and transposes the result.
|
||
*
|
||
* **Details**
|
||
*
|
||
* If the `Option` is `None`, the resulting `Effect` will immediately succeed with a `None` value.
|
||
* If the `Option` is `Some`, the effectful operation will be executed on the inner value, and its result wrapped in a `Some`.
|
||
*
|
||
* @example
|
||
* ```ts
|
||
* import { Effect, Option, pipe } from "effect"
|
||
*
|
||
* // ┌─── Effect<Option<number>, never, never>>
|
||
* // ▼
|
||
* const noneResult = pipe(
|
||
* Option.none(),
|
||
* Effect.transposeMapOption(() => Effect.succeed(42)) // will not be executed
|
||
* )
|
||
* console.log(Effect.runSync(noneResult))
|
||
* // Output: { _id: 'Option', _tag: 'None' }
|
||
*
|
||
* // ┌─── Effect<Option<number>, never, never>>
|
||
* // ▼
|
||
* const someSuccessResult = pipe(
|
||
* Option.some(42),
|
||
* Effect.transposeMapOption((value) => Effect.succeed(value * 2))
|
||
* )
|
||
* console.log(Effect.runSync(someSuccessResult))
|
||
* // Output: { _id: 'Option', _tag: 'Some', value: 84 }
|
||
* ```
|
||
*
|
||
* @since 3.14.0
|
||
* @category Optional Wrapping & Unwrapping
|
||
*/
|
||
exports.transposeOption = transposeOption;
|
||
const transposeMapOption = exports.transposeMapOption = /*#__PURE__*/(0, _Function.dual)(2, (self, f) => option_.isNone(self) ? succeedNone : map(f(self.value), option_.some));
|
||
const makeTagProxy = TagClass => {
|
||
const cache = new Map();
|
||
return new Proxy(TagClass, {
|
||
get(target, prop, receiver) {
|
||
if (prop in target) {
|
||
return Reflect.get(target, prop, receiver);
|
||
}
|
||
if (cache.has(prop)) {
|
||
return cache.get(prop);
|
||
}
|
||
const fn = (...args) => core.andThen(target, s => {
|
||
if (typeof s[prop] === "function") {
|
||
cache.set(prop, (...args) => core.andThen(target, s => s[prop](...args)));
|
||
return s[prop](...args);
|
||
}
|
||
cache.set(prop, core.andThen(target, s => s[prop]));
|
||
return s[prop];
|
||
});
|
||
const cn = core.andThen(target, s => s[prop]);
|
||
// @effect-diagnostics-next-line floatingEffect:off
|
||
Object.assign(fn, cn);
|
||
Object.setPrototypeOf(fn, Object.getPrototypeOf(cn));
|
||
cache.set(prop, fn);
|
||
return fn;
|
||
}
|
||
});
|
||
};
|
||
/**
|
||
* Creates a unique tag for a dependency, embedding the service's methods as
|
||
* static properties.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to define a `Tag` for a service or dependency in
|
||
* your application. The `Tag` not only acts as an identifier but also provides
|
||
* direct access to the service's methods via static properties. This makes it
|
||
* easier to access and use the service in your code without manually managing
|
||
* contexts.
|
||
*
|
||
* In the example below, the fields of the service (in this case, the `notify`
|
||
* method) are turned into static properties of the Notifications class, making
|
||
* it easier to access them.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* class Notifications extends Effect.Tag("Notifications")<
|
||
* Notifications,
|
||
* { readonly notify: (message: string) => Effect.Effect<void> }
|
||
* >() {}
|
||
*
|
||
* // Create an effect that depends on the Notifications service
|
||
* const action = Notifications.notify("Hello, world!")
|
||
* ```
|
||
*
|
||
* @since 2.0.0
|
||
* @category Context
|
||
*/
|
||
const Tag = id => () => {
|
||
const limit = Error.stackTraceLimit;
|
||
Error.stackTraceLimit = 2;
|
||
const creationError = new Error();
|
||
Error.stackTraceLimit = limit;
|
||
function TagClass() {}
|
||
Object.setPrototypeOf(TagClass, _context.TagProto);
|
||
TagClass.key = id;
|
||
Object.defineProperty(TagClass, "use", {
|
||
get() {
|
||
return body => core.andThen(this, body);
|
||
}
|
||
});
|
||
Object.defineProperty(TagClass, "stack", {
|
||
get() {
|
||
return creationError.stack;
|
||
}
|
||
});
|
||
return makeTagProxy(TagClass);
|
||
};
|
||
/**
|
||
* Simplifies the creation and management of services in Effect by defining both
|
||
* a `Tag` and a `Layer`.
|
||
*
|
||
* **Details**
|
||
*
|
||
* This function allows you to streamline the creation of services by combining
|
||
* the definition of a `Context.Tag` and a `Layer` in a single step. It supports
|
||
* various ways of providing the service implementation:
|
||
* - Using an `effect` to define the service dynamically.
|
||
* - Using `sync` or `succeed` to define the service statically.
|
||
* - Using `scoped` to create services with lifecycle management.
|
||
*
|
||
* It also allows you to specify dependencies for the service, which will be
|
||
* provided automatically when the service is used. Accessors can be optionally
|
||
* generated for the service, making it more convenient to use.
|
||
*
|
||
* **Example**
|
||
*
|
||
* ```ts
|
||
* import { Effect } from 'effect';
|
||
*
|
||
* class Prefix extends Effect.Service<Prefix>()("Prefix", {
|
||
* sync: () => ({ prefix: "PRE" })
|
||
* }) {}
|
||
*
|
||
* class Logger extends Effect.Service<Logger>()("Logger", {
|
||
* accessors: true,
|
||
* effect: Effect.gen(function* () {
|
||
* const { prefix } = yield* Prefix
|
||
* return {
|
||
* info: (message: string) =>
|
||
* Effect.sync(() => {
|
||
* console.log(`[${prefix}][${message}]`)
|
||
* })
|
||
* }
|
||
* }),
|
||
* dependencies: [Prefix.Default]
|
||
* }) {}
|
||
* ```
|
||
*
|
||
* @since 3.9.0
|
||
* @category Context
|
||
* @experimental might be up for breaking changes
|
||
*/
|
||
exports.Tag = Tag;
|
||
const Service = function () {
|
||
return function () {
|
||
const [id, maker] = arguments;
|
||
const proxy = "accessors" in maker ? maker["accessors"] : false;
|
||
const limit = Error.stackTraceLimit;
|
||
Error.stackTraceLimit = 2;
|
||
const creationError = new Error();
|
||
Error.stackTraceLimit = limit;
|
||
let patchState = "unchecked";
|
||
const TagClass = function (service) {
|
||
if (patchState === "unchecked") {
|
||
const proto = Object.getPrototypeOf(service);
|
||
if (proto === Object.prototype || proto === null) {
|
||
patchState = "plain";
|
||
} else {
|
||
const selfProto = Object.getPrototypeOf(this);
|
||
Object.setPrototypeOf(selfProto, proto);
|
||
patchState = "patched";
|
||
}
|
||
}
|
||
if (patchState === "plain") {
|
||
Object.assign(this, service);
|
||
} else if (patchState === "patched") {
|
||
Object.setPrototypeOf(service, Object.getPrototypeOf(this));
|
||
return service;
|
||
}
|
||
};
|
||
TagClass.prototype._tag = id;
|
||
Object.defineProperty(TagClass, "make", {
|
||
get() {
|
||
return service => new this(service);
|
||
}
|
||
});
|
||
Object.defineProperty(TagClass, "use", {
|
||
get() {
|
||
return body => core.andThen(this, body);
|
||
}
|
||
});
|
||
TagClass.key = id;
|
||
Object.assign(TagClass, _context.TagProto);
|
||
Object.defineProperty(TagClass, "stack", {
|
||
get() {
|
||
return creationError.stack;
|
||
}
|
||
});
|
||
const hasDeps = "dependencies" in maker && maker.dependencies.length > 0;
|
||
const layerName = hasDeps ? "DefaultWithoutDependencies" : "Default";
|
||
let layerCache;
|
||
let isFunction = false;
|
||
if ("effect" in maker) {
|
||
isFunction = typeof maker.effect === "function";
|
||
Object.defineProperty(TagClass, layerName, {
|
||
get() {
|
||
if (isFunction) {
|
||
return function () {
|
||
return layer.fromEffect(TagClass, map(maker.effect.apply(null, arguments), _ => new this(_)));
|
||
}.bind(this);
|
||
}
|
||
return layerCache ??= layer.fromEffect(TagClass, map(maker.effect, _ => new this(_)));
|
||
}
|
||
});
|
||
} else if ("scoped" in maker) {
|
||
isFunction = typeof maker.scoped === "function";
|
||
Object.defineProperty(TagClass, layerName, {
|
||
get() {
|
||
if (isFunction) {
|
||
return function () {
|
||
return layer.scoped(TagClass, map(maker.scoped.apply(null, arguments), _ => new this(_)));
|
||
}.bind(this);
|
||
}
|
||
return layerCache ??= layer.scoped(TagClass, map(maker.scoped, _ => new this(_)));
|
||
}
|
||
});
|
||
} else if ("sync" in maker) {
|
||
Object.defineProperty(TagClass, layerName, {
|
||
get() {
|
||
return layerCache ??= layer.sync(TagClass, () => new this(maker.sync()));
|
||
}
|
||
});
|
||
} else {
|
||
Object.defineProperty(TagClass, layerName, {
|
||
get() {
|
||
return layerCache ??= layer.succeed(TagClass, new this(maker.succeed));
|
||
}
|
||
});
|
||
}
|
||
if (hasDeps) {
|
||
let layerWithDepsCache;
|
||
Object.defineProperty(TagClass, "Default", {
|
||
get() {
|
||
if (isFunction) {
|
||
return function () {
|
||
return layer.provide(this.DefaultWithoutDependencies.apply(null, arguments), maker.dependencies);
|
||
};
|
||
}
|
||
return layerWithDepsCache ??= layer.provide(this.DefaultWithoutDependencies, maker.dependencies);
|
||
}
|
||
});
|
||
}
|
||
return proxy === true ? makeTagProxy(TagClass) : TagClass;
|
||
};
|
||
};
|
||
/**
|
||
* The `Effect.fn` function allows you to create traced functions that return an
|
||
* effect. It provides two key features:
|
||
*
|
||
* - **Stack traces with location details** if an error occurs.
|
||
* - **Automatic span creation** for tracing when a span name is provided.
|
||
*
|
||
* If a span name is passed as the first argument, the function's execution is
|
||
* tracked using that name. If no name is provided, stack tracing still works,
|
||
* but spans are not created.
|
||
*
|
||
* A function can be defined using either:
|
||
*
|
||
* - A generator function, allowing the use of `yield*` for effect composition.
|
||
* - A regular function that returns an `Effect`.
|
||
*
|
||
* **Example** (Creating a Traced Function with a Span Name)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const myfunc = Effect.fn("myspan")(function* <N extends number>(n: N) {
|
||
* yield* Effect.annotateCurrentSpan("n", n) // Attach metadata to the span
|
||
* console.log(`got: ${n}`)
|
||
* yield* Effect.fail(new Error("Boom!")) // Simulate failure
|
||
* })
|
||
*
|
||
* Effect.runFork(myfunc(100).pipe(Effect.catchAllCause(Effect.logError)))
|
||
* // Output:
|
||
* // got: 100
|
||
* // timestamp=... level=ERROR fiber=#0 cause="Error: Boom!
|
||
* // at <anonymous> (/.../index.ts:6:22) <= Raise location
|
||
* // at myspan (/.../index.ts:3:23) <= Definition location
|
||
* // at myspan (/.../index.ts:9:16)" <= Call location
|
||
* ```
|
||
*
|
||
* `Effect.fn` automatically creates spans. The spans capture information about
|
||
* the function execution, including metadata and error details.
|
||
*
|
||
* **Example** (Exporting Spans to the Console)
|
||
*
|
||
* ```ts skip-type-checking
|
||
* import { Effect } from "effect"
|
||
* import { NodeSdk } from "@effect/opentelemetry"
|
||
* import {
|
||
* ConsoleSpanExporter,
|
||
* BatchSpanProcessor
|
||
* } from "@opentelemetry/sdk-trace-base"
|
||
*
|
||
* const myfunc = Effect.fn("myspan")(function* <N extends number>(n: N) {
|
||
* yield* Effect.annotateCurrentSpan("n", n)
|
||
* console.log(`got: ${n}`)
|
||
* yield* Effect.fail(new Error("Boom!"))
|
||
* })
|
||
*
|
||
* const program = myfunc(100)
|
||
*
|
||
* const NodeSdkLive = NodeSdk.layer(() => ({
|
||
* resource: { serviceName: "example" },
|
||
* // Export span data to the console
|
||
* spanProcessor: new BatchSpanProcessor(new ConsoleSpanExporter())
|
||
* }))
|
||
*
|
||
* Effect.runFork(program.pipe(Effect.provide(NodeSdkLive)))
|
||
* // Output:
|
||
* // got: 100
|
||
* // {
|
||
* // resource: {
|
||
* // attributes: {
|
||
* // 'service.name': 'example',
|
||
* // 'telemetry.sdk.language': 'nodejs',
|
||
* // 'telemetry.sdk.name': '@effect/opentelemetry',
|
||
* // 'telemetry.sdk.version': '1.30.1'
|
||
* // }
|
||
* // },
|
||
* // instrumentationScope: { name: 'example', version: undefined, schemaUrl: undefined },
|
||
* // traceId: '22801570119e57a6e2aacda3dec9665b',
|
||
* // parentId: undefined,
|
||
* // traceState: undefined,
|
||
* // name: 'myspan',
|
||
* // id: '7af530c1e01bc0cb',
|
||
* // kind: 0,
|
||
* // timestamp: 1741182277518402.2,
|
||
* // duration: 4300.416,
|
||
* // attributes: {
|
||
* // n: 100,
|
||
* // 'code.stacktrace': 'at <anonymous> (/.../index.ts:8:23)\n' +
|
||
* // 'at <anonymous> (/.../index.ts:14:17)'
|
||
* // },
|
||
* // status: { code: 2, message: 'Boom!' },
|
||
* // events: [
|
||
* // {
|
||
* // name: 'exception',
|
||
* // attributes: {
|
||
* // 'exception.type': 'Error',
|
||
* // 'exception.message': 'Boom!',
|
||
* // 'exception.stacktrace': 'Error: Boom!\n' +
|
||
* // ' at <anonymous> (/.../index.ts:11:22)\n' +
|
||
* // ' at myspan (/.../index.ts:8:23)\n' +
|
||
* // ' at myspan (/.../index.ts:14:17)'
|
||
* // },
|
||
* // time: [ 1741182277, 522702583 ],
|
||
* // droppedAttributesCount: 0
|
||
* // }
|
||
* // ],
|
||
* // links: []
|
||
* // }
|
||
* ```
|
||
*
|
||
* `Effect.fn` also acts as a pipe function, allowing you to create a pipeline
|
||
* after the function definition using the effect returned by the generator
|
||
* function as the starting value of the pipeline.
|
||
*
|
||
* **Example** (Creating a Traced Function with a Delay)
|
||
*
|
||
* ```ts
|
||
* import { Effect } from "effect"
|
||
*
|
||
* const myfunc = Effect.fn(
|
||
* function* (n: number) {
|
||
* console.log(`got: ${n}`)
|
||
* yield* Effect.fail(new Error("Boom!"))
|
||
* },
|
||
* // You can access both the created effect and the original arguments
|
||
* (effect, n) => Effect.delay(effect, `${n / 100} seconds`)
|
||
* )
|
||
*
|
||
* Effect.runFork(myfunc(100).pipe(Effect.catchAllCause(Effect.logError)))
|
||
* // Output:
|
||
* // got: 100
|
||
* // timestamp=... level=ERROR fiber=#0 cause="Error: Boom! (<= after 1 second)
|
||
* ```
|
||
*
|
||
* @see {@link fnUntraced} for a version of this function that doesn't add a span.
|
||
*
|
||
* @since 3.11.0
|
||
* @category Tracing
|
||
*/
|
||
exports.Service = Service;
|
||
const fn = function (nameOrBody, ...pipeables) {
|
||
const limit = Error.stackTraceLimit;
|
||
Error.stackTraceLimit = 2;
|
||
const errorDef = new Error();
|
||
Error.stackTraceLimit = limit;
|
||
if (typeof nameOrBody !== "string") {
|
||
return defineLength(nameOrBody.length, function (...args) {
|
||
const limit = Error.stackTraceLimit;
|
||
Error.stackTraceLimit = 2;
|
||
const errorCall = new Error();
|
||
Error.stackTraceLimit = limit;
|
||
return fnApply({
|
||
self: this,
|
||
body: nameOrBody,
|
||
args,
|
||
pipeables,
|
||
spanName: "<anonymous>",
|
||
spanOptions: {
|
||
context: internalTracer.DisablePropagation.context(true)
|
||
},
|
||
errorDef,
|
||
errorCall
|
||
});
|
||
});
|
||
}
|
||
const name = nameOrBody;
|
||
const options = pipeables[0];
|
||
return (body, ...pipeables) => defineLength(body.length, {
|
||
[name](...args) {
|
||
const limit = Error.stackTraceLimit;
|
||
Error.stackTraceLimit = 2;
|
||
const errorCall = new Error();
|
||
Error.stackTraceLimit = limit;
|
||
return fnApply({
|
||
self: this,
|
||
body,
|
||
args,
|
||
pipeables,
|
||
spanName: name,
|
||
spanOptions: options,
|
||
errorDef,
|
||
errorCall
|
||
});
|
||
}
|
||
}[name]);
|
||
};
|
||
exports.fn = fn;
|
||
function defineLength(length, fn) {
|
||
return Object.defineProperty(fn, "length", {
|
||
value: length,
|
||
configurable: true
|
||
});
|
||
}
|
||
function fnApply(options) {
|
||
let effect;
|
||
let fnError = undefined;
|
||
if ((0, _Utils.isGeneratorFunction)(options.body)) {
|
||
effect = core.fromIterator(() => options.body.apply(options.self, options.args));
|
||
} else {
|
||
try {
|
||
effect = options.body.apply(options.self, options.args);
|
||
} catch (error) {
|
||
fnError = error;
|
||
effect = die(error);
|
||
}
|
||
}
|
||
if (options.pipeables.length > 0) {
|
||
try {
|
||
for (const x of options.pipeables) {
|
||
effect = x(effect, ...options.args);
|
||
}
|
||
} catch (error) {
|
||
effect = fnError ? failCause(internalCause.sequential(internalCause.die(fnError), internalCause.die(error))) : die(error);
|
||
}
|
||
}
|
||
let cache = false;
|
||
const captureStackTrace = () => {
|
||
if (cache !== false) {
|
||
return cache;
|
||
}
|
||
if (options.errorCall.stack) {
|
||
const stackDef = options.errorDef.stack.trim().split("\n");
|
||
const stackCall = options.errorCall.stack.trim().split("\n");
|
||
let endStackDef = stackDef.slice(2).join("\n").trim();
|
||
if (!endStackDef.includes(`(`)) {
|
||
endStackDef = endStackDef.replace(/at (.*)/, "at ($1)");
|
||
}
|
||
let endStackCall = stackCall.slice(2).join("\n").trim();
|
||
if (!endStackCall.includes(`(`)) {
|
||
endStackCall = endStackCall.replace(/at (.*)/, "at ($1)");
|
||
}
|
||
cache = `${endStackDef}\n${endStackCall}`;
|
||
return cache;
|
||
}
|
||
};
|
||
const opts = options.spanOptions && "captureStackTrace" in options.spanOptions ? options.spanOptions : {
|
||
captureStackTrace,
|
||
...options.spanOptions
|
||
};
|
||
return withSpan(effect, options.spanName, opts);
|
||
}
|
||
/**
|
||
* Same as {@link fn}, but allows you to create a function that is not traced, for when performance is critical.
|
||
*
|
||
* @see {@link fn} for a version that includes tracing.
|
||
*
|
||
* @since 3.12.0
|
||
* @category Tracing
|
||
*/
|
||
const fnUntraced = exports.fnUntraced = core.fnUntraced;
|
||
//# sourceMappingURL=Effect.js.map
|