effect 4.0.0-rc.112 → 4.0.0-rc.113

package/src/Match.ts

@@ -20,6 +20,22 @@ import type { Unify } from "./Unify.ts"
 
 const TypeId = internal.TypeId
 
+// The conditional must stay deferred until P is inferred. Replacing it with an
+// intersection loses contextual typing for nested generic calls (microsoft/TypeScript#52864).
+type Contextual<P, Fallback> = internal.Contextual<P, Fallback>
+
+type TagHandlers<D extends string, R, Ret> = {
+  readonly [Tag in Types.Tags<D, R> & string]: (_: Extract<R, Record<D, Tag>>) => Ret
+}
+
+type PartialTagHandlers<D extends string, R, Ret> = {
+  readonly [Tag in Types.Tags<D, R> & string]?: ((_: Extract<R, Record<D, Tag>>) => Ret) | undefined
+}
+
+type ValueTagHandlers<I> = {
+  readonly [Tag in Types.Tags<"_tag", I> & string]: (_: Extract<I, { readonly _tag: Tag }>) => any
+}
+
 /**
  * Marker used by `Matcher` to distinguish matchers created with `Match.value`.
  *
@@ -316,10 +332,13 @@ export const type: <I>() => Matcher<I, Types.Without<never>, I, never, never> =
 /**
  * Creates a reusable matcher from a function that selects the value to match.
  *
+ * **Details**
+ *
  * The compiled matcher keeps the selector's original argument list. Case
  * handlers receive the narrowed selected value followed by those arguments.
  *
- * @example
+ * **Example** (Creating a reusable matcher)
+ *
  * ```ts import.meta.vitest
  * import { Match } from "effect"
  *
@@ -448,9 +467,9 @@ export const valueTags: {
   <
     const I,
     P extends
-      & { readonly [Tag in Types.Tags<"_tag", I> & string]: (_: Extract<I, { readonly _tag: Tag }>) => any }
+      & ValueTagHandlers<I>
       & { readonly [Tag in Exclude<keyof P, Types.Tags<"_tag", I>>]: never }
-  >(fields: P): (input: I) => Unify<ReturnType<P[keyof P]>>
+  >(fields: Contextual<P, ValueTagHandlers<I>>): (input: I) => Unify<ReturnType<P[keyof P]>>
   /**
    * Creates a match function for a specific value with discriminated union handling.
    *
@@ -483,9 +502,9 @@ export const valueTags: {
   <
     const I,
     P extends
-      & { readonly [Tag in Types.Tags<"_tag", I> & string]: (_: Extract<I, { readonly _tag: Tag }>) => any }
+      & ValueTagHandlers<I>
       & { readonly [Tag in Exclude<keyof P, Types.Tags<"_tag", I>>]: never }
-  >(input: I, fields: P): Unify<ReturnType<P[keyof P]>>
+  >(input: I, fields: Contextual<P, ValueTagHandlers<I>>): Unify<ReturnType<P[keyof P]>>
 } = internal.valueTags
 
 /**
@@ -1024,10 +1043,10 @@ export const discriminators: <D extends string>(
   R,
   Ret,
   P extends
-    & { readonly [Tag in Types.Tags<D, R> & string]?: ((_: Extract<R, Record<D, Tag>>) => Ret) | undefined }
+    & PartialTagHandlers<D, R, Ret>
     & { readonly [Tag in Exclude<keyof P, Types.Tags<D, R>>]: never }
 >(
-  fields: P
+  fields: Contextual<P, PartialTagHandlers<D, R, Ret>>
 ) => <I, F, A, Pr>(
   self: Matcher<I, F, R, A, Pr, Ret>
 ) => Matcher<
@@ -1087,10 +1106,10 @@ export const discriminatorsExhaustive: <D extends string>(
   R,
   Ret,
   P extends
-    & { readonly [Tag in Types.Tags<D, R> & string]: (_: Extract<R, Record<D, Tag>>) => Ret }
+    & TagHandlers<D, R, Ret>
     & { readonly [Tag in Exclude<keyof P, Types.Tags<D, R>>]: never }
 >(
-  fields: P
+  fields: Contextual<P, TagHandlers<D, R, Ret>>
 ) => <I, F, A, Pr>(
   self: Matcher<I, F, R, A, Pr, Ret>
 ) => [Pr] extends [never] ? (u: I) => Unify<A | ReturnType<P[keyof P]>> : Unify<A | ReturnType<P[keyof P]>> =
@@ -1247,10 +1266,10 @@ export const tags: <
   R,
   Ret,
   P extends
-    & { readonly [Tag in Types.Tags<"_tag", R> & string]?: ((_: Extract<R, Record<"_tag", Tag>>) => Ret) | undefined }
+    & PartialTagHandlers<"_tag", R, Ret>
     & { readonly [Tag in Exclude<keyof P, Types.Tags<"_tag", R>>]: never }
 >(
-  fields: P
+  fields: Contextual<P, PartialTagHandlers<"_tag", R, Ret>>
 ) => <I, F, A, Pr>(
   self: Matcher<I, F, R, A, Pr, Ret>
 ) => Matcher<
@@ -1302,10 +1321,10 @@ export const tagsExhaustive: <
   R,
   Ret,
   P extends
-    & { readonly [Tag in Types.Tags<"_tag", R> & string]: (_: Extract<R, Record<"_tag", Tag>>) => Ret }
+    & TagHandlers<"_tag", R, Ret>
     & { readonly [Tag in Exclude<keyof P, Types.Tags<"_tag", R>>]: never }
 >(
-  fields: P
+  fields: Contextual<P, TagHandlers<"_tag", R, Ret>>
 ) => <I, F, A, Pr>(
   self: Matcher<I, F, R, A, Pr, Ret>
 ) => [Pr] extends [never] ? (u: I) => Unify<A | ReturnType<P[keyof P]>> : Unify<A | ReturnType<P[keyof P]>> =
@@ -2195,7 +2214,7 @@ export const exhaustive: <I, F, A, Pr, Ret, Args extends Array<any>>(
 ) => [Pr] extends [never] ? [Args] extends [[]] ? (u: I) => Unify<A> : (...args: Args) => Unify<A> : Unify<A> =
   internal.exhaustive
 
-const SafeRefinementId = "~effect/match/Match/SafeRefinement"
+const SafeRefinementId = "~effect/Match/SafeRefinement"
 
 /**
  * A safe refinement that narrows types without runtime errors.

package/src/Metric.ts

@@ -1609,7 +1609,15 @@ export const CurrentMetricAttributes = Context.Reference<Metric.AttributeSet>(Cu
   defaultValue: () => ({})
 })
 
-const MetricRegistryKey = "~effect/observability/Metric/MetricRegistryKey"
+const MetricRegistryKey = "effect/Metric/MetricRegistry"
+
+/**
+ * The registry used to store metric metadata and hooks.
+ *
+ * @category services
+ * @since 4.0.0
+ */
+export type MetricRegistry = Map<string, Metric.Metadata<any, any>>
 
 /**
  * Context reference for the metric registry in the current context.
@@ -1637,12 +1645,12 @@ const MetricRegistryKey = "~effect/observability/Metric/MetricRegistryKey"
  * @category services
  * @since 4.0.0
  */
-export const MetricRegistry = Context.Reference<Map<string, Metric.Metadata<any, any>>>(
+export const MetricRegistry: Context.Reference<MetricRegistry> = Context.Reference<MetricRegistry>(
   MetricRegistryKey,
   { defaultValue: () => new Map() }
 )
 
-const TypeId = "~effect/observability/Metric"
+const TypeId = "~effect/Metric"
 
 abstract class Metric$<in Input, out State> implements Metric<Input, State> {
   readonly [TypeId] = TypeId
@@ -1652,8 +1660,7 @@ abstract class Metric$<in Input, out State> implements Metric<Input, State> {
   declare readonly Input: Contravariant<Input>
   declare readonly State: Covariant<State>
 
-  readonly #metadataCache = new WeakMap<Metric.Attributes, Metric.Metadata<Input, State>>()
-  #metadata: Metric.Metadata<Input, State> | undefined
+  readonly #metadata = new WeakMap<MetricRegistry, Metric.Metadata<Input, State>>()
 
   readonly id: string
   readonly description: string | undefined
@@ -1685,20 +1692,15 @@ abstract class Metric$<in Input, out State> implements Metric<Input, State> {
 
   hook(context: Context.Context<never>): Metric.Hooks<Input, State> {
     const extraAttributes = Context.get(context, CurrentMetricAttributes)
-    if (Object.keys(extraAttributes).length === 0) {
-      if (Predicate.isNotUndefined(this.#metadata)) {
-        return this.#metadata.hooks
-      }
-      this.#metadata = this.getOrCreate(context, this.attributes)
-      return this.#metadata.hooks
+    if (Object.keys(extraAttributes).length > 0) {
+      return this.getOrCreate(context, mergeAttributes(this.attributes, extraAttributes)).hooks
     }
-    const mergedAttributes = mergeAttributes(this.attributes, extraAttributes)
-    let metadata = this.#metadataCache.get(mergedAttributes)
-    if (Predicate.isNotUndefined(metadata)) {
-      return metadata.hooks
+    const registry = Context.get(context, MetricRegistry)
+    let metadata = this.#metadata.get(registry)
+    if (Predicate.isUndefined(metadata)) {
+      metadata = this.getOrCreate(context, this.attributes)
+      this.#metadata.set(registry, metadata)
     }
-    metadata = this.getOrCreate(context, mergedAttributes)
-    this.#metadataCache.set(mergedAttributes, metadata)
     return metadata.hooks
   }
 
@@ -4349,14 +4351,13 @@ const fiberFailures = counter("child_fiber_failures", {
  * ```ts import.meta.vitest
  * import { Metric } from "effect"
  *
- * Metric.FiberRuntimeMetricsKey // => "effect/observability/Metric/FiberRuntimeMetricsKey"
+ * Metric.FiberRuntimeMetricsKey // => "effect/Metric/FiberRuntimeMetrics"
  * ```
  *
  * @category constants
  * @since 4.0.0
  */
-export const FiberRuntimeMetricsKey: "effect/observability/Metric/FiberRuntimeMetricsKey" =
-  InternalMetric.FiberRuntimeMetricsKey
+export const FiberRuntimeMetricsKey: "effect/Metric/FiberRuntimeMetrics" = InternalMetric.FiberRuntimeMetricsKey
 
 /**
  * Interface for the fiber runtime metrics service that tracks fiber lifecycle events.
@@ -4610,7 +4611,9 @@ function makeHooks<Input, State>(
 }
 
 function serializeAttributes(attributes: Metric.Attributes): string {
-  return JSON.stringify(Array.isArray(attributes) ? attributes : Object.entries(attributes))
+  const entries = Array.isArray(attributes) ? [...attributes] : Object.entries(attributes)
+  entries.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)
+  return JSON.stringify(entries)
 }
 
 function mergeAttributes(

package/src/MutableHashMap.ts

@@ -20,7 +20,7 @@ import type { Pipeable } from "./Pipeable.ts"
 import { pipeArguments } from "./Pipeable.ts"
 import { hasProperty } from "./Predicate.ts"
 
-const TypeId = "~effect/collections/MutableHashMap"
+const TypeId = "~effect/MutableHashMap"
 
 /**
  * A mutable hash map that stores key-value pairs and supports both referential

package/src/MutableHashSet.ts

@@ -17,7 +17,7 @@ import type { Pipeable } from "./Pipeable.ts"
 import { pipeArguments } from "./Pipeable.ts"
 import { hasProperty } from "./Predicate.ts"
 
-const TypeId = "~effect/collections/MutableHashSet"
+const TypeId = "~effect/MutableHashSet"
 
 /**
  * A mutable hash set for storing unique values with Effect structural equality

package/src/MutableList.ts

@@ -9,6 +9,7 @@
  * @since 4.0.0
  */
 import * as Arr from "./Array.ts"
+import * as Count from "./internal/count.ts"
 
 /**
  * A mutable linked list data structure optimized for high-throughput operations.
@@ -290,6 +291,7 @@ export const prependAllUnsafe = <A>(self: MutableList<A>, messages: ReadonlyArra
     offset: 0,
     next: self.head
   }
+  if (!self.tail && messages.length > 0) self.tail = self.head
   self.length += self.head.array.length
 }
 
@@ -399,6 +401,11 @@ export const clear = <A>(self: MutableList<A>): void => {
  * The taken elements are removed from the list. This operation is optimized for performance
  * and includes zero-copy optimizations when possible.
  *
+ * **Details**
+ *
+ * Finite fractional values of `n` are rounded down. `NaN` and non-positive
+ * values leave the list unchanged and return an empty array.
+ *
  * **Example** (Taking batches)
  *
  * ```ts import.meta.vitest
@@ -416,6 +423,7 @@ export const clear = <A>(self: MutableList<A>): void => {
  * @since 4.0.0
  */
 export const takeN = <A>(self: MutableList<A>, n: number): Array<A> => {
+  n = Count.normalize(n)
   if (n <= 0 || !self.head) return []
   n = Math.min(n, self.length)
   if (n === self.length && self.head?.offset === 0 && !self.head.next) {
@@ -455,8 +463,9 @@ export const takeN = <A>(self: MutableList<A>, n: number): Array<A> => {
  *
  * **Details**
  *
- * If `n` is less than or equal to zero, or the list is empty, the list is left
- * unchanged. If `n` is greater than or equal to the current length, the list is
+ * Finite fractional values of `n` are rounded down. If `n` is `NaN` or
+ * non-positive, or the list is empty, the list is left unchanged. If the
+ * normalized count is greater than or equal to the current length, the list is
  * cleared.
  *
  * @see {@link takeN} for removing up to `n` values and returning them as an array
@@ -466,6 +475,7 @@ export const takeN = <A>(self: MutableList<A>, n: number): Array<A> => {
  * @since 4.0.0
  */
 export const takeNVoid = <A>(self: MutableList<A>, n: number): void => {
+  n = Count.normalize(n)
   if (n <= 0 || !self.head) return
   n = Math.min(n, self.length)
   if (n === self.length && self.head?.offset === 0 && !self.head.next) {
@@ -556,12 +566,18 @@ export const take = <A>(self: MutableList<A>): Empty | A => {
  * Use when you need to inspect or snapshot a bounded prefix of the list without
  * consuming it.
  *
+ * **Details**
+ *
+ * Finite fractional values of `n` are rounded down. `NaN` and non-positive
+ * values return an empty array.
+ *
  * @see {@link takeN} for removing up to `n` values and returning them as an array
  *
  * @category converting
  * @since 4.0.0
  */
 export const toArrayN = <A>(self: MutableList<A>, n: number): Array<A> => {
+  n = Count.normalize(n)
   if (n <= 0) return []
   const length = Math.min(n, self.length)
   const out = new Array<A>(length)

package/src/Number.ts

@@ -876,6 +876,8 @@ export const between: {
  * - If the `number` is less than the `minimum` value, the function returns the `minimum` value.
  * - If the `number` is greater than the `maximum` value, the function returns the `maximum` value.
  * - Otherwise, it returns the original `number`.
+ * - `NaN` is ordered below every non-`NaN` number by `Number.Order`, so it is
+ *   clamped to `minimum`.
  *
  * **Example** (Clamping to a range)
  *
@@ -907,6 +909,8 @@ export const clamp: {
    * - If the `number` is less than the `minimum` value, the function returns the `minimum` value.
    * - If the `number` is greater than the `maximum` value, the function returns the `maximum` value.
    * - Otherwise, it returns the original `number`.
+   * - `NaN` is ordered below every non-`NaN` number by `Number.Order`, so it is
+   *   clamped to `minimum`.
    *
    * **Example** (Clamping to a range)
    *
@@ -943,6 +947,8 @@ export const clamp: {
    * - If the `number` is less than the `minimum` value, the function returns the `minimum` value.
    * - If the `number` is greater than the `maximum` value, the function returns the `maximum` value.
    * - Otherwise, it returns the original `number`.
+   * - `NaN` is ordered below every non-`NaN` number by `Number.Order`, so it is
+   *   clamped to `minimum`.
    *
    * **Example** (Clamping to a range)
    *
@@ -1267,7 +1273,7 @@ export const remainder: {
   const selfDecCount = (selfString.split(".")[1] || "").length
   const divisorDecCount = (divisorString.split(".")[1] || "").length
   const decCount = selfDecCount > divisorDecCount ? selfDecCount : divisorDecCount
-  const selfInt = parseInt(self.toFixed(decCount).replace(".", ""))
+  const selfInt = self === 0 ? self : parseInt(self.toFixed(decCount).replace(".", ""))
   const divisorInt = parseInt(divisor.toFixed(decCount).replace(".", ""))
   return (selfInt % divisorInt) / Math.pow(10, decCount)
 })

package/src/Optic.ts

@@ -12,6 +12,7 @@
  * @since 4.0.0
  */
 
+import * as Arr from "./Array.ts"
 import { dual, identity } from "./Function.ts"
 import * as InternalRecord from "./internal/record.ts"
 import * as Option from "./Option.ts"
@@ -1001,8 +1002,11 @@ class OptionalImpl<S, A> implements Optional<S, A> {
           (a, s) => {
             const copy = cloneShallow(s)
             if (a === undefined) {
-              if (Array.isArray(copy) && typeof key === "number") {
-                copy.splice(key, 1)
+              if (
+                Array.isArray(copy) &&
+                (typeof key === "number" || (typeof key === "string" && Arr.isCanonicalArrayIndex(key)))
+              ) {
+                copy.splice(Number(key), 1)
               } else {
                 delete copy[key]
               }
@@ -1058,10 +1062,10 @@ class OptionalImpl<S, A> implements Optional<S, A> {
     )
   }
   pick(keys: any) {
-    return this.compose(makeLens(Struct.pick(keys), (p, a) => ({ ...a, ...p })))
+    return this.compose(makeLens(Struct.pick(keys), (p, a) => ({ ...Struct.omit(a, keys), ...p })))
   }
   omit(keys: any) {
-    return this.compose(makeLens(Struct.omit(keys), (o, a) => ({ ...a, ...o })))
+    return this.compose(makeLens(Struct.omit(keys), (o, a) => ({ ...Struct.pick(a, keys), ...o })))
   }
   notUndefined(): any {
     return this.refine(Predicate.isNotUndefined, { expected: "a value other than `undefined`" })

package/src/Option.ts

@@ -33,7 +33,7 @@ import type { Covariant, NoInfer, NotFunction } from "./Types.ts"
 import type * as Unify from "./Unify.ts"
 import type * as Gen from "./Utils.ts"
 
-const TypeId = "~effect/data/Option"
+const TypeId = "~effect/Option"
 
 /**
  * The `Option` data type represents optional values. An `Option<A>` is either

package/src/Order.ts

@@ -452,6 +452,7 @@ export function alwaysEqual<A>(): Order<A> {
  *
  * Applies orders in iteration order and short-circuits on the first non-zero
  * result. It returns `0` only if all orders return `0`.
+ * The collection is materialized when the order is created, so it must be finite.
  *
  * **Example** (Combining multiple Orders)
  *
@@ -481,9 +482,10 @@ export function alwaysEqual<A>(): Order<A> {
  * @since 2.0.0
  */
 export function combineAll<A>(collection: Iterable<Order<A>>): Order<A> {
+  const orders = Array.from(collection)
   return make((a1, a2) => {
     let out: Ordering = 0
-    for (const O of collection) {
+    for (const O of orders) {
       out = O(a1, a2)
       if (out !== 0) {
         return out

package/src/PartitionedSemaphore.ts

@@ -216,8 +216,7 @@ export const makeUnsafe = <K = unknown>(options: {
       }
 
       const cleanup = () => {
-        waiters.delete(entry)
-        if (waiters.size === 0) {
+        if (waiters.delete(entry) && waiters.size === 0) {
           MutableHashMap.remove(partitions, key)
         }
       }

package/src/Path.ts

@@ -29,7 +29,7 @@ import { BadArgument } from "./PlatformError.ts"
  * @category type IDs
  * @since 4.0.0
  */
-export const TypeId = "~effect/platform/Path"
+export const TypeId = "~effect/Path"
 
 /**
  * Defines the service interface for platform-specific path manipulation.

package/src/PlatformError.ts

@@ -11,7 +11,7 @@
  */
 import * as Data from "./Data.ts"
 
-const TypeId = "~effect/platform/PlatformError"
+const TypeId = "~effect/PlatformError"
 
 /**
  * Error data for an invalid argument passed to a platform API.

package/src/Pool.ts

@@ -674,8 +674,13 @@ const releaseItem = <A, E>(self: Pool<A, E>, item: PoolItem<A, E>): Effect.Effec
     if (state.invalidated.has(item)) {
       return invalidatePoolItem(self, item)
     }
-    if (item.refCount === self.config.concurrency - 1) {
-      addAvailable(self, item)
+    // Every release frees one slot, so it can admit one waiter. Reacting only
+    // to the saturated-to-unsaturated transition strands the rest: several
+    // leases returning at once would wake a single waiter and leave the others
+    // asleep against an item that has capacity for them. `addAvailable` is
+    // idempotent, so re-adding an available item is free.
+    if (item.refCount < self.config.concurrency) {
+      addAvailableFront(self, item)
       wakeWaiters(self, fiber, 1)
     }
     return internal.void
@@ -719,8 +724,12 @@ const wakeAll = <A, E>(self: Pool<A, E>): Effect.Effect<void> =>
     return internal.void
   })
 
+// Reservations prevent reuse without extending the lifetime of borrowed items.
+const reservations = new WeakMap<PoolItem<unknown, unknown>, number>()
+
+/** Adds a freshly acquired item, which has no use behind it, at the back. */
 const addAvailable = <A, E>(self: Pool<A, E>, item: PoolItem<A, E>): void => {
-  if (item.isAvailable) return
+  if (item.isAvailable || reservations.has(item)) return
   item.isAvailable = true
   item.availablePrevious = self.state.availableTail
   item.availableNext = undefined
@@ -732,6 +741,32 @@ const addAvailable = <A, E>(self: Pool<A, E>, item: PoolItem<A, E>): void => {
   self.state.availableTail = item
 }
 
+/**
+ * Returns a released item at the front, so the next borrow gets the one used
+ * most recently. Borrowers take from the front, so the list runs warmest
+ * first.
+ *
+ * Sending it to the back instead spreads a sequence of borrows evenly over
+ * every item the pool has open. For a pool of connections that means none of
+ * them is ever the hot one - each borrow lands on a peer that has been sitting
+ * idle, losing whatever warmth it had - and it means `timeToLive` never
+ * reclaims anything, because a pool that grew for one burst keeps every item
+ * equally fresh forever. Under saturation the two orders agree, since every
+ * item is checked out either way.
+ */
+const addAvailableFront = <A, E>(self: Pool<A, E>, item: PoolItem<A, E>): void => {
+  if (item.isAvailable || reservations.has(item)) return
+  item.isAvailable = true
+  item.availablePrevious = undefined
+  item.availableNext = self.state.availableHead
+  if (self.state.availableHead !== undefined) {
+    self.state.availableHead.availablePrevious = item
+  } else {
+    self.state.availableTail = item
+  }
+  self.state.availableHead = item
+}
+
 const removeAvailable = <A, E>(self: Pool<A, E>, item: PoolItem<A, E>): void => {
   if (!item.isAvailable) return
   item.isAvailable = false
@@ -788,7 +823,7 @@ export const invalidate: {
    * @category combinators
    * @since 2.0.0
    */
-  <A>(item: A): <E>(self: Pool<A, E>) => Effect.Effect<void, never, Scope.Scope>
+  <A>(item: A): <E>(self: Pool<A, E>) => Effect.Effect<void>
   /**
    * Invalidates the specified item so the pool can remove it and reallocate the
    * item, lazily if needed.
@@ -808,8 +843,8 @@ export const invalidate: {
    * @category combinators
    * @since 2.0.0
    */
-  <A, E>(self: Pool<A, E>, item: A): Effect.Effect<void, never, Scope.Scope>
-} = dual(2, <A, E>(self: Pool<A, E>, item: A): Effect.Effect<void, never, Scope.Scope> =>
+  <A, E>(self: Pool<A, E>, item: A): Effect.Effect<void>
+} = dual(2, <A, E>(self: Pool<A, E>, item: A): Effect.Effect<void> =>
   Effect.suspend(() => {
     if (self.state.isShuttingDown) return Effect.void
     for (const poolItem of self.state.items) {
@@ -821,6 +856,82 @@ export const invalidate: {
     return Effect.void
   }))
 
+/**
+ * Reserves a leased item for exclusive use until the scope closes. This
+ * removes the item's remaining capacity from the pool but does not wait
+ * for existing leases to finish. It has no effect when per-item concurrency is
+ * `1` or the pool does not contain the item.
+ *
+ * @see {@link get} for acquiring an item
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export const reserve: {
+  /**
+   * Reserves a leased item for exclusive use until the scope closes. This
+   * removes the item's remaining capacity from the pool but does not wait
+   * for existing leases to finish. It has no effect when per-item concurrency is
+   * `1` or the pool does not contain the item.
+   *
+   * @see {@link get} for acquiring an item
+   *
+   * @category combinators
+   * @since 4.0.0
+   */
+  <A>(item: A): <E>(self: Pool<A, E>) => Effect.Effect<void, never, Scope.Scope>
+  /**
+   * Reserves a leased item for exclusive use until the scope closes. This
+   * removes the item's remaining capacity from the pool but does not wait
+   * for existing leases to finish. It has no effect when per-item concurrency is
+   * `1` or the pool does not contain the item.
+   *
+   * @see {@link get} for acquiring an item
+   *
+   * @category combinators
+   * @since 4.0.0
+   */
+  <A, E>(self: Pool<A, E>, item: A): Effect.Effect<void, never, Scope.Scope>
+} = dual(
+  2,
+  <A, E>(self: Pool<A, E>, item: A): Effect.Effect<void, never, Scope.Scope> =>
+    Effect.asVoid(Effect.acquireRelease(
+      Effect.sync(() => {
+        if (self.config.concurrency === 1) return undefined
+        for (const poolItem of self.state.items) {
+          if (poolItem.exit._tag !== "Success" || poolItem.exit.value !== item) continue
+          const existing = reservations.get(poolItem)
+          if (existing === undefined) self.state.usage += self.config.concurrency - 1
+          reservations.set(poolItem, (existing ?? 0) + 1)
+          removeAvailable(self, poolItem)
+          return poolItem
+        }
+        return undefined
+      }),
+      (poolItem) =>
+        core.withFiber((fiber) => {
+          if (poolItem === undefined) return internal.void
+          const remaining = (reservations.get(poolItem) ?? 1) - 1
+          if (remaining > 0) {
+            reservations.set(poolItem, remaining)
+            return internal.void
+          }
+          reservations.delete(poolItem)
+          self.state.usage -= self.config.concurrency - 1
+          if (
+            !self.state.isShuttingDown &&
+            self.state.items.has(poolItem) &&
+            !self.state.invalidated.has(poolItem) &&
+            poolItem.refCount < self.config.concurrency
+          ) {
+            addAvailableFront(self, poolItem)
+            wakeWaiters(self, fiber, self.config.concurrency - poolItem.refCount)
+          }
+          return internal.void
+        })
+    ))
+)
+
 const invalidatePoolItem = <A, E>(self: Pool<A, E>, poolItem: PoolItem<A, E>): Effect.Effect<void> =>
   Effect.suspend(() => {
     if (!self.state.items.has(poolItem)) {
@@ -836,7 +947,13 @@ const invalidatePoolItem = <A, E>(self: Pool<A, E>, poolItem: PoolItem<A, E>): E
     }
     self.state.invalidated.add(poolItem)
     removeAvailable(self, poolItem)
-    return Effect.void
+    // An invalidated item stops counting towards the pool's active size, so the
+    // pool is now below target and has to top itself back up. Waiting for the
+    // last lease to be returned would strand anybody already queued: the item
+    // they are waiting for is never coming back.
+    return Effect.asVoid(
+      Effect.forkIn(Effect.interruptible(resize(self)), self.state.scope, { startImmediately: true })
+    )
   })
 
 const resize = <A, E>(self: Pool<A, E>): Effect.Effect<void> =>
@@ -995,7 +1112,7 @@ const strategyUsageTTL = Effect.fnUntraced(function*<A, E>(ttl: Duration.Input)
           return Effect.undefined
         }
         const item = Iterable.head(
-          Iterable.filter(pool.state.invalidated, (item) => !item.disableReclaim)
+          Iterable.filter(pool.state.invalidated, (item) => !item.disableReclaim && !reservations.has(item))
         )
         if (item._tag === "None") {
           return Effect.undefined

package/src/PrimaryKey.ts

@@ -24,7 +24,7 @@ import { hasProperty } from "./Predicate.ts"
  * @category symbols
  * @since 2.0.0
  */
-export const symbol = "~effect/interfaces/PrimaryKey"
+export const symbol = "~effect/PrimaryKey"
 
 /**
  * An interface for objects that can provide a string-based primary key.