effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/SchemaUtils.ts

@@ -25,6 +25,8 @@ import * as Transformation from "./SchemaTransformation.ts"
  * Builds an experimental schema for instances of a native class using a struct
  * schema as the encoded representation.
  *
+ * **Details**
+ *
  * Decoding constructs `new constructor(props)` from the encoded fields.
  * Encoding uses the instance as the encoded shape, so the class should expose
  * properties compatible with the provided encoding schema.

package/src/Scope.ts

@@ -110,10 +110,12 @@ export interface Closeable extends Scope {
  *
  * @since 4.0.0
  */
-export namespace State {
+export declare namespace State {
   /**
    * Represents an open scope with no registered finalizers yet.
    *
+   * **Details**
+   *
    * Adding the first finalizer transitions the scope to `Open`; closing an
    * empty scope transitions directly to `Closed` without producing a finalizer
    * effect.
@@ -358,6 +360,8 @@ export const provide: {
 /**
  * Registers an exit-aware finalizer on a scope.
  *
+ * **Details**
+ *
  * If the scope is open, the finalizer runs when the scope closes and receives
  * the scope's exit value. If the scope is already closed, the finalizer runs
  * immediately with the stored exit value.
@@ -398,6 +402,8 @@ export const addFinalizerExit: (scope: Scope, finalizer: (exit: Exit<any, any>)
 /**
  * Registers a finalizer effect on a scope.
  *
+ * **Details**
+ *
  * If the scope is open, the finalizer runs when the scope closes, regardless of
  * whether the scope closes successfully or with an error. If the scope is
  * already closed, the finalizer runs immediately.
@@ -431,6 +437,8 @@ export const addFinalizer: (scope: Scope, finalizer: Effect<unknown>) => Effect<
 /**
  * Creates a closeable child scope registered with a parent scope.
  *
+ * **Details**
+ *
  * Closing the parent closes the child with the same exit value, and closing the
  * child detaches it from the parent. The optional finalizer strategy configures
  * the child scope and defaults to `"sequential"` when omitted.
@@ -469,6 +477,8 @@ export const fork: (
 /**
  * Synchronously creates a closeable child scope registered with a parent scope.
  *
+ * **Details**
+ *
  * Closing the parent closes the child with the same exit value, and closing the
  * child detaches it from the parent. The optional finalizer strategy configures
  * the child scope and defaults to `"sequential"` when omitted.
@@ -532,6 +542,8 @@ export const close: <A, E>(self: Scope, exit: Exit<A, E>) => Effect<void> = effe
 /**
  * Unsafely transitions a scope to `Closed` with the provided exit value.
  *
+ * **Details**
+ *
  * Returns an effect that runs registered finalizers, or `undefined` when the
  * scope was already closed or no finalizers need to run. Prefer `close` unless
  * you are implementing lower-level scope machinery and can correctly run the
@@ -547,6 +559,8 @@ export const closeUnsafe: <A, E>(self: Scope, exit_: Exit<A, E>) => Effect<void,
  * Runs an effect with the provided closeable scope in its context and closes
  * that scope when the effect exits.
  *
+ * **Details**
+ *
  * The scope is closed with the same exit value as the effect, so registered
  * finalizers can observe whether the effect succeeded, failed, or was
  * interrupted.
@@ -559,6 +573,8 @@ export const use: {
    * Runs an effect with the provided closeable scope in its context and closes
    * that scope when the effect exits.
    *
+   * **Details**
+   *
    * The scope is closed with the same exit value as the effect, so registered
    * finalizers can observe whether the effect succeeded, failed, or was
    * interrupted.
@@ -571,6 +587,8 @@ export const use: {
    * Runs an effect with the provided closeable scope in its context and closes
    * that scope when the effect exits.
    *
+   * **Details**
+   *
    * The scope is closed with the same exit value as the effect, so registered
    * finalizers can observe whether the effect succeeded, failed, or was
    * interrupted.

package/src/ScopedCache.ts

@@ -48,6 +48,8 @@ const TypeId = "~effect/ScopedCache"
  * A scoped cache whose values are acquired by a lookup effect and stored in
  * per-entry scopes.
  *
+ * **Details**
+ *
  * Concurrent requests for the same key share the same in-flight lookup.
  * Entries can expire based on the lookup exit, are evicted when capacity is
  * exceeded, and release their entry scopes when invalidated, evicted, expired,
@@ -67,6 +69,8 @@ export interface ScopedCache<in out Key, in out A, in out E = never, out R = nev
 /**
  * Represents whether a `ScopedCache` is open or closed.
  *
+ * **Details**
+ *
  * `Open` stores cached entries in access order for reuse and eviction.
  * `Closed` means the owning scope has closed and the cache can no longer
  * perform lookup operations.
@@ -84,6 +88,8 @@ export type State<K, A, E> = {
 /**
  * A single scoped cache entry.
  *
+ * **Details**
+ *
  * The entry contains the deferred lookup result shared by readers, the scope
  * that owns resources acquired while computing the value, and an optional
  * expiration time in milliseconds. Removing the entry closes its scope.
@@ -101,6 +107,8 @@ export interface Entry<A, E> {
  * Creates a `ScopedCache` from a lookup function, maximum capacity, and a
  * time-to-live function computed from each lookup exit and key.
  *
+ * **Details**
+ *
  * The cache must be constructed in a `Scope`. Each lookup runs in its own entry
  * scope, and that scope is closed when the entry expires, is invalidated, is
  * evicted by capacity, or when the cache's owning scope closes.
@@ -155,6 +163,8 @@ export const makeWith = <
 /**
  * Creates a `ScopedCache` with a fixed time-to-live for every lookup result.
  *
+ * **Details**
+ *
  * This is the constant-TTL variant of `makeWith`: values are acquired by the
  * lookup effect in per-entry scopes, capacity can evict older entries, and
  * entry scopes are closed when entries expire, are invalidated, are evicted, or
@@ -204,6 +214,8 @@ const defaultTimeToLive = <A, E>(_: Exit.Exit<A, E>, _key: unknown): Duration.Du
  * Gets the value for a key, running the cache lookup when no unexpired entry is
  * present.
  *
+ * **Details**
+ *
  * Concurrent `get` calls for the same key share the same in-flight lookup.
  * Successful and failed lookup exits are cached according to the configured
  * TTL. If the cache is closed, the effect is interrupted.
@@ -216,6 +228,8 @@ export const get: {
    * Gets the value for a key, running the cache lookup when no unexpired entry is
    * present.
    *
+   * **Details**
+   *
    * Concurrent `get` calls for the same key share the same in-flight lookup.
    * Successful and failed lookup exits are cached according to the configured
    * TTL. If the cache is closed, the effect is interrupted.
@@ -228,6 +242,8 @@ export const get: {
    * Gets the value for a key, running the cache lookup when no unexpired entry is
    * present.
    *
+   * **Details**
+   *
    * Concurrent `get` calls for the same key share the same in-flight lookup.
    * Successful and failed lookup exits are cached according to the configured
    * TTL. If the cache is closed, the effect is interrupted.
@@ -257,6 +273,8 @@ export const get: {
          * Gets the value for a key, running the cache lookup when no unexpired entry is
          * present.
          *
+         * **Details**
+         *
          * Concurrent `get` calls for the same key share the same in-flight lookup.
          * Successful and failed lookup exits are cached according to the configured
          * TTL. If the cache is closed, the effect is interrupted.
@@ -268,6 +286,8 @@ export const get: {
          * Gets the value for a key, running the cache lookup when no unexpired entry is
          * present.
          *
+         * **Details**
+         *
          * Concurrent `get` calls for the same key share the same in-flight lookup.
          * Successful and failed lookup exits are cached according to the configured
          * TTL. If the cache is closed, the effect is interrupted.
@@ -327,6 +347,8 @@ const checkCapacity = <K, A, E>(
 /**
  * Reads an existing unexpired cache entry without running the lookup function.
  *
+ * **Details**
+ *
  * Returns `Option.none` when the key is absent or expired. If an entry exists,
  * the effect waits for its cached result and returns `Option.some(value)` on
  * success, or fails with the cached lookup error.
@@ -338,6 +360,8 @@ export const getOption: {
   /**
    * Reads an existing unexpired cache entry without running the lookup function.
    *
+   * **Details**
+   *
    * Returns `Option.none` when the key is absent or expired. If an entry exists,
    * the effect waits for its cached result and returns `Option.some(value)` on
    * success, or fails with the cached lookup error.
@@ -349,6 +373,8 @@ export const getOption: {
   /**
    * Reads an existing unexpired cache entry without running the lookup function.
    *
+   * **Details**
+   *
    * Returns `Option.none` when the key is absent or expired. If an entry exists,
    * the effect waits for its cached result and returns `Option.some(value)` on
    * success, or fails with the cached lookup error.
@@ -442,6 +468,8 @@ export const getSuccess: {
 /**
  * Stores a successful value for a key without running the lookup function.
  *
+ * **Details**
+ *
  * This replaces and closes any existing entry scope for the key, applies the
  * cache's TTL using a successful exit for the value, and may evict older
  * entries if the cache capacity is exceeded.
@@ -453,6 +481,8 @@ export const set: {
   /**
    * Stores a successful value for a key without running the lookup function.
    *
+   * **Details**
+   *
    * This replaces and closes any existing entry scope for the key, applies the
    * cache's TTL using a successful exit for the value, and may evict older
    * entries if the cache capacity is exceeded.
@@ -464,6 +494,8 @@ export const set: {
   /**
    * Stores a successful value for a key without running the lookup function.
    *
+   * **Details**
+   *
    * This replaces and closes any existing entry scope for the key, applies the
    * cache's TTL using a successful exit for the value, and may evict older
    * entries if the cache capacity is exceeded.
@@ -486,6 +518,8 @@ export const set: {
         const deferred = Deferred.makeUnsafe</**
          * Stores a successful value for a key without running the lookup function.
          *
+         * **Details**
+         *
          * This replaces and closes any existing entry scope for the key, applies the
          * cache's TTL using a successful exit for the value, and may evict older
          * entries if the cache capacity is exceeded.
@@ -496,6 +530,8 @@ export const set: {
         A, /**
          * Stores a successful value for a key without running the lookup function.
          *
+         * **Details**
+         *
          * This replaces and closes any existing entry scope for the key, applies the
          * cache's TTL using a successful exit for the value, and may evict older
          * entries if the cache capacity is exceeded.
@@ -553,6 +589,8 @@ export const has: {
 /**
  * Removes the entry associated with a key and closes its entry scope.
  *
+ * **Details**
+ *
  * If the key is absent, this is a no-op. If the cache is closed, the effect is
  * interrupted.
  *
@@ -563,6 +601,8 @@ export const invalidate: {
   /**
    * Removes the entry associated with a key and closes its entry scope.
    *
+   * **Details**
+   *
    * If the key is absent, this is a no-op. If the cache is closed, the effect is
    * interrupted.
    *
@@ -573,6 +613,8 @@ export const invalidate: {
   /**
    * Removes the entry associated with a key and closes its entry scope.
    *
+   * **Details**
+   *
    * If the key is absent, this is a no-op. If the cache is closed, the effect is
    * interrupted.
    *
@@ -648,6 +690,8 @@ export const invalidateWhen: {
 /**
  * Forces a refresh of the value associated with the specified key in the cache.
  *
+ * **Details**
+ *
  * It will always invoke the lookup function to construct a new value,
  * overwriting any existing value for that key.
  *
@@ -658,6 +702,8 @@ export const refresh: {
   /**
    * Forces a refresh of the value associated with the specified key in the cache.
    *
+   * **Details**
+   *
    * It will always invoke the lookup function to construct a new value,
    * overwriting any existing value for that key.
    *
@@ -668,6 +714,8 @@ export const refresh: {
   /**
    * Forces a refresh of the value associated with the specified key in the cache.
    *
+   * **Details**
+   *
    * It will always invoke the lookup function to construct a new value,
    * overwriting any existing value for that key.
    *
@@ -685,6 +733,8 @@ export const refresh: {
       const deferred = Deferred.makeUnsafe</**
        * Forces a refresh of the value associated with the specified key in the cache.
        *
+       * **Details**
+       *
        * It will always invoke the lookup function to construct a new value,
        * overwriting any existing value for that key.
        *
@@ -694,6 +744,8 @@ export const refresh: {
       A, /**
        * Forces a refresh of the value associated with the specified key in the cache.
        *
+       * **Details**
+       *
        * It will always invoke the lookup function to construct a new value,
        * overwriting any existing value for that key.
        *
@@ -738,6 +790,8 @@ export const refresh: {
 /**
  * Removes every entry from the cache and closes each entry scope.
  *
+ * **Details**
+ *
  * If the cache is closed, the effect is interrupted.
  *
  * @category combinators
@@ -766,6 +820,8 @@ const invalidateAllImpl = <Key, A, E>(
 /**
  * Retrieves the approximate number of entries in the cache.
  *
+ * **Gotchas**
+ *
  * Note that expired entries are counted until they are accessed and removed.
  * The size reflects the current number of entries stored, not the number
  * of valid entries.

package/src/ScopedRef.ts

@@ -121,7 +121,9 @@ export const make = <A>(evaluate: LazyArg<A>): Effect.Effect<ScopedRef<A>, never
 
 /**
  * Sets the value of this reference to the specified resourcefully-created
- * value. Any resources associated with the old value will be released.
+ * value, releasing any resources associated with the old value.
+ *
+ * **Details**
  *
  * This method will not return until either the reference is successfully
  * changed to the new value, with old resources released, or until the attempt
@@ -133,7 +135,9 @@ export const make = <A>(evaluate: LazyArg<A>): Effect.Effect<ScopedRef<A>, never
 export const set: {
   /**
    * Sets the value of this reference to the specified resourcefully-created
-   * value. Any resources associated with the old value will be released.
+   * value, releasing any resources associated with the old value.
+   *
+   * **Details**
    *
    * This method will not return until either the reference is successfully
    * changed to the new value, with old resources released, or until the attempt
@@ -145,7 +149,9 @@ export const set: {
   <A, R, E>(acquire: Effect.Effect<A, E, R>): (self: ScopedRef<A>) => Effect.Effect<void, E, Exclude<R, Scope.Scope>>
   /**
    * Sets the value of this reference to the specified resourcefully-created
-   * value. Any resources associated with the old value will be released.
+   * value, releasing any resources associated with the old value.
+   *
+   * **Details**
    *
    * This method will not return until either the reference is successfully
    * changed to the new value, with old resources released, or until the attempt

package/src/Semaphore.ts

@@ -30,6 +30,8 @@ import type * as Option from "./Option.ts"
 /**
  * A counting semaphore that coordinates concurrent access with permits.
  *
+ * **Details**
+ *
  * Effects can acquire permits, wait until enough permits are available,
  * release permits, or run with permits that are automatically released when
  * the effect exits.
@@ -123,6 +125,8 @@ export interface Semaphore {
  * Synchronously creates a `Semaphore` initialized with the specified total
  * number of permits.
  *
+ * **When to use**
+ *
  * Use this low-level constructor when an immediate semaphore value is required;
  * otherwise prefer the effectful `make` constructor.
  *
@@ -264,6 +268,8 @@ class SemaphoreImpl implements Semaphore {
 /**
  * Creates a `Semaphore` initialized with the specified total number of permits.
  *
+ * **When to use**
+ *
  * Use the returned semaphore to limit concurrency with `withPermit` or
  * `withPermits`, or to manually `take` and `release` permits.
  *