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

package/src/Random.ts

@@ -0,0 +1,204 @@
+/**
+ * @since 2.0.0
+ */
+import type * as Array from "./Array.js"
+import type * as Cause from "./Cause.js"
+import type * as Chunk from "./Chunk.js"
+import type * as Context from "./Context.js"
+import type * as Effect from "./Effect.js"
+import * as defaultServices from "./internal/defaultServices.js"
+import * as internal from "./internal/random.js"
+import type * as NonEmptyIterable from "./NonEmptyIterable.js"
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export const RandomTypeId: unique symbol = internal.RandomTypeId
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export type RandomTypeId = typeof RandomTypeId
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface Random {
+  readonly [RandomTypeId]: RandomTypeId
+  /**
+   * Returns the next numeric value from the pseudo-random number generator.
+   */
+  readonly next: Effect.Effect<number>
+  /**
+   * Returns the next boolean value from the pseudo-random number generator.
+   */
+  readonly nextBoolean: Effect.Effect<boolean>
+  /**
+   * Returns the next integer value from the pseudo-random number generator.
+   */
+  readonly nextInt: Effect.Effect<number>
+  /**
+   * Returns the next numeric value in the specified range from the
+   * pseudo-random number generator.
+   */
+  nextRange(min: number, max: number): Effect.Effect<number>
+  /**
+   * Returns the next integer value in the specified range from the
+   * pseudo-random number generator.
+   */
+  nextIntBetween(min: number, max: number): Effect.Effect<number>
+  /**
+   * Uses the pseudo-random number generator to shuffle the specified iterable.
+   */
+  shuffle<A>(elements: Iterable<A>): Effect.Effect<Chunk.Chunk<A>>
+}
+
+/**
+ * Returns the next numeric value from the pseudo-random number generator.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const next: Effect.Effect<number> = defaultServices.next
+
+/**
+ * Returns the next integer value from the pseudo-random number generator.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const nextInt: Effect.Effect<number> = defaultServices.nextInt
+
+/**
+ * Returns the next boolean value from the pseudo-random number generator.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const nextBoolean: Effect.Effect<boolean> = defaultServices.nextBoolean
+
+/**
+ * Returns the next numeric value in the specified range from the
+ * pseudo-random number generator.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const nextRange: (min: number, max: number) => Effect.Effect<number> = defaultServices.nextRange
+
+/**
+ * Returns the next integer value in the specified range from the
+ * pseudo-random number generator.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const nextIntBetween: (min: number, max: number) => Effect.Effect<number> = defaultServices.nextIntBetween
+
+/**
+ * Uses the pseudo-random number generator to shuffle the specified iterable.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const shuffle: <A>(elements: Iterable<A>) => Effect.Effect<Chunk.Chunk<A>> = defaultServices.shuffle
+
+/**
+ * Get a random element from an iterable.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Random } from "effect"
+ *
+ * Effect.gen(function* () {
+ *   const randomItem = yield* Random.choice([1, 2, 3])
+ *   console.log(randomItem)
+ * })
+ * ```
+ *
+ * @since 3.6.0
+ * @category constructors
+ */
+export const choice: <Self extends Iterable<unknown>>(
+  elements: Self
+) => Self extends NonEmptyIterable.NonEmptyIterable<infer A> ? Effect.Effect<A>
+  : Self extends Array.NonEmptyReadonlyArray<infer A> ? Effect.Effect<A>
+  : Self extends Iterable<infer A> ? Effect.Effect<A, Cause.NoSuchElementException>
+  : never = defaultServices.choice
+
+/**
+ * Retreives the `Random` service from the context and uses it to run the
+ * specified workflow.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const randomWith: <A, E, R>(f: (random: Random) => Effect.Effect<A, E, R>) => Effect.Effect<A, E, R> =
+  defaultServices.randomWith
+
+/**
+ * @since 2.0.0
+ * @category context
+ */
+export const Random: Context.Tag<Random, Random> = internal.randomTag
+
+/**
+ * Constructs the `Random` service, seeding the pseudo-random number generator
+ * with an hash of the specified seed.
+ * This constructor is useful for generating predictable sequences of random values for specific use cases.
+ *
+ * Example uses:
+ * - Generating random UI data for visual tests.
+ * - Creating data that needs to change daily but remain the same throughout a single day, such as using a date as the seed.
+ *
+ * @example
+ * ```ts
+ * import * as assert from "node:assert"
+ * import { Effect, Random } from "effect"
+ *
+ * const random1 = Random.make("myseed")
+ * const random2 = Random.make("myseed")
+ *
+ * assert.equal(Effect.runSync(random1.next), Effect.runSync(random2.next))
+ * ```
+ *
+ * @since 3.5.0
+ * @category constructors
+ */
+export const make: <A>(seed: A) => Random = internal.make
+
+/**
+ * Constructs the `Random` service from an array of literal values.
+ * The service will cycle through the provided values in order when generating random values.
+ * This constructor is useful for creating deterministic sequences for testing or when specific values need to be returned.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Random } from "effect"
+ *
+ * Effect.gen(function* () {
+ *   console.log(yield* Random.next) // 0.2
+ *   console.log(yield* Random.next) // 0.5
+ *   console.log(yield* Random.next) // 0.8
+ *   console.log(yield* Random.next) // 0.2 (cycles back)
+ * }).pipe(Effect.withRandom(Random.fixed([0.2, 0.5, 0.8])))
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { Effect, Random } from "effect"
+ *
+ * Effect.gen(function* () {
+ *   console.log(yield* Random.nextBoolean) // true
+ *   console.log(yield* Random.nextBoolean) // false
+ *   console.log(yield* Random.nextBoolean) // true
+ * }).pipe(Effect.withRandom(Random.fixed([true, false, true])))
+ * ```
+ *
+ * @since 3.11.0
+ * @category constructors
+ */
+export const fixed: <const T extends Array.NonEmptyArray<any>>(values: T) => Random = internal.fixed

package/src/RateLimiter.ts

@@ -0,0 +1,138 @@
+/**
+ * Limits the number of calls to a resource to a maximum amount in some interval.
+ *
+ * @since 2.0.0
+ */
+import type { DurationInput } from "./Duration.js"
+import type { Effect } from "./Effect.js"
+import * as internal from "./internal/rateLimiter.js"
+import type { Scope } from "./Scope.js"
+
+/**
+ * Limits the number of calls to a resource to a maximum amount in some interval.
+ *
+ * Note that only the moment of starting the effect is rate limited: the number
+ * of concurrent executions is not bounded.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export interface RateLimiter {
+  <A, E, R>(task: Effect<A, E, R>): Effect<A, E, R>
+}
+
+/**
+ * @since 2.0.0
+ */
+export declare namespace RateLimiter {
+  /**
+   * @since 2.0.0
+   * @category models
+   */
+  export interface Options {
+    /**
+     * The maximum number of requests that should be allowed.
+     */
+    readonly limit: number
+    /**
+     * The interval to utilize for rate-limiting requests. The semantics of the
+     * specified `interval` vary depending on the chosen `algorithm`:
+     *
+     * `token-bucket`: The maximum number of requests will be spread out over
+     * the provided interval if no tokens are available.
+     *
+     * For example, for a `RateLimiter` using the `token-bucket` algorithm with
+     * a `limit` of `10` and an `interval` of `1 seconds`, `1` request can be
+     * made every `100 millis`.
+     *
+     * `fixed-window`: The maximum number of requests will be reset during each
+     * interval. For example, for a `RateLimiter` using the `fixed-window`
+     * algorithm with a `limit` of `10` and an `interval` of `1 seconds`, a
+     * maximum of `10` requests can be made each second.
+     */
+    readonly interval: DurationInput
+    /**
+     * The algorithm to utilize for rate-limiting requests.
+     *
+     * Defaults to `token-bucket`.
+     */
+    readonly algorithm?: "fixed-window" | "token-bucket"
+  }
+}
+
+/**
+ * Constructs a new `RateLimiter` which will utilize the specified algorithm
+ * to limit requests (defaults to `token-bucket`).
+ *
+ * Notes
+ * - Only the moment of starting the effect is rate limited. The number of concurrent executions is not bounded.
+ * - Instances of `RateLimiter` can be composed.
+ * - The "cost" per effect can be changed. See {@link withCost}
+ *
+ * @example
+ * ```ts
+ * import { Effect, RateLimiter } from "effect";
+ * import { compose } from "effect/Function"
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* ($) {
+ *     const perMinuteRL = yield* $(RateLimiter.make({ limit: 30, interval: "1 minutes" }))
+ *     const perSecondRL = yield* $(RateLimiter.make({ limit: 2, interval: "1 seconds" }))
+ *
+ *     // This rate limiter respects both the 30 calls per minute
+ *     // and the 2 calls per second constraints.
+ *      const rateLimit = compose(perMinuteRL, perSecondRL)
+ *
+ *     // simulate repeated calls
+ *     for (let n = 0; n < 100; n++) {
+ *       // wrap the effect we want to limit with rateLimit
+ *       yield* $(rateLimit(Effect.log("Calling RateLimited Effect")));
+ *     }
+ *   })
+ * );
+ * ```
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const make: (options: RateLimiter.Options) => Effect<RateLimiter, never, Scope> = internal.make
+
+/**
+ * Alters the per-effect cost of the rate-limiter.
+ *
+ * This can be used for "credit" based rate-limiting where different API endpoints
+ * cost a different number of credits within a time window.
+ * Eg: 1000 credits / hour, where a query costs 1 credit and a mutation costs 5 credits.
+ *
+ * @example
+ * ```ts
+ * import { Effect, RateLimiter } from "effect";
+ * import { compose } from "effect/Function";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* ($) {
+ *     // Create a rate limiter that has an hourly limit of 1000 credits
+ *     const rateLimiter = yield* $(RateLimiter.make({ limit: 1000, interval: "1 hours" }));
+ *     // Query API costs 1 credit per call ( 1 is the default cost )
+ *     const queryAPIRL = compose(rateLimiter, RateLimiter.withCost(1));
+ *     // Mutation API costs 5 credits per call
+ *     const mutationAPIRL = compose(rateLimiter, RateLimiter.withCost(5));
+
+ *     // Use the pre-defined rate limiters
+ *     yield* $(queryAPIRL(Effect.log("Sample Query")));
+ *     yield* $(mutationAPIRL(Effect.log("Sample Mutation")));
+ *
+ *     // Or set a cost on-the-fly
+ *     yield* $(
+ *       rateLimiter(Effect.log("Another query with a different cost")).pipe(
+ *         RateLimiter.withCost(3)
+ *       )
+ *     );
+ *   })
+ * );
+ * ```
+ *
+ * @since 2.0.0
+ * @category combinators
+ */
+export const withCost: (cost: number) => <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R> = internal.withCost

package/src/RcMap.ts

@@ -0,0 +1,141 @@
+/**
+ * @since 3.5.0
+ */
+import type * as Cause from "./Cause.js"
+import type * as Duration from "./Duration.js"
+import type * as Effect from "./Effect.js"
+import * as internal from "./internal/rcMap.js"
+import { type Pipeable } from "./Pipeable.js"
+import type * as Scope from "./Scope.js"
+import type * as Types from "./Types.js"
+
+/**
+ * @since 3.5.0
+ * @category type ids
+ */
+export const TypeId: unique symbol = internal.TypeId
+
+/**
+ * @since 3.5.0
+ * @category type ids
+ */
+export type TypeId = typeof TypeId
+
+/**
+ * @since 3.5.0
+ * @category models
+ */
+export interface RcMap<in K, out A, out E = never> extends Pipeable {
+  readonly [TypeId]: RcMap.Variance<K, A, E>
+}
+
+/**
+ * @since 3.5.0
+ * @category models
+ */
+export declare namespace RcMap {
+  /**
+   * @since 3.5.0
+   * @category models
+   */
+  export interface Variance<K, A, E> {
+    readonly _K: Types.Contravariant<K>
+    readonly _A: Types.Covariant<A>
+    readonly _E: Types.Covariant<E>
+  }
+}
+
+/**
+ * An `RcMap` can contain multiple reference counted resources that can be indexed
+ * by a key. The resources are lazily acquired on the first call to `get` and
+ * released when the last reference is released.
+ *
+ * Complex keys can extend `Equal` and `Hash` to allow lookups by value.
+ *
+ * **Options**
+ *
+ * - `capacity`: The maximum number of resources that can be held in the map.
+ * - `idleTimeToLive`: When the reference count reaches zero, the resource will be released after this duration.
+ *
+ * @since 3.5.0
+ * @category models
+ * @example
+ * ```ts
+ * import { Effect, RcMap } from "effect"
+ *
+ * Effect.gen(function*() {
+ *   const map = yield* RcMap.make({
+ *     lookup: (key: string) =>
+ *       Effect.acquireRelease(
+ *         Effect.succeed(`acquired ${key}`),
+ *         () => Effect.log(`releasing ${key}`)
+ *       )
+ *   })
+ *
+ *   // Get "foo" from the map twice, which will only acquire it once.
+ *   // It will then be released once the scope closes.
+ *   yield* RcMap.get(map, "foo").pipe(
+ *     Effect.andThen(RcMap.get(map, "foo")),
+ *     Effect.scoped
+ *   )
+ * })
+ * ```
+ */
+export const make: {
+  <K, A, E, R>(
+    options: {
+      readonly lookup: (key: K) => Effect.Effect<A, E, R>
+      readonly idleTimeToLive?: Duration.DurationInput | undefined
+      readonly capacity?: undefined
+    }
+  ): Effect.Effect<RcMap<K, A, E>, never, Scope.Scope | R>
+  <K, A, E, R>(
+    options: {
+      readonly lookup: (key: K) => Effect.Effect<A, E, R>
+      readonly idleTimeToLive?: Duration.DurationInput | undefined
+      readonly capacity: number
+    }
+  ): Effect.Effect<RcMap<K, A, E | Cause.ExceededCapacityException>, never, Scope.Scope | R>
+} = internal.make
+
+/**
+ * @since 3.5.0
+ * @category combinators
+ */
+export const get: {
+  <K>(key: K): <A, E>(self: RcMap<K, A, E>) => Effect.Effect<A, E, Scope.Scope>
+  <K, A, E>(self: RcMap<K, A, E>, key: K): Effect.Effect<A, E, Scope.Scope>
+} = internal.get
+
+/**
+ * @since 3.17.7
+ * @category combinators
+ */
+export const has: {
+  <K>(key: K): <A, E>(self: RcMap<K, A, E>) => Effect.Effect<boolean>
+  <K, A, E>(self: RcMap<K, A, E>, key: K): Effect.Effect<boolean>
+} = internal.has
+
+/**
+ * @since 3.8.0
+ * @category combinators
+ */
+export const keys: <K, A, E>(self: RcMap<K, A, E>) => Effect.Effect<Array<K>> = internal.keys
+
+/**
+ * @since 3.13.0
+ * @category combinators
+ */
+export const invalidate: {
+  <K>(key: K): <A, E>(self: RcMap<K, A, E>) => Effect.Effect<void>
+  <K, A, E>(self: RcMap<K, A, E>, key: K): Effect.Effect<void>
+} = internal.invalidate
+
+/**
+ * @since 3.13.0
+ * @category combinators
+ */
+export const touch: {
+  <K>(key: K): <A, E>(self: RcMap<K, A, E>) => Effect.Effect<void>
+  <K, A, E>(self: RcMap<K, A, E>, key: K): Effect.Effect<void>
+} = internal.touch

package/src/RcRef.ts

@@ -0,0 +1,122 @@
+/**
+ * @since 3.5.0
+ */
+import type * as Duration from "./Duration.js"
+import type * as Effect from "./Effect.js"
+import * as internal from "./internal/rcRef.js"
+import type * as Readable from "./Readable.js"
+import type * as Scope from "./Scope.js"
+import type * as Types from "./Types.js"
+import type * as Unify from "./Unify.js"
+
+/**
+ * @since 3.5.0
+ * @category type ids
+ */
+export const TypeId: unique symbol = internal.TypeId
+
+/**
+ * @since 3.5.0
+ * @category type ids
+ */
+export type TypeId = typeof TypeId
+
+/**
+ * @since 3.5.0
+ * @category models
+ */
+export interface RcRef<out A, out E = never>
+  extends Effect.Effect<A, E, Scope.Scope>, Readable.Readable<A, E, Scope.Scope>
+{
+  readonly [TypeId]: RcRef.Variance<A, E>
+  readonly [Unify.typeSymbol]?: unknown
+  readonly [Unify.unifySymbol]?: RcRefUnify<this>
+  readonly [Unify.ignoreSymbol]?: RcRefUnifyIgnore
+}
+
+/**
+ * @category models
+ * @since 3.8.0
+ */
+export interface RcRefUnify<A extends { [Unify.typeSymbol]?: any }> extends Effect.EffectUnify<A> {
+  RcRef?: () => A[Unify.typeSymbol] extends RcRef<infer A0, infer E0> | infer _ ? RcRef<A0, E0>
+    : never
+}
+
+/**
+ * @category models
+ * @since 3.8.0
+ */
+export interface RcRefUnifyIgnore extends Effect.EffectUnifyIgnore {
+  Effect?: true
+}
+/**
+ * @since 3.5.0
+ * @category models
+ */
+export declare namespace RcRef {
+  /**
+   * @since 3.5.0
+   * @category models
+   */
+  export interface Variance<A, E> {
+    readonly _A: Types.Covariant<A>
+    readonly _E: Types.Covariant<E>
+  }
+}
+
+/**
+ * Create an `RcRef` from an acquire `Effect`.
+ *
+ * An RcRef wraps a reference counted resource that can be acquired and released
+ * multiple times.
+ *
+ * The resource is lazily acquired on the first call to `get` and released when
+ * the last reference is released.
+ *
+ * @since 3.5.0
+ * @category constructors
+ * @example
+ * ```ts
+ * import { Effect, RcRef } from "effect"
+ *
+ * Effect.gen(function*() {
+ *   const ref = yield* RcRef.make({
+ *     acquire: Effect.acquireRelease(
+ *       Effect.succeed("foo"),
+ *       () => Effect.log("release foo")
+ *     )
+ *   })
+ *
+ *   // will only acquire the resource once, and release it
+ *   // when the scope is closed
+ *   yield* RcRef.get(ref).pipe(
+ *     Effect.andThen(RcRef.get(ref)),
+ *     Effect.scoped
+ *   )
+ * })
+ * ```
+ */
+export const make: <A, E, R>(
+  options: {
+    readonly acquire: Effect.Effect<A, E, R>
+    /**
+     * When the reference count reaches zero, the resource will be released
+     * after this duration.
+     */
+    readonly idleTimeToLive?: Duration.DurationInput | undefined
+  }
+) => Effect.Effect<RcRef<A, E>, never, R | Scope.Scope> = internal.make
+
+/**
+ * @since 3.5.0
+ * @category combinators
+ */
+export const get: <A, E>(self: RcRef<A, E>) => Effect.Effect<A, E, Scope.Scope> = internal.get
+
+/**
+ * @since 3.19.6
+ * @category combinators
+ * @experimental
+ */
+export const invalidate: <A, E>(self: RcRef<A, E>) => Effect.Effect<void> = internal.invalidate

package/src/Readable.ts

@@ -0,0 +1,93 @@
+/**
+ * @since 2.0.0
+ */
+import type { Effect } from "./Effect.js"
+import { dual } from "./Function.js"
+import * as core from "./internal/core.js"
+import { type Pipeable, pipeArguments } from "./Pipeable.js"
+import { hasProperty } from "./Predicate.js"
+import type { NoInfer } from "./Types.js"
+
+/**
+ * @since 2.0.0
+ * @category type ids
+ */
+export const TypeId: unique symbol = Symbol.for("effect/Readable")
+
+/**
+ * @since 2.0.0
+ * @category type ids
+ */
+export type TypeId = typeof TypeId
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface Readable<A, E = never, R = never> extends Pipeable {
+  readonly [TypeId]: TypeId
+  readonly get: Effect<A, E, R>
+}
+
+/**
+ * @since 2.0.0
+ * @category refinements
+ */
+export const isReadable = (u: unknown): u is Readable<unknown, unknown, unknown> => hasProperty(u, TypeId)
+
+const Proto: Omit<Readable<any>, "get"> = {
+  [TypeId]: TypeId,
+  pipe() {
+    return pipeArguments(this, arguments)
+  }
+}
+
+/**
+ * @since 2.0.0
+ * @category constructors
+ */
+export const make = <A, E, R>(get: Effect<A, E, R>): Readable<A, E, R> => {
+  const self = Object.create(Proto)
+  self.get = get
+  return self
+}
+
+/**
+ * @since 2.0.0
+ * @category combinators
+ */
+export const map: {
+  <A, B>(f: (a: NoInfer<A>) => B): <E, R>(fa: Readable<A, E, R>) => Readable<B, E, R>
+  <A, E, R, B>(self: Readable<A, E, R>, f: (a: NoInfer<A>) => B): Readable<B, E, R>
+} = dual(
+  2,
+  <A, E, R, B>(self: Readable<A, E, R>, f: (a: NoInfer<A>) => B): Readable<B, E, R> => make(core.map(self.get, f))
+)
+
+/**
+ * @since 2.0.0
+ * @category combinators
+ */
+export const mapEffect: {
+  <A, B, E2, R2>(
+    f: (a: NoInfer<A>) => Effect<B, E2, R2>
+  ): <E, R>(fa: Readable<A, E, R>) => Readable<B, E | E2, R | R2>
+  <A, E, R, B, E2, R2>(
+    self: Readable<A, E, R>,
+    f: (a: NoInfer<A>) => Effect<B, E2, R2>
+  ): Readable<B, E | E2, R | R2>
+} = dual(2, <A, E, R, B, E2, R2>(
+  self: Readable<A, E, R>,
+  f: (a: NoInfer<A>) => Effect<B, E2, R2>
+): Readable<B, E | E2, R | R2> => make(core.flatMap(self.get, f)))
+
+/**
+ * @since 2.0.0
+ * @category constructors
+ */
+export const unwrap = <A, E, R, E1, R1>(
+  effect: Effect<Readable<A, E, R>, E1, R1>
+): Readable<A, E | E1, R | R1> =>
+  make(
+    core.flatMap(effect, (s) => s.get)
+  )