effect 4.0.0-rc.118 → 4.0.1

package/src/Pool.ts

@@ -19,7 +19,6 @@ import * as Fiber from "./Fiber.ts"
 import { constant, dual, identity } from "./Function.ts"
 import * as core from "./internal/core.ts"
 import * as internal from "./internal/effect.ts"
-import * as Iterable from "./Iterable.ts"
 import { type Pipeable, pipeArguments } from "./Pipeable.ts"
 import { hasProperty } from "./Predicate.ts"
 import * as Queue from "./Queue.ts"
@@ -31,10 +30,12 @@ const TypeId = "~effect/Pool"
 
 const Acquire = Symbol()
 const AcquireContext = Symbol()
+const PoolClock = Symbol()
 
 interface PoolImpl<A, E> extends Pool<A, E> {
   readonly [Acquire]: Effect.Effect<A, E, Scope.Scope>
   readonly [AcquireContext]: Context.Context<Scope.Scope>
+  readonly [PoolClock]: Clock
 }
 
 /**
@@ -119,7 +120,6 @@ export interface State<A, E> {
   isShuttingDown: boolean
   usage: number
   readonly resizeSemaphore: Semaphore.Semaphore
-  // Insertion order determines usage-TTL retirement order; reclaimed items move to the back.
   readonly items: Set<PoolItem<A, E>>
   availableHead: PoolItem<A, E> | undefined
   availableTail: PoolItem<A, E> | undefined
@@ -139,8 +139,8 @@ export interface State<A, E> {
  * **Details**
  *
  * Each item stores the acquisition `Exit`, its finalizer, the current
- * reference count, and whether automatic reclaiming has been disabled because
- * the item was invalidated.
+ * reference count, when it last became idle, and whether automatic reclaiming
+ * has been disabled because the item was invalidated.
  *
  * @see {@link Strategy} for the custom strategy callbacks that receive and return pool items
  * @see {@link State} for the runtime sets that store active, available, and invalidated pool items
@@ -152,6 +152,8 @@ export interface PoolItem<A, E> {
   readonly exit: Exit.Exit<A, E>
   finalizer: Effect.Effect<void>
   refCount: number
+  /** Clock time at which the item was acquired or its last borrower released it. */
+  idleSince: number
   disableReclaim: boolean
   isAvailable: boolean
   availablePrevious: PoolItem<A, E> | undefined
@@ -257,9 +259,11 @@ export const make = <A, E, R>(options: {
  * pool implementation. A value of `1` waits until existing items are fully
  * utilized before creating more items.
  *
- * `timeToLiveStrategy` controls when excess items expire: `"creation"` measures
- * from item creation, while `"usage"` measures from pool usage. The default is
- * `"usage"`.
+ * `timeToLiveStrategy` defaults to `"usage"`, which expires idle, unreserved
+ * excess items after `timeToLive` since their last borrower released them
+ * (or acquisition if never borrowed). It checks once per `timeToLive`, so
+ * retirement can take up to twice that duration. `"creation"` measures from
+ * item creation instead.
  *
  * **Example** (Creating a connection pool)
  *
@@ -374,6 +378,7 @@ export const makeWithStrategy = <A, E, R>(options: {
       [TypeId]: TypeId,
       [Acquire]: options.acquire as Effect.Effect<A, E, Scope.Scope>,
       [AcquireContext]: services as Context.Context<Scope.Scope>,
+      [PoolClock]: yield* Clock,
       config,
       state,
       pipe() {
@@ -676,6 +681,9 @@ const releaseItem = <A, E>(self: Pool<A, E>, item: PoolItem<A, E>): Effect.Effec
     const state = self.state
     item.refCount--
     state.usage--
+    if (item.refCount === 0) {
+      item.idleSince = (self as PoolImpl<A, E>)[PoolClock].currentTimeMillisUnsafe()
+    }
     if (state.invalidated.has(item)) {
       return invalidatePoolItem(self, item)
     }
@@ -1014,6 +1022,7 @@ const allocate = <A, E>(self: Pool<A, E>): Effect.Effect<PoolItem<A, E>> =>
           exit,
           finalizer: Effect.catchCause(Scope.close(scope, exit), reportUnhandledError),
           refCount: 0,
+          idleSince: impl[PoolClock].currentTimeMillisUnsafe(),
           disableReclaim: false,
           isAvailable: false,
           availablePrevious: undefined,
@@ -1110,19 +1119,21 @@ const strategyCreationTTL = Effect.fnUntraced(function*<A, E>(ttl: Duration.Inpu
   })
 })
 
-const strategyUsageTTL = <A, E>(ttl: Duration.Input): Effect.Effect<Strategy<A, E>> =>
-  Effect.succeed<Strategy<A, E>>({
+const strategyUsageTTL = Effect.fnUntraced(function*<A, E>(ttl: Duration.Input) {
+  const clock = yield* Clock
+  const ttlMillis = Duration.toMillis(Duration.fromInputUnsafe(ttl))
+  return identity<Strategy<A, E>>({
     run: (pool) => {
-      // `state.items` iterates in insertion order, so its oldest live entry is
-      // the next to retire. Using it directly means an item stops being
-      // referenced by this strategy as soon as it leaves the pool.
       const process: Effect.Effect<void> = Effect.suspend(() => {
         if (activeSize(pool) <= targetSize(pool)) return Effect.void
+        const expired = clock.currentTimeMillisUnsafe() - ttlMillis
+        let oldest: PoolItem<A, E> | undefined
         for (const item of pool.state.items) {
-          if (pool.state.invalidated.has(item)) continue
-          return Effect.flatMap(invalidatePoolItem(pool, item), () => process)
+          if (item.refCount > 0 || item.idleSince > expired) continue
+          if (pool.state.invalidated.has(item) || reservations.has(item)) continue
+          if (oldest === undefined || item.idleSince < oldest.idleSince) oldest = item
         }
-        return Effect.void
+        return oldest === undefined ? Effect.void : Effect.flatMap(invalidatePoolItem(pool, oldest), () => process)
       })
       return process.pipe(
         Effect.delay(ttl),
@@ -1130,28 +1141,9 @@ const strategyUsageTTL = <A, E>(ttl: Duration.Input): Effect.Effect<Strategy<A,
       )
     },
     onAcquire: (_) => Effect.void,
-    reclaim(pool) {
-      return Effect.suspend((): Effect.Effect<PoolItem<A, E> | undefined> => {
-        if (pool.state.invalidated.size === 0) {
-          return Effect.undefined
-        }
-        const item = Iterable.head(
-          Iterable.filter(pool.state.invalidated, (item) => !item.disableReclaim && !reservations.has(item))
-        )
-        if (item._tag === "None") {
-          return Effect.undefined
-        }
-        pool.state.invalidated.delete(item.value)
-        // Re-adding moves the reclaimed item to the back of the retirement order.
-        pool.state.items.delete(item.value)
-        pool.state.items.add(item.value)
-        if (item.value.refCount < pool.config.concurrency) {
-          addAvailable(pool, item.value)
-        }
-        return Effect.succeed(item.value)
-      })
-    }
+    reclaim: (_) => Effect.undefined
   })
+})
 
 const reportUnhandledError = <E>(cause: Cause.Cause<E>) =>
   Effect.withFiber<void>((fiber) => {

package/src/Queue.ts

@@ -344,13 +344,13 @@ export declare namespace Queue {
   export type State<A, E> =
     | {
       readonly _tag: "Open"
-      readonly takers: Set<(_: Effect<void, E>) => void>
+      readonly takers: Set<Taker<E>>
       readonly offers: Set<OfferEntry<A>>
       readonly awaiters: Set<(_: Effect<void, E>) => void>
     }
     | {
       readonly _tag: "Closing"
-      readonly takers: Set<(_: Effect<void, E>) => void>
+      readonly takers: Set<Taker<E>>
       readonly offers: Set<OfferEntry<A>>
       readonly awaiters: Set<(_: Effect<void, E>) => void>
       readonly exit: Failure<never, E>
@@ -384,6 +384,24 @@ export declare namespace Queue {
       readonly message: A
       readonly resume: (_: Effect<boolean>) => void
     }
+
+  /**
+   * Represents a suspended take waiting for the queue to become readable.
+   *
+   * **Details**
+   *
+   * `ready` reports whether the take can now complete, so a batch take is
+   * only resumed once its minimum is available. `resume` completes the
+   * suspended take, with `void` to retry or with a failure exit when the queue
+   * is done.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface Taker<E> {
+    readonly ready: () => boolean
+    readonly resume: (_: Effect<void, E>) => void
+  }
 }
 
 const variance = {
@@ -2427,8 +2445,9 @@ const releaseTakers = <A, E>(self: Enqueue<A, E>) => {
     return
   }
   for (const taker of self.state.takers) {
+    if (!taker.ready()) continue
     self.state.takers.delete(taker)
-    taker(internalEffect.exitVoid)
+    taker.resume(internalEffect.exitVoid)
     if (self.messages.length === 0) {
       break
     }
@@ -2478,9 +2497,10 @@ const awaitTake = <A, E>(self: Dequeue<A, E>, ready: () => boolean) =>
   internalEffect.callback<void, E>((resume) => {
     if (self.state._tag === "Done") return resume(self.state.exit)
     if (ready()) return resume(internalEffect.exitVoid)
-    self.state.takers.add(resume)
+    const taker = { ready, resume }
+    self.state.takers.add(taker)
     return internalEffect.sync(() => {
-      if (self.state._tag !== "Done") self.state.takers.delete(resume)
+      if (self.state._tag !== "Done") self.state.takers.delete(taker)
     })
   })
 
@@ -2577,7 +2597,7 @@ const finalize = <A, E>(self: Enqueue<A, E> | Dequeue<A, E>, exit: Failure<never
   const openState = self.state
   self.state = { _tag: "Done", exit }
   for (const taker of openState.takers) {
-    taker(exit)
+    taker.resume(exit)
   }
   openState.takers.clear()
   for (const awaiter of openState.awaiters) {

package/src/RcMap.ts

@@ -566,10 +566,16 @@ export const get: {
           context.set(key, value)
         })
         context.set(Scope.Scope.key, entry.scope)
+        const lookupContext: Context.Context<Scope.Scope> = Context.makeUnsafe(context)
         Effect.suspend(() => self.lookup(key)).pipe(
-          Effect.runForkWith(Context.makeUnsafe(context)),
+          Effect.runForkWith(lookupContext),
           Fiber.runIn(entry.scope)
-        ).addObserver((exit) => Deferred.doneUnsafe(entry.deferred, exit))
+        ).addObserver((exit) => {
+          // Interruption is abandonment, so the entry is dropped and the next
+          // get starts a fresh lookup.
+          if (Exit.hasInterrupts(exit)) removeInterrupted(self, key, entry, lookupContext)
+          Deferred.doneUnsafe(entry.deferred, exit)
+        })
       }
       const scope = Context.getUnsafe(parent.context, Scope.Scope)
       return Scope.addFinalizer(scope, entry.finalizer).pipe(
@@ -733,6 +739,24 @@ export const getOption: {
     })
 )
 
+const removeInterrupted = <K, A, E>(
+  self: RcMap<K, A, E>,
+  key: K,
+  entry: State.Entry<A, E>,
+  context: Context.Context<Scope.Scope>
+) => {
+  if (self.state._tag === "Closed") return
+  const o = MutableHashMap.get(self.state.map, key)
+  if (o._tag === "None" || o.value !== entry) return
+  MutableHashMap.remove(self.state.map, key)
+  // Borrowers close the entry on release; an idle entry has none left.
+  if (entry.refCount > 0) return
+  closeEntry(entry).pipe(
+    Effect.runForkWith(context),
+    Fiber.runIn(self.scope)
+  )
+}
+
 const closeEntry = <A, E>(entry: State.Entry<A, E>) =>
   entry.fiber
     ? Fiber.interrupt(entry.fiber).pipe(Effect.andThen(Scope.close(entry.scope, Exit.void)))

package/src/Record.ts

@@ -1372,8 +1372,8 @@ export const getSuccesses = <K extends string, A, E>(
  *
  * **Details**
  *
- * Failure values are collected in the left record, and success values are
- * collected in the right record, preserving the original keys.
+ * Success values are collected in the first record, and failure values are
+ * collected in the second record, preserving the original keys.
  *
  * **Example** (Partitioning with Result)
  *
@@ -1382,7 +1382,7 @@ export const getSuccesses = <K extends string, A, E>(
  *
  * const x = { a: 1, b: 2, c: 3 }
  * const f = (n: number) => (n % 2 === 0 ? Result.succeed(n) : Result.fail(n))
- * Record.partition(x, f) // => [{ a: 1, c: 3 }, { b: 2 }]
+ * Record.partition(x, f) // => [{ b: 2 }, { a: 1, c: 3 }]
  * ```
  *
  * @category filtering
@@ -1395,8 +1395,8 @@ export const partition: {
    *
    * **Details**
    *
-   * Failure values are collected in the left record, and success values are
-   * collected in the right record, preserving the original keys.
+   * Success values are collected in the first record, and failure values are
+   * collected in the second record, preserving the original keys.
    *
    * **Example** (Partitioning with Result)
    *
@@ -1405,7 +1405,7 @@ export const partition: {
    *
    * const x = { a: 1, b: 2, c: 3 }
    * const f = (n: number) => (n % 2 === 0 ? Result.succeed(n) : Result.fail(n))
-   * Record.partition(x, f) // => [{ a: 1, c: 3 }, { b: 2 }]
+   * Record.partition(x, f) // => [{ b: 2 }, { a: 1, c: 3 }]
    * ```
    *
    * @category filtering
@@ -1413,15 +1413,15 @@ export const partition: {
    */
   <K extends string, A, B, C>(f: (input: A, key: K) => Result<C, B>): (
     self: ReadonlyRecord<K, A>
-  ) => [left: Record<ReadonlyRecord.NonLiteralKey<K>, B>, right: Record<ReadonlyRecord.NonLiteralKey<K>, C>]
+  ) => [passes: Record<ReadonlyRecord.NonLiteralKey<K>, C>, fails: Record<ReadonlyRecord.NonLiteralKey<K>, B>]
   /**
    * Applies a function to each record entry and partitions the returned `Result`
    * values into two records.
    *
    * **Details**
    *
-   * Failure values are collected in the left record, and success values are
-   * collected in the right record, preserving the original keys.
+   * Success values are collected in the first record, and failure values are
+   * collected in the second record, preserving the original keys.
    *
    * **Example** (Partitioning with Result)
    *
@@ -1430,43 +1430,43 @@ export const partition: {
    *
    * const x = { a: 1, b: 2, c: 3 }
    * const f = (n: number) => (n % 2 === 0 ? Result.succeed(n) : Result.fail(n))
-   * Record.partition(x, f) // => [{ a: 1, c: 3 }, { b: 2 }]
+   * Record.partition(x, f) // => [{ b: 2 }, { a: 1, c: 3 }]
    * ```
    *
    * @category filtering
    * @since 2.0.0
    */
-  <K extends string, A, B, C>(self: ReadonlyRecord<K, A>, f: (input: A, key: K) => Result<C, B>): [left: Record<ReadonlyRecord.NonLiteralKey<K>, B>, right: Record<ReadonlyRecord.NonLiteralKey<K>, C>]
+  <K extends string, A, B, C>(self: ReadonlyRecord<K, A>, f: (input: A, key: K) => Result<C, B>): [passes: Record<ReadonlyRecord.NonLiteralKey<K>, C>, fails: Record<ReadonlyRecord.NonLiteralKey<K>, B>]
 } = dual(
   2,
   <K extends string, A, B, C>(
     self: ReadonlyRecord<K, A>,
     f: (input: A, key: K) => Result<C, B>
-  ): [left: Record<ReadonlyRecord.NonLiteralKey<K>, B>, right: Record<ReadonlyRecord.NonLiteralKey<K>, C>] => {
-    const left: Record<string, B> = empty()
-    const right: Record<string, C> = empty()
+  ): [passes: Record<ReadonlyRecord.NonLiteralKey<K>, C>, fails: Record<ReadonlyRecord.NonLiteralKey<K>, B>] => {
+    const passes: Record<string, C> = empty()
+    const fails: Record<string, B> = empty()
     for (const key of keys(self)) {
       const e = f(self[key], key)
       if (R.isFailure(e)) {
-        InternalRecord.assignProperty(left, key, e.failure)
+        InternalRecord.assignProperty(fails, key, e.failure)
       } else {
-        InternalRecord.assignProperty(right, key, e.success)
+        InternalRecord.assignProperty(passes, key, e.success)
       }
     }
-    return [left, right]
+    return [passes, fails]
   }
 )
 
 /**
  * Partitions a record of `Result` values into two separate records,
- * one with the `Err` values and one with the `Ok` values.
+ * one with the success values and one with the failure values.
  *
  * **Example** (Separating Result values)
  *
  * ```ts import.meta.vitest
  * import { Record, Result } from "effect"
  *
- * Record.separate({ a: Result.fail("e"), b: Result.succeed(1) }) // => [{ a: "e" }, { b: 1 }]
+ * Record.separate({ a: Result.fail("e"), b: Result.succeed(1) }) // => [{ b: 1 }, { a: "e" }]
  * ```
  *
  * @category filtering
@@ -1474,7 +1474,7 @@ export const partition: {
  */
 export const separate: <K extends string, A, B>(
   self: ReadonlyRecord<K, Result<B, A>>
-) => [Record<ReadonlyRecord.NonLiteralKey<K>, A>, Record<ReadonlyRecord.NonLiteralKey<K>, B>] = partition(identity)
+) => [Record<ReadonlyRecord.NonLiteralKey<K>, B>, Record<ReadonlyRecord.NonLiteralKey<K>, A>] = partition(identity)
 
 /**
  * Retrieves the keys of a given record as an array.

package/src/Schema.ts

@@ -77,7 +77,7 @@ import * as SchemaTransformation from "./SchemaTransformation.ts"
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "./StandardSchema.ts"
 import type { Assign, Lambda, Mutable, Simplify } from "./Struct.ts"
 import * as Struct_ from "./Struct.ts"
-import type { RequiredKeys, UnionToIntersection } from "./Types.ts"
+import type { IsUnion, RequiredKeys } from "./Types.ts"
 import type { Unify } from "./Unify.ts"
 
 const TypeId = InternalMake.TypeId
@@ -5057,14 +5057,19 @@ export function refine<S extends Constraint, T extends S["Type"]>(
   return (schema: S): refine<T, S> =>
     make(SchemaAST.appendChecks(schema.ast, [SchemaAST.makeFilterByGuard(refinement, annotations)]), { schema })
 }
-type DistributeBrands<B> = UnionToIntersection<B extends infer U extends string ? Brand.Brand<U> : never>
+// A concrete key requires a property; broad and open template keys do not.
+type EnsureSingleBrandKey<K extends PropertyKey> = IsUnion<K> extends false
+  ? {} extends Record<K, unknown> ? never : unknown
+  : never
+// Collect all keys, including those not shared by every union member.
+type FromBrandKeys<A extends Brand.Brand<any>> = A extends unknown ? Brand.Brand.Keys<A> : never
 /**
  * Type-level representation returned by {@link brand}.
  *
  * @category branding
  * @since 3.10.0
  */
-export interface brand<S extends Constraint, B> extends
+export interface brand<S extends Constraint, B extends string> extends
   BottomLazy<
     S["ast"],
     brand<S, B>,
@@ -5076,19 +5081,19 @@ export interface brand<S extends Constraint, B> extends
     S["~encoded.optionality"]
   >
 {
-  readonly "Type": S["Type"] & DistributeBrands<B>
+  readonly "Type": S["Type"] & Brand.Brand<B>
   readonly "Encoded": S["Encoded"]
   readonly "DecodingServices": S["DecodingServices"]
   readonly "EncodingServices": S["EncodingServices"]
   readonly "~type.make.in": S["~type.make.in"]
-  readonly "~type.make": S["Type"] & DistributeBrands<B>
-  readonly "Iso": S["Type"] & DistributeBrands<B>
+  readonly "~type.make": S["Type"] & Brand.Brand<B>
+  readonly "Iso": S["Type"] & Brand.Brand<B>
   readonly schema: S
   readonly identifier: string
 }
 /**
- * Adds a nominal brand to a schema, intersecting the output type with
- * `Brand.Brand<B>` to prevent accidental mixing of structurally identical types.
+ * Intersects a schema's output type with `Brand.Brand<B>` to prevent accidental
+ * mixing of structurally identical types.
  *
  * **When to use**
  *
@@ -5097,31 +5102,52 @@ export interface brand<S extends Constraint, B> extends
  *
  * **Gotchas**
  *
- * `brand` adds brand metadata and narrows the TypeScript output type, but it
- * does not add runtime checks.
+ * - `identifier` must be a single concrete string literal. Widened strings,
+ *   unions, and open template literal types are rejected.
+ * - `brand` only narrows the TypeScript output type. It does not change the
+ *   schema's runtime AST or add runtime checks.
+ * - Schema representations and generated schema code omit the brand. Reapply
+ *   `brand` after rebuilding or generating a schema when the nominal type is
+ *   still required.
  *
- * @see {@link fromBrand} for applying a Brand constructor's checks along with the brand tag
+ * @see {@link fromBrand} for applying a Brand constructor's checks along with its branded type
  *
  * @category branding
  * @since 3.10.0
  */
-export function brand<B extends string>(identifier: B) {
+export function brand<B extends string>(identifier: B & EnsureSingleBrandKey<B>) {
   return <S extends ConstraintRebuildable>(schema: S): brand<S["Rebuild"], B> =>
-    make(SchemaAST.brand(schema.ast, identifier), { schema, identifier })
+    make(schema.ast, { schema, identifier })
 }
 /**
  * Creates a branded schema from a {@link Brand.Constructor}, applying the
- * constructor's checks and brand tag to the underlying schema.
+ * constructor's checks and branded type to the underlying schema.
+ *
+ * **When to use**
+ *
+ * Use to reuse the checks from a constructor with one concrete brand key.
+ *
+ * **Gotchas**
+ *
+ * `identifier` must match the constructor's only brand key. Apply `fromBrand`
+ * repeatedly to compose distinct brands, and use {@link Union} to represent
+ * alternatives.
+ *
+ * @see {@link brand} for adding a brand without constructor checks
  *
  * @category branding
  * @since 3.10.0
  */
-export function fromBrand<A extends Brand.Brand<any>>(identifier: string, ctor: Brand.Constructor<A>) {
+export function fromBrand<A extends Brand.Brand<any>>(
+  identifier: Brand.Brand.Keys<A> & string,
+  ctor: Brand.Constructor<A> & EnsureSingleBrandKey<FromBrandKeys<A>>
+) {
+  type B = Brand.Brand.Keys<A> & string
   return <S extends Top & { readonly "Type": Brand.Brand.Unbranded<A> }>(
     self: S
-  ): brand<S["Rebuild"], Brand.Brand.Keys<A>> => {
-    return (ctor.checks ? self.check(...ctor.checks) : self).pipe(brand(identifier))
-  }
+  ): brand<S["Rebuild"], B> =>
+    // The constructor already guarantees a single concrete brand key.
+    (ctor.checks ? self.check(...ctor.checks) : self).pipe(brand<B>(identifier as B & EnsureSingleBrandKey<B>))
 }
 /**
  * Type-level representation returned by {@link middlewareDecoding}.
@@ -15695,6 +15721,8 @@ export function toEquivalence<T>(schema: Schema<T>): Equivalence.Equivalence<T>
  * Use {@link toType} before this function to represent the type side instead.
  * The optional reference policy controls which candidates are extracted into the document's reference table. By
  * default, only candidates with a resolved identifier become references; recursive candidates always require one.
+ * TypeScript-only distinctions such as those added by {@link brand} are not
+ * part of the schema AST and are therefore omitted.
  *
  * @see {@link SchemaRepresentation.toRepresentation} for converting a `SchemaAST.AST` directly
  *
@@ -16577,8 +16605,8 @@ export declare namespace Annotations {
   }
   /**
    * Base annotations shared by all composite schema nodes. Extends
-   * {@link Documentation} with error messages, branding, and arbitrary
-   * generation hooks. {@link Declaration} and other annotation
+   * {@link Documentation} with error messages and arbitrary generation hooks.
+   * {@link Declaration} and other annotation
    * interfaces build on top of this.
    *
    * @category models
@@ -16616,10 +16644,6 @@ export declare namespace Annotations {
      * filter/refinement instead.
      */
     readonly identifier?: string | undefined
-    /**
-     * Accumulated brands when multiple brands are added with `Schema.brand`.
-     */
-    readonly brands?: ReadonlyArray<string> | undefined
   }
   /**
    * Helpers for projecting declaration type-parameter schemas into decoded or