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

package/src/Scope.ts

@@ -0,0 +1,171 @@
+/**
+ * @since 2.0.0
+ */
+
+import type * as Context from "./Context"
+import type * as Effect from "./Effect"
+import type * as ExecutionStrategy from "./ExecutionStrategy"
+import type * as Exit from "./Exit"
+import * as core from "./internal/core"
+import * as fiberRuntime from "./internal/fiberRuntime"
+import type { Pipeable } from "./Pipeable"
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export const ScopeTypeId: unique symbol = core.ScopeTypeId
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export type ScopeTypeId = typeof ScopeTypeId
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export const CloseableScopeTypeId: unique symbol = core.CloseableScopeTypeId
+
+/**
+ * @since 2.0.0
+ * @category symbols
+ */
+export type CloseableScopeTypeId = typeof CloseableScopeTypeId
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface Scope extends Pipeable {
+  readonly [ScopeTypeId]: ScopeTypeId
+  readonly strategy: ExecutionStrategy.ExecutionStrategy
+  /**
+   * @internal
+   */
+  readonly fork: (strategy: ExecutionStrategy.ExecutionStrategy) => Effect.Effect<never, never, Scope.Closeable>
+  /**
+   * @internal
+   */
+  readonly addFinalizer: (finalizer: Scope.Finalizer) => Effect.Effect<never, never, void>
+}
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export interface CloseableScope extends Scope, Pipeable {
+  readonly [CloseableScopeTypeId]: CloseableScopeTypeId
+
+  /**
+   * @internal
+   */
+  readonly close: (exit: Exit.Exit<unknown, unknown>) => Effect.Effect<never, never, void>
+}
+
+/**
+ * @since 2.0.0
+ * @category context
+ */
+export const Scope: Context.Tag<Scope, Scope> = fiberRuntime.scopeTag
+
+/**
+ * @since 2.0.0
+ */
+export declare namespace Scope {
+  /**
+   * @since 2.0.0
+   * @category model
+   */
+  export type Finalizer = (exit: Exit.Exit<unknown, unknown>) => Effect.Effect<never, never, void>
+  /**
+   * @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.
+ *
+ * @since 2.0.0
+ * @category utils
+ */
+export const addFinalizer: (
+  self: Scope,
+  finalizer: Effect.Effect<never, never, unknown>
+) => Effect.Effect<never, never, void> = core.scopeAddFinalizer
+
+/**
+ * A simplified version of `addFinalizerWith` when the `finalizer` does not
+ * depend on the `Exit` value that the scope is closed with.
+ *
+ * @since 2.0.0
+ * @category utils
+ */
+export const addFinalizerExit: (self: Scope, finalizer: Scope.Finalizer) => Effect.Effect<never, never, void> =
+  core.scopeAddFinalizerExit
+
+/**
+ * Closes a 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<never, never, void> =
+  core.scopeClose
+
+/**
+ * Extends the scope of an `Effect` workflow that needs a scope into this
+ * scope by providing it to the workflow but not closing the scope when the
+ * workflow completes execution. This allows extending a scoped value into a
+ * larger scope.
+ *
+ * @since 2.0.0
+ * @category utils
+ */
+export const extend: {
+  (scope: Scope): <R, E, A>(effect: Effect.Effect<R, E, A>) => Effect.Effect<Exclude<R, Scope>, E, A>
+  <R, E, A>(effect: Effect.Effect<R, E, A>, scope: Scope): Effect.Effect<Exclude<R, Scope>, E, A>
+} = fiberRuntime.scopeExtend
+
+/**
+ * Forks a new scope that is a child of this scope. 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<never, never, CloseableScope> = core.scopeFork
+
+/**
+ * Uses the scope by providing it to an `Effect` workflow that needs a scope,
+ * guaranteeing that the scope is closed with the result of that workflow as
+ * soon as the workflow completes execution, whether by success, failure, or
+ * interruption.
+ *
+ * @since 2.0.0
+ * @category destructors
+ */
+export const use: {
+  (scope: CloseableScope): <R, E, A>(effect: Effect.Effect<R, E, A>) => Effect.Effect<Exclude<R, Scope>, E, A>
+  <R, E, A>(effect: Effect.Effect<R, E, A>, scope: CloseableScope): Effect.Effect<Exclude<R, Scope>, E, A>
+} = fiberRuntime.scopeUse
+
+/**
+ * Creates a Scope where Finalizers will run according to the `ExecutionStrategy`.
+ *
+ * If an ExecutionStrategy is not provided `sequential` will be used.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const make: (
+  executionStrategy?: ExecutionStrategy.ExecutionStrategy
+) => Effect.Effect<never, never, CloseableScope> = fiberRuntime.scopeMake

package/src/ScopedCache.ts

@@ -0,0 +1,148 @@
+/**
+ * @since 2.0.0
+ */
+import type * as Cache from "./Cache"
+import type * as Duration from "./Duration"
+import type * as Effect from "./Effect"
+import type * as Exit from "./Exit"
+import * as internal from "./internal/scopedCache"
+import type * as Option from "./Option"
+import type { Pipeable } from "./Pipeable"
+import type * as Scope from "./Scope"
+
+/**
+ * @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<Key, Error, Value> extends ScopedCache.Variance<Key, Error, Value>, Pipeable {
+  /**
+   * Retrieves the value associated with the specified key if it exists.
+   * Otherwise returns `Option.none`.
+   */
+  getOption(key: Key): Effect.Effect<Scope.Scope, Error, Option.Option<Value>>
+
+  /**
+   * 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<Scope.Scope, never, Option.Option<Value>>
+
+  /**
+   * Returns statistics for this cache.
+   */
+  cacheStats(): Effect.Effect<never, never, 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<never, never, boolean>
+
+  /**
+   * Return statistics for the specified entry.
+   */
+  entryStats(key: Key): Effect.Effect<never, never, 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<Scope.Scope, Error, Value>
+
+  /**
+   * Invalidates the resource associated with the specified key.
+   */
+  invalidate(key: Key): Effect.Effect<never, never, void>
+
+  /**
+   * Invalidates all values in the cache.
+   */
+  invalidateAll(): Effect.Effect<never, never, 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<never, Error, void>
+
+  /**
+   * Returns the approximate number of values in the cache.
+   */
+  size(): Effect.Effect<never, never, number>
+}
+
+/**
+ * @since 2.0.0
+ */
+export declare namespace ScopedCache {
+  /**
+   * @since 2.0.0
+   * @category models
+   */
+  export interface Variance<Key, Error, Value> {
+    readonly [ScopedCacheTypeId]: {
+      _Key: (_: Key) => void
+      _Error: (_: never) => Error
+      _Value: (_: never) => 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, Environment, Error, Value>(
+  options: {
+    readonly lookup: Lookup<Key, Environment, Error, Value>
+    readonly capacity: number
+    readonly timeToLive: Duration.DurationInput
+  }
+) => Effect.Effect<Scope.Scope | Environment, never, ScopedCache<Key, Error, Value>> = 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, Environment, Error, Value>(
+  options: {
+    readonly capacity: number
+    readonly lookup: Lookup<Key, Environment, Error, Value>
+    readonly timeToLive: (exit: Exit.Exit<Error, Value>) => Duration.DurationInput
+  }
+) => Effect.Effect<Scope.Scope | Environment, never, ScopedCache<Key, Error, Value>> = internal.makeWith
+
+/**
+ * Similar to `Cache.Lookup`, but executes the lookup function within a `Scope`.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export type Lookup<Key, Environment, Error, Value> = (
+  key: Key
+) => Effect.Effect<Environment | Scope.Scope, Error, Value>

package/src/ScopedRef.ts

@@ -0,0 +1,95 @@
+/**
+ * @since 2.0.0
+ */
+import type * as Effect from "./Effect"
+import type { LazyArg } from "./Function"
+import * as internal from "./internal/scopedRef"
+import type { Pipeable } from "./Pipeable"
+import type * as Scope from "./Scope"
+import type * as Synchronized from "./SynchronizedRef"
+
+/**
+ * @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<A> extends ScopedRef.Variance<A>, Pipeable {
+  /** @internal */
+  readonly ref: Synchronized.SynchronizedRef<readonly [Scope.Scope.Closeable, A]>
+}
+
+/**
+ * @since 2.0.0
+ */
+export declare namespace ScopedRef {
+  /**
+   * @since 2.0.0
+   * @category models
+   */
+  export interface Variance<A> {
+    readonly [ScopedRefTypeId]: {
+      readonly _A: (_: never) => A
+    }
+  }
+}
+
+/**
+ * Creates a new `ScopedRef` from an effect that resourcefully produces a
+ * value.
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const fromAcquire: <R, E, A>(
+  acquire: Effect.Effect<R, E, A>
+) => Effect.Effect<Scope.Scope | R, E, ScopedRef<A>> = 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<never, never, 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<Scope.Scope, never, ScopedRef<A>> = 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<R, E, A>): (self: ScopedRef<A>) => Effect.Effect<Exclude<R, Scope.Scope>, E, void>
+  <A, R, E>(self: ScopedRef<A>, acquire: Effect.Effect<R, E, A>): Effect.Effect<Exclude<R, Scope.Scope>, E, void>
+} = internal.set