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

package/src/Scope.ts

@@ -0,0 +1,204 @@
+/**
+ * @since 2.0.0
+ */
+
+import type * as Context from "./Context.js"
+import type * as Effect from "./Effect.js"
+import type * as ExecutionStrategy from "./ExecutionStrategy.js"
+import type * as Exit from "./Exit.js"
+import * as core from "./internal/core.js"
+import * as fiberRuntime from "./internal/fiberRuntime.js"
+import type { Pipeable } from "./Pipeable.js"
+
+/**
+ * A unique identifier for the `Scope` type.
+ *
+ * @since 2.0.0
+ * @category symbols
+ */
+export const ScopeTypeId: unique symbol = core.ScopeTypeId
+
+/**
+ * The type of the unique identifier for `Scope`.
+ *
+ * @since 2.0.0
+ * @category symbols
+ */
+export type ScopeTypeId = typeof ScopeTypeId
+
+/**
+ * A unique identifier for the `CloseableScope` type.
+ *
+ * @since 2.0.0
+ * @category symbols
+ */
+export const CloseableScopeTypeId: unique symbol = core.CloseableScopeTypeId
+
+/**
+ * The type of the unique identifier for `CloseableScope`.
+ *
+ * @since 2.0.0
+ * @category symbols
+ */
+export type CloseableScopeTypeId = typeof CloseableScopeTypeId
+
+/**
+ * Represents a scope that manages finalizers and can fork child scopes.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export interface Scope extends Pipeable {
+  readonly [ScopeTypeId]: ScopeTypeId
+  /**
+   * The execution strategy for running finalizers in this scope.
+   */
+  readonly strategy: ExecutionStrategy.ExecutionStrategy
+  /**
+   * Forks a new child scope with the specified execution strategy. The child scope
+   * will automatically be closed when this scope is closed.
+   *
+   * @internal
+   */
+  fork(strategy: ExecutionStrategy.ExecutionStrategy): Effect.Effect<Scope.Closeable>
+  /**
+   * Adds a finalizer to this scope. The finalizer will be run when the scope is closed.
+   *
+   * @internal
+   */
+  addFinalizer(finalizer: Scope.Finalizer): Effect.Effect<void>
+}
+
+/**
+ * A scope that can be explicitly closed with a specified exit value.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export interface CloseableScope extends Scope, Pipeable {
+  readonly [CloseableScopeTypeId]: CloseableScopeTypeId
+
+  /**
+   * Closes this scope with the given exit value, running all finalizers.
+   *
+   * @internal
+   */
+  close(exit: Exit.Exit<unknown, unknown>): Effect.Effect<void>
+}
+
+/**
+ * A tag representing the current `Scope` in the environment.
+ *
+ * @since 2.0.0
+ * @category context
+ */
+export const Scope: Context.Tag<Scope, Scope> = fiberRuntime.scopeTag
+
+/**
+ * @since 2.0.0
+ */
+export declare namespace Scope {
+  /**
+   * A finalizer function that takes an `Exit` value and returns an `Effect`.
+   *
+   * @since 2.0.0
+   * @category model
+   */
+  export type Finalizer = (exit: Exit.Exit<unknown, unknown>) => Effect.Effect<void>
+  /**
+   * A closeable scope that can be explicitly closed.
+   *
+   * @since 2.0.0
+   * @category model
+   */
+  export type Closeable = CloseableScope
+}
+
+/**
+ * Adds a finalizer to this scope. The finalizer is guaranteed to be run when
+ * the scope is closed. Use this when the finalizer does not need to know the
+ * `Exit` value that the scope is closed with.
+ *
+ * @see {@link addFinalizerExit}
+ *
+ * @since 2.0.0
+ * @category utils
+ */
+export const addFinalizer: (
+  self: Scope,
+  finalizer: Effect.Effect<unknown>
+) => Effect.Effect<void> = core.scopeAddFinalizer
+
+/**
+ * Adds a finalizer to this scope. The finalizer receives the `Exit` value
+ * when the scope is closed, allowing it to perform different actions based
+ * on the exit status.
+ *
+ * @see {@link addFinalizer}
+ *
+ * @since 2.0.0
+ * @category utils
+ */
+export const addFinalizerExit: (self: Scope, finalizer: Scope.Finalizer) => Effect.Effect<void> =
+  core.scopeAddFinalizerExit
+
+/**
+ * Closes this scope with the specified exit value, running all finalizers that
+ * have been added to the scope.
+ *
+ * @since 2.0.0
+ * @category destructors
+ */
+export const close: (self: CloseableScope, exit: Exit.Exit<unknown, unknown>) => Effect.Effect<void> = core.scopeClose
+
+/**
+ * Extends the scope of an `Effect` that requires a scope into this scope.
+ * It provides this scope to the effect but does not close the scope when the
+ * effect completes execution. This allows extending a scoped value into a
+ * larger scope.
+ *
+ * @since 2.0.0
+ * @category utils
+ */
+export const extend: {
+  (scope: Scope): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Scope>>
+  <A, E, R>(effect: Effect.Effect<A, E, R>, scope: Scope): Effect.Effect<A, E, Exclude<R, Scope>>
+} = fiberRuntime.scopeExtend
+
+/**
+ * Forks a new child scope with the specified execution strategy. The child scope
+ * will automatically be closed when this scope is closed.
+ *
+ * @since 2.0.0
+ * @category utils
+ */
+export const fork: (
+  self: Scope,
+  strategy: ExecutionStrategy.ExecutionStrategy
+) => Effect.Effect<CloseableScope> = core.scopeFork
+
+/**
+ * Provides this closeable scope to an `Effect` that requires a scope,
+ * guaranteeing that the scope is closed with the result of that effect as
+ * soon as the effect completes execution, whether by success, failure, or
+ * interruption.
+ *
+ * @since 2.0.0
+ * @category destructors
+ */
+export const use: {
+  (scope: CloseableScope): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Scope>>
+  <A, E, R>(effect: Effect.Effect<A, E, R>, scope: CloseableScope): Effect.Effect<A, E, Exclude<R, Scope>>
+} = fiberRuntime.scopeUse
+
+/**
+ * Creates a new closeable scope where finalizers will run according to the
+ * specified `ExecutionStrategy`. If no execution strategy is provided, `sequential`
+ * will be used by default.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const make: (
+  executionStrategy?: ExecutionStrategy.ExecutionStrategy
+) => Effect.Effect<CloseableScope> = fiberRuntime.scopeMake

package/src/ScopedCache.ts

@@ -0,0 +1,151 @@
+/**
+ * @since 2.0.0
+ */
+import type * as Cache from "./Cache.js"
+import type * as Duration from "./Duration.js"
+import type * as Effect from "./Effect.js"
+import type * as Exit from "./Exit.js"
+import * as internal from "./internal/scopedCache.js"
+import type * as Option from "./Option.js"
+import type { Pipeable } from "./Pipeable.js"
+import type * as Scope from "./Scope.js"
+import type * as Types from "./Types.js"
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export const ScopedCacheTypeId: unique symbol = internal.ScopedCacheTypeId
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export type ScopedCacheTypeId = typeof ScopedCacheTypeId
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface ScopedCache<in Key, out Value, out Error = never>
+  extends ScopedCache.Variance<Key, Value, Error>, Pipeable
+{
+  /**
+   * Retrieves the value associated with the specified key if it exists.
+   * Otherwise returns `Option.none`.
+   */
+  getOption(key: Key): Effect.Effect<Option.Option<Value>, Error, Scope.Scope>
+
+  /**
+   * Retrieves the value associated with the specified key if it exists and the
+   * lookup function has completed. Otherwise returns `Option.none`.
+   */
+  getOptionComplete(key: Key): Effect.Effect<Option.Option<Value>, never, Scope.Scope>
+
+  /**
+   * Returns statistics for this cache.
+   */
+  readonly cacheStats: Effect.Effect<Cache.CacheStats>
+
+  /**
+   * Return whether a resource associated with the specified key exists in the
+   * cache. Sometime `contains` can return true if the resource is currently
+   * being created but not yet totally created.
+   */
+  contains(key: Key): Effect.Effect<boolean>
+
+  /**
+   * Return statistics for the specified entry.
+   */
+  entryStats(key: Key): Effect.Effect<Option.Option<Cache.EntryStats>>
+
+  /**
+   * Gets the value from the cache if it exists or otherwise computes it, the
+   * release action signals to the cache that the value is no longer being used
+   * and can potentially be finalized subject to the policies of the cache.
+   */
+  get(key: Key): Effect.Effect<Value, Error, Scope.Scope>
+
+  /**
+   * Invalidates the resource associated with the specified key.
+   */
+  invalidate(key: Key): Effect.Effect<void>
+
+  /**
+   * Invalidates all values in the cache.
+   */
+  readonly invalidateAll: Effect.Effect<void>
+
+  /**
+   * Force the reuse of the lookup function to compute the returned scoped
+   * effect associated with the specified key immediately. Once the new resource
+   * is recomputed, the old resource associated to the key is cleaned (once all
+   * fiber using it are done with it). During the time the new resource is
+   * computed, concurrent call the .get will use the old resource if this one is
+   * not expired.
+   */
+  refresh(key: Key): Effect.Effect<void, Error>
+
+  /**
+   * Returns the approximate number of values in the cache.
+   */
+  readonly size: Effect.Effect<number>
+}
+
+/**
+ * @since 2.0.0
+ */
+export declare namespace ScopedCache {
+  /**
+   * @since 2.0.0
+   * @category models
+   */
+  export interface Variance<in Key, out Value, out Error> {
+    readonly [ScopedCacheTypeId]: {
+      _Key: Types.Contravariant<Key>
+      _Error: Types.Covariant<Error>
+      _Value: Types.Covariant<Value>
+    }
+  }
+}
+
+/**
+ * Constructs a new cache with the specified capacity, time to live, and
+ * lookup function.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const make: <Key, Value, Error = never, Environment = never>(
+  options: {
+    readonly lookup: Lookup<Key, Value, Error, Environment>
+    readonly capacity: number
+    readonly timeToLive: Duration.DurationInput
+  }
+) => Effect.Effect<ScopedCache<Key, Value, Error>, never, Scope.Scope | Environment> = internal.make
+
+/**
+ * Constructs a new cache with the specified capacity, time to live, and
+ * lookup function, where the time to live can depend on the `Exit` value
+ * returned by the lookup function.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const makeWith: <Key, Value, Error = never, Environment = never>(
+  options: {
+    readonly capacity: number
+    readonly lookup: Lookup<Key, Value, Error, Environment>
+    readonly timeToLive: (exit: Exit.Exit<Value, Error>) => Duration.DurationInput
+  }
+) => Effect.Effect<ScopedCache<Key, Value, Error>, never, Scope.Scope | Environment> = internal.makeWith
+
+/**
+ * Similar to `Cache.Lookup`, but executes the lookup function within a `Scope`.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export type Lookup<Key, Value, Error = never, Environment = never> = (
+  key: Key
+) => Effect.Effect<Value, Error, Environment | Scope.Scope>

package/src/ScopedRef.ts

@@ -0,0 +1,117 @@
+/**
+ * @since 2.0.0
+ */
+import type * as Effect from "./Effect.js"
+import type { LazyArg } from "./Function.js"
+import * as internal from "./internal/scopedRef.js"
+import type { Pipeable } from "./Pipeable.js"
+import type * as Scope from "./Scope.js"
+import type * as Synchronized from "./SynchronizedRef.js"
+import type * as Types from "./Types.js"
+import type * as Unify from "./Unify.js"
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export const ScopedRefTypeId: unique symbol = internal.ScopedRefTypeId
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export type ScopedRefTypeId = typeof ScopedRefTypeId
+
+/**
+ * A `ScopedRef` is a reference whose value is associated with resources,
+ * which must be released properly. You can both get the current value of any
+ * `ScopedRef`, as well as set it to a new value (which may require new
+ * resources). The reference itself takes care of properly releasing resources
+ * for the old value whenever a new value is obtained.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export interface ScopedRef<in out A> extends Effect.Effect<A>, ScopedRef.Variance<A>, Pipeable {
+  /** @internal */
+  readonly ref: Synchronized.SynchronizedRef<readonly [Scope.Scope.Closeable, A]>
+
+  readonly [Unify.typeSymbol]?: unknown
+  readonly [Unify.unifySymbol]?: ScopedRefUnify<this>
+  readonly [Unify.ignoreSymbol]?: ScopedRefUnifyIgnore
+}
+
+/**
+ * @category models
+ * @since 3.9.0
+ */
+export interface ScopedRefUnify<A extends { [Unify.typeSymbol]?: any }> extends Effect.EffectUnify<A> {
+  ScopedRef?: () => Extract<A[Unify.typeSymbol], ScopedRef<any>>
+}
+
+/**
+ * @category models
+ * @since 3.9.0
+ */
+export interface ScopedRefUnifyIgnore extends Effect.EffectUnifyIgnore {
+  Effect?: true
+}
+
+/**
+ * @since 2.0.0
+ */
+export declare namespace ScopedRef {
+  /**
+   * @since 2.0.0
+   * @category models
+   */
+  export interface Variance<in out A> {
+    readonly [ScopedRefTypeId]: {
+      readonly _A: Types.Invariant<A>
+    }
+  }
+}
+
+/**
+ * Creates a new `ScopedRef` from an effect that resourcefully produces a
+ * value.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const fromAcquire: <A, E, R>(
+  acquire: Effect.Effect<A, E, R>
+) => Effect.Effect<ScopedRef<A>, E, Scope.Scope | R> = internal.fromAcquire
+
+/**
+ * Retrieves the current value of the scoped reference.
+ *
+ * @since 2.0.0
+ * @category getters
+ */
+export const get: <A>(self: ScopedRef<A>) => Effect.Effect<A> = internal.get
+
+/**
+ * Creates a new `ScopedRef` from the specified value. This method should
+ * not be used for values whose creation require the acquisition of resources.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const make: <A>(evaluate: LazyArg<A>) => Effect.Effect<ScopedRef<A>, never, Scope.Scope> = internal.make
+
+/**
+ * Sets the value of this reference to the specified resourcefully-created
+ * value. Any resources associated with the old value will be released.
+ *
+ * This method will not return until either the reference is successfully
+ * changed to the new value, with old resources released, or until the attempt
+ * to acquire a new value fails.
+ *
+ * @since 2.0.0
+ * @category getters
+ */
+export const set: {
+  <A, R, E>(acquire: Effect.Effect<A, E, R>): (self: ScopedRef<A>) => Effect.Effect<void, E, Exclude<R, Scope.Scope>>
+  <A, R, E>(self: ScopedRef<A>, acquire: Effect.Effect<A, E, R>): Effect.Effect<void, E, Exclude<R, Scope.Scope>>
+} = internal.set

package/src/Secret.ts

@@ -0,0 +1,88 @@
+/**
+ * @since 2.0.0
+ * @deprecated
+ */
+import type * as Equal from "./Equal.js"
+import * as InternalSecret from "./internal/secret.js"
+import type * as Redacted from "./Redacted.js"
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ * @deprecated
+ */
+export const SecretTypeId: unique symbol = InternalSecret.SecretTypeId
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ * @deprecated
+ */
+export type SecretTypeId = typeof SecretTypeId
+
+/**
+ * @since 2.0.0
+ * @category models
+ * @deprecated
+ */
+export interface Secret extends Redacted.Redacted, Secret.Proto, Equal.Equal {
+  /** @internal */
+  readonly raw: Array<number>
+}
+
+/**
+ * @since 2.0.0
+ * @deprecated
+ */
+export declare namespace Secret {
+  /**
+   * @since 2.0.0
+   * @category models
+   * @deprecated
+   */
+  export interface Proto {
+    readonly [SecretTypeId]: SecretTypeId
+  }
+}
+
+/**
+ * @since 2.0.0
+ * @category refinements
+ * @deprecated
+ */
+export const isSecret: (u: unknown) => u is Secret = InternalSecret.isSecret
+
+/**
+ * @since 2.0.0
+ * @category constructors
+ * @deprecated
+ */
+export const make: (bytes: Array<number>) => Secret = InternalSecret.make
+
+/**
+ * @since 2.0.0
+ * @category constructors
+ * @deprecated
+ */
+export const fromIterable: (iterable: Iterable<string>) => Secret = InternalSecret.fromIterable
+
+/**
+ * @since 2.0.0
+ * @category constructors
+ * @deprecated
+ */
+export const fromString: (text: string) => Secret = InternalSecret.fromString
+
+/**
+ * @since 2.0.0
+ * @category getters
+ * @deprecated
+ */
+export const value: (self: Secret) => string = InternalSecret.value
+
+/**
+ * @since 2.0.0
+ * @category unsafe
+ * @deprecated
+ */
+export const unsafeWipe: (self: Secret) => void = InternalSecret.unsafeWipe

package/src/SingleProducerAsyncInput.ts

@@ -0,0 +1,67 @@
+/**
+ * @since 2.0.0
+ */
+import type * as Cause from "./Cause.js"
+import type * as Effect from "./Effect.js"
+import type * as Either from "./Either.js"
+import type * as Exit from "./Exit.js"
+import * as internal from "./internal/channel/singleProducerAsyncInput.js"
+
+/**
+ * An MVar-like abstraction for sending data to channels asynchronously which is
+ * designed for one producer and multiple consumers.
+ *
+ * Features the following semantics:
+ *   - Buffer of size 1.
+ *   - When emitting, the producer waits for a consumer to pick up the value to
+ *     prevent "reading ahead" too much.
+ *   - Once an emitted element is read by a consumer, it is cleared from the
+ *     buffer, so that at most one consumer sees every emitted element.
+ *   - When sending a done or error signal, the producer does not wait for a
+ *     consumer to pick up the signal. The signal stays in the buffer after
+ *     being read by a consumer, so it can be propagated to multiple consumers.
+ *   - Trying to publish another emit/error/done after an error/done have
+ *     already been published results in an interruption.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export interface SingleProducerAsyncInput<in out Err, in out Elem, in out Done>
+  extends AsyncInputProducer<Err, Elem, Done>, AsyncInputConsumer<Err, Elem, Done>
+{
+  readonly close: Effect.Effect<unknown>
+  readonly take: Effect.Effect<Exit.Exit<Elem, Either.Either<Done, Err>>>
+}
+
+/**
+ * Producer-side view of `SingleProducerAsyncInput` for variance purposes.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export interface AsyncInputProducer<in Err, in Elem, in Done> {
+  awaitRead(): Effect.Effect<unknown>
+  done(value: Done): Effect.Effect<unknown>
+  emit(element: Elem): Effect.Effect<unknown>
+  error(cause: Cause.Cause<Err>): Effect.Effect<unknown>
+}
+
+/**
+ * Consumer-side view of `SingleProducerAsyncInput` for variance purposes.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export interface AsyncInputConsumer<out Err, out Elem, out Done> {
+  takeWith<A>(
+    onError: (cause: Cause.Cause<Err>) => A,
+    onElement: (element: Elem) => A,
+    onDone: (value: Done) => A
+  ): Effect.Effect<A>
+}
+
+/**
+ * @since 2.0.0
+ * @category constructors
+ */
+export const make: <Err, Elem, Done>() => Effect.Effect<SingleProducerAsyncInput<Err, Elem, Done>> = internal.make