effect 4.0.0-rc.113 → 4.0.0-rc.115

package/src/Effect.ts

@@ -13941,8 +13941,8 @@ export const onExitFilter: {
 export const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>> = internal.cached
 
 /**
- * Returns an effect that caches its result for a specified `Duration`,
- * known as "timeToLive" (TTL).
+ * Returns an effect that caches its result for a fixed duration or a duration
+ * computed from its `Exit`, known as "timeToLive" (TTL).
  *
  * **When to use**
  *
@@ -13961,6 +13961,17 @@ export const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
  * After the specified duration has passed, the cache expires, and the effect
  * will be recomputed upon the next evaluation.
  *
+ * `timeToLive` accepts a `Duration.Input` or a function from `Exit<A, E>` to
+ * `Duration.Input`. The function runs once after each fresh computation,
+ * including failures, so successes and failures can have different TTLs. It
+ * does not run when the cache is created or when a cached result is reused.
+ * The callback also receives interruption exits, which are cached for the
+ * returned duration.
+ *
+ * The TTL starts when the computation completes. Concurrent callers share the
+ * pending computation. A zero TTL expires immediately, and an infinite TTL
+ * keeps the result indefinitely.
+ *
  * **Example** (Memoizing an effect with TTL)
  *
  * ```ts import.meta.vitest
@@ -13985,6 +13996,26 @@ export const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
  * output // => ["expensive task...", "result 1", "result 1", "result 1"]
  * ```
  *
+ * **Example** (Caching successes while retrying failures)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Exit } from "effect"
+ *
+ * let attempts = 0
+ * const task = Effect.suspend(() =>
+ *   ++attempts === 1 ? Effect.fail("temporary failure") : Effect.succeed(42)
+ * )
+ * const program = Effect.gen(function*() {
+ *   const cached = yield* task.pipe(
+ *     Effect.cachedWithTTL((exit) => Exit.isSuccess(exit) ? "1 hour" : 0)
+ *   )
+ *   yield* Effect.exit(cached)
+ *   return yield* cached
+ * })
+ *
+ * Effect.runSync(program) // => 42
+ * ```
+ *
  * @see {@link cached} for a similar function that caches the result
  * indefinitely.
  * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
@@ -13994,8 +14025,8 @@ export const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
  */
 export const cachedWithTTL: {
   /**
-   * Returns an effect that caches its result for a specified `Duration`,
-   * known as "timeToLive" (TTL).
+   * Returns an effect that caches its result for a fixed duration or a duration
+   * computed from its `Exit`, known as "timeToLive" (TTL).
    *
    * **When to use**
    *
@@ -14014,6 +14045,17 @@ export const cachedWithTTL: {
    * After the specified duration has passed, the cache expires, and the effect
    * will be recomputed upon the next evaluation.
    *
+   * `timeToLive` accepts a `Duration.Input` or a function from `Exit<A, E>` to
+   * `Duration.Input`. The function runs once after each fresh computation,
+   * including failures, so successes and failures can have different TTLs. It
+   * does not run when the cache is created or when a cached result is reused.
+   * The callback also receives interruption exits, which are cached for the
+   * returned duration.
+   *
+   * The TTL starts when the computation completes. Concurrent callers share the
+   * pending computation. A zero TTL expires immediately, and an infinite TTL
+   * keeps the result indefinitely.
+   *
    * **Example** (Memoizing an effect with TTL)
    *
    * ```ts import.meta.vitest
@@ -14038,6 +14080,110 @@ export const cachedWithTTL: {
    * output // => ["expensive task...", "result 1", "result 1", "result 1"]
    * ```
    *
+   * **Example** (Caching successes while retrying failures)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, Exit } from "effect"
+   *
+   * let attempts = 0
+   * const task = Effect.suspend(() =>
+   *   ++attempts === 1 ? Effect.fail("temporary failure") : Effect.succeed(42)
+   * )
+   * const program = Effect.gen(function*() {
+   *   const cached = yield* task.pipe(
+   *     Effect.cachedWithTTL((exit) => Exit.isSuccess(exit) ? "1 hour" : 0)
+   *   )
+   *   yield* Effect.exit(cached)
+   *   return yield* cached
+   * })
+   *
+   * Effect.runSync(program) // => 42
+   * ```
+   *
+   * @see {@link cached} for a similar function that caches the result
+   * indefinitely.
+   * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
+   * additional effect for manually invalidating the cached value.
+   * @category caching
+   * @since 2.0.0
+   */
+  <A, E>(timeToLive: (exit: Exit.Exit<A, E>) => Duration.Input): <R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
+  /**
+   * Returns an effect that caches its result for a fixed duration or a duration
+   * computed from its `Exit`, known as "timeToLive" (TTL).
+   *
+   * **When to use**
+   *
+   * Use when you need a costly effect result to be reused for a bounded duration
+   * before being recomputed.
+   *
+   * **Details**
+   *
+   * This function is used to cache the result of an effect for a specified amount
+   * of time. This means that the first time the effect is evaluated, its result
+   * is computed and stored.
+   *
+   * If the effect is evaluated again within the specified `timeToLive`, the
+   * cached result will be used, avoiding recomputation.
+   *
+   * After the specified duration has passed, the cache expires, and the effect
+   * will be recomputed upon the next evaluation.
+   *
+   * `timeToLive` accepts a `Duration.Input` or a function from `Exit<A, E>` to
+   * `Duration.Input`. The function runs once after each fresh computation,
+   * including failures, so successes and failures can have different TTLs. It
+   * does not run when the cache is created or when a cached result is reused.
+   * The callback also receives interruption exits, which are cached for the
+   * returned duration.
+   *
+   * The TTL starts when the computation completes. Concurrent callers share the
+   * pending computation. A zero TTL expires immediately, and an infinite TTL
+   * keeps the result indefinitely.
+   *
+   * **Example** (Memoizing an effect with TTL)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect } from "effect"
+   * const output: Array<unknown> = []
+   * const record = (value: unknown) => Effect.sync(() => { output.push(value) })
+   *
+   * let i = 1
+   * const expensiveTask = Effect.sync(() => {
+   *   void output.push("expensive task...")
+   *   return `result ${i++}`
+   * })
+   *
+   * const program = Effect.gen(function*() {
+   *   const cached = yield* Effect.cachedWithTTL(expensiveTask, "1 hour")
+   *   yield* cached.pipe(Effect.andThen(record))
+   *   yield* cached.pipe(Effect.andThen(record))
+   *   yield* cached.pipe(Effect.andThen(record))
+   * })
+   *
+   * Effect.runSync(program)
+   * output // => ["expensive task...", "result 1", "result 1", "result 1"]
+   * ```
+   *
+   * **Example** (Caching successes while retrying failures)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, Exit } from "effect"
+   *
+   * let attempts = 0
+   * const task = Effect.suspend(() =>
+   *   ++attempts === 1 ? Effect.fail("temporary failure") : Effect.succeed(42)
+   * )
+   * const program = Effect.gen(function*() {
+   *   const cached = yield* task.pipe(
+   *     Effect.cachedWithTTL((exit) => Exit.isSuccess(exit) ? "1 hour" : 0)
+   *   )
+   *   yield* Effect.exit(cached)
+   *   return yield* cached
+   * })
+   *
+   * Effect.runSync(program) // => 42
+   * ```
+   *
    * @see {@link cached} for a similar function that caches the result
    * indefinitely.
    * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
@@ -14047,8 +14193,92 @@ export const cachedWithTTL: {
    */
   (timeToLive: Duration.Input): <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
   /**
-   * Returns an effect that caches its result for a specified `Duration`,
-   * known as "timeToLive" (TTL).
+   * Returns an effect that caches its result for a fixed duration or a duration
+   * computed from its `Exit`, known as "timeToLive" (TTL).
+   *
+   * **When to use**
+   *
+   * Use when you need a costly effect result to be reused for a bounded duration
+   * before being recomputed.
+   *
+   * **Details**
+   *
+   * This function is used to cache the result of an effect for a specified amount
+   * of time. This means that the first time the effect is evaluated, its result
+   * is computed and stored.
+   *
+   * If the effect is evaluated again within the specified `timeToLive`, the
+   * cached result will be used, avoiding recomputation.
+   *
+   * After the specified duration has passed, the cache expires, and the effect
+   * will be recomputed upon the next evaluation.
+   *
+   * `timeToLive` accepts a `Duration.Input` or a function from `Exit<A, E>` to
+   * `Duration.Input`. The function runs once after each fresh computation,
+   * including failures, so successes and failures can have different TTLs. It
+   * does not run when the cache is created or when a cached result is reused.
+   * The callback also receives interruption exits, which are cached for the
+   * returned duration.
+   *
+   * The TTL starts when the computation completes. Concurrent callers share the
+   * pending computation. A zero TTL expires immediately, and an infinite TTL
+   * keeps the result indefinitely.
+   *
+   * **Example** (Memoizing an effect with TTL)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect } from "effect"
+   * const output: Array<unknown> = []
+   * const record = (value: unknown) => Effect.sync(() => { output.push(value) })
+   *
+   * let i = 1
+   * const expensiveTask = Effect.sync(() => {
+   *   void output.push("expensive task...")
+   *   return `result ${i++}`
+   * })
+   *
+   * const program = Effect.gen(function*() {
+   *   const cached = yield* Effect.cachedWithTTL(expensiveTask, "1 hour")
+   *   yield* cached.pipe(Effect.andThen(record))
+   *   yield* cached.pipe(Effect.andThen(record))
+   *   yield* cached.pipe(Effect.andThen(record))
+   * })
+   *
+   * Effect.runSync(program)
+   * output // => ["expensive task...", "result 1", "result 1", "result 1"]
+   * ```
+   *
+   * **Example** (Caching successes while retrying failures)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, Exit } from "effect"
+   *
+   * let attempts = 0
+   * const task = Effect.suspend(() =>
+   *   ++attempts === 1 ? Effect.fail("temporary failure") : Effect.succeed(42)
+   * )
+   * const program = Effect.gen(function*() {
+   *   const cached = yield* task.pipe(
+   *     Effect.cachedWithTTL((exit) => Exit.isSuccess(exit) ? "1 hour" : 0)
+   *   )
+   *   yield* Effect.exit(cached)
+   *   return yield* cached
+   * })
+   *
+   * Effect.runSync(program) // => 42
+   * ```
+   *
+   * @see {@link cached} for a similar function that caches the result
+   * indefinitely.
+   * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
+   * additional effect for manually invalidating the cached value.
+   * @category caching
+   * @since 2.0.0
+   */
+  <A, E>(timeToLive: Duration.Input | ((exit: Exit.Exit<A, E>) => Duration.Input)): <R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>
+  /**
+   * Returns an effect that caches its result for a fixed duration or a duration
+   * computed from its `Exit`, known as "timeToLive" (TTL).
    *
    * **When to use**
    *
@@ -14067,6 +14297,17 @@ export const cachedWithTTL: {
    * After the specified duration has passed, the cache expires, and the effect
    * will be recomputed upon the next evaluation.
    *
+   * `timeToLive` accepts a `Duration.Input` or a function from `Exit<A, E>` to
+   * `Duration.Input`. The function runs once after each fresh computation,
+   * including failures, so successes and failures can have different TTLs. It
+   * does not run when the cache is created or when a cached result is reused.
+   * The callback also receives interruption exits, which are cached for the
+   * returned duration.
+   *
+   * The TTL starts when the computation completes. Concurrent callers share the
+   * pending computation. A zero TTL expires immediately, and an infinite TTL
+   * keeps the result indefinitely.
+   *
    * **Example** (Memoizing an effect with TTL)
    *
    * ```ts import.meta.vitest
@@ -14091,6 +14332,26 @@ export const cachedWithTTL: {
    * output // => ["expensive task...", "result 1", "result 1", "result 1"]
    * ```
    *
+   * **Example** (Caching successes while retrying failures)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, Exit } from "effect"
+   *
+   * let attempts = 0
+   * const task = Effect.suspend(() =>
+   *   ++attempts === 1 ? Effect.fail("temporary failure") : Effect.succeed(42)
+   * )
+   * const program = Effect.gen(function*() {
+   *   const cached = yield* task.pipe(
+   *     Effect.cachedWithTTL((exit) => Exit.isSuccess(exit) ? "1 hour" : 0)
+   *   )
+   *   yield* Effect.exit(cached)
+   *   return yield* cached
+   * })
+   *
+   * Effect.runSync(program) // => 42
+   * ```
+   *
    * @see {@link cached} for a similar function that caches the result
    * indefinitely.
    * @see {@link cachedInvalidateWithTTL} for a similar function that includes an
@@ -14098,7 +14359,10 @@ export const cachedWithTTL: {
    * @category caching
    * @since 2.0.0
    */
-  <A, E, R>(self: Effect<A, E, R>, timeToLive: Duration.Input): Effect<Effect<A, E, R>>
+  <A, E, R>(
+    self: Effect<A, E, R>,
+    timeToLive: Duration.Input | ((exit: Exit.Exit<A, E>) => Duration.Input)
+  ): Effect<Effect<A, E, R>>
 } = internal.cachedWithTTL
 
 /**

package/src/Effectable.ts

@@ -8,7 +8,7 @@
  */
 import type * as Effect from "./Effect.ts"
 import type * as Fiber from "./Fiber.ts"
-import { type EffectTypeId, evaluate, makePrimitiveProto } from "./internal/core.ts"
+import { evaluate, makePrimitiveProto } from "./internal/core.ts"
 
 /**
  * Create a low-level `Effect` prototype.
@@ -78,7 +78,7 @@ type AsEffectReturn<Self> = Self extends {
 
 declare abstract class MixinBase extends Class<any, any, any> {
   constructor(...args: ReadonlyArray<any>)
-  override readonly [EffectTypeId]: AsEffectReturn<this>[typeof EffectTypeId]
+  override readonly [Effect.TypeId]: AsEffectReturn<this>[Effect.TypeId]
   override [Symbol.iterator](): Effect.EffectIterator<AsEffectReturn<this>>
 }
 

package/src/FileSystem.ts

@@ -906,10 +906,9 @@ export declare namespace File {
    * permissions, and size information. This structure is returned by file
    * stat operations.
    *
-   * Node and Bun preserve `size` and `blksize` exactly. Unsafe numeric metadata
-   * (such as `ino` or `dev`) fails the entire stat operation with `BadArgument`,
-   * including optional fields. Inode values above `Number.MAX_SAFE_INTEGER`
-   * can therefore prevent stat and HTTP file serving even for small files.
+   * Node and Bun preserve `size` and `blksize` exactly. Optional `number`
+   * metadata is `Option.none()` when absent or outside the safe integer range.
+   * Unsafe `dev` or `mode` values fail the stat operation with `BadArgument`.
    *
    * **Example** (Inspecting file information)
    *

package/src/Match.ts

@@ -22,7 +22,7 @@ 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 Contextual<P, Fallback> = [P] extends [never] ? Fallback : P
 
 type TagHandlers<D extends string, R, Ret> = {
   readonly [Tag in Types.Tags<D, R> & string]: (_: Extract<R, Record<D, Tag>>) => Ret

package/src/Schema.ts

@@ -15512,9 +15512,6 @@ export function resolveAnnotations<S extends Constraint>(
 export function resolveAnnotationsKey<S extends Constraint>(schema: S): Annotations.Key<S["Type"]> | undefined {
   return schema.ast.context?.annotations
 }
-/** @internal */
-type AnnotationSchemaConstraint = Constraint
-
 /**
  * The `Annotations` namespace groups all annotation interfaces used to attach
  * metadata to schemas. Annotations control documentation, validation messages,
@@ -15833,7 +15830,7 @@ export declare namespace Annotations {
      *
      * @since 4.0.0
      */
-    readonly arbitraryConstraint?: ToArbitrary.Constraint<any> | undefined
+    readonly arbitraryConstraint?: ToArbitrary.FilterConstraint<any> | undefined
     /**
      * Marks the filter as *structural*, meaning it applies to the shape or
      * structure of the container (e.g., array length, object keys) rather than
@@ -15899,7 +15896,7 @@ export declare namespace Annotations {
      * @category models
      * @since 4.0.0
      */
-    interface Constraint<T = unknown> extends GenerationConstraint<T> {
+    interface FilterConstraint<T = unknown> extends GenerationConstraint<T> {
       readonly order?: Order.Order<T> | undefined
     }
     /**
@@ -15908,7 +15905,7 @@ export declare namespace Annotations {
      * @category models
      * @since 4.0.0
      */
-    interface DeclarationInput<T, Parameters extends ReadonlyArray<AnnotationSchemaConstraint>> {
+    interface DeclarationInput<T, Parameters extends ReadonlyArray<Constraint>> {
       readonly typeParameters: TypeParameters.Type<Parameters>
       readonly constraint: GenerationConstraint<T> | undefined
     }
@@ -15918,7 +15915,7 @@ export declare namespace Annotations {
      * @category models
      * @since 4.0.0
      */
-    interface Declaration<T, Parameters extends ReadonlyArray<AnnotationSchemaConstraint>> {
+    interface Declaration<T, Parameters extends ReadonlyArray<Constraint>> {
       (input: DeclarationInput<T, Parameters>): SchemaAST.Link
     }
   }

package/src/SchemaAST.ts

@@ -1377,10 +1377,18 @@ type TemplateLiteralPart =
   | TemplateLiteral
   | Union<TemplateLiteralPart>
 
-function isTemplateLiteralPart(ast: AST, path: string, validated: WeakSet<AST>): ast is TemplateLiteralPart {
+function formatTemplateLiteralPath(path: string | number): string {
+  return typeof path === "number" ? `parts[${path}]` : path
+}
+
+function isTemplateLiteralPart(
+  ast: AST,
+  path: string | number,
+  validated: Set<AST>
+): ast is TemplateLiteralPart {
   if (validated.has(ast)) return true
   if (ast.encoding) {
-    throw new Error(`TemplateLiteral parts cannot have an encoding at ${path}`)
+    throw new Error(`TemplateLiteral parts cannot have an encoding at ${formatTemplateLiteralPath(path)}`)
   }
   let valid: boolean
   switch (ast._tag) {
@@ -1392,14 +1400,18 @@ function isTemplateLiteralPart(ast: AST, path: string, validated: WeakSet<AST>):
     case "Literal":
       valid = !ast.checks
       break
-    case "TemplateLiteral":
+    case "TemplateLiteral": {
+      const currentPath = formatTemplateLiteralPath(path)
       valid = !ast.checks &&
-        ast.parts.every((part, index) => isTemplateLiteralPart(part, `${path}.parts[${index}]`, validated))
+        ast.parts.every((part, index) => isTemplateLiteralPart(part, `${currentPath}.parts[${index}]`, validated))
       break
-    case "Union":
+    }
+    case "Union": {
+      const currentPath = formatTemplateLiteralPath(path)
       valid = !ast.checks &&
-        ast.types.every((part, index) => isTemplateLiteralPart(part, `${path}.types[${index}]`, validated))
+        ast.types.every((part, index) => isTemplateLiteralPart(part, `${currentPath}.types[${index}]`, validated))
       break
+    }
     default:
       return false
   }
@@ -1477,10 +1489,10 @@ export const TemplateLiteral: new(
     super(annotations, checks, encoding, context)
     const encodedParts: Array<TemplateLiteralPart> = []
     const literals: Array<string | undefined> = []
-    const validated = new WeakSet<AST>()
+    const validated = new Set<AST>()
     for (let index = 0; index < parts.length; index++) {
       const part = parts[index]
-      if (!isTemplateLiteralPart(part, `parts[${index}]`, validated)) {
+      if (!isTemplateLiteralPart(part, index, validated)) {
         throw new Error(`Invalid TemplateLiteral part ${part._tag}`)
       }
       encodedParts.push(part)
@@ -2573,8 +2585,23 @@ function isIndexSignatureParameterSide(ast: AST): ast is IndexSignatureParameter
   }
 }
 
+function isIndexSignatureParameterEncodedSide(ast: AST): boolean {
+  const encoded = getLastEncoding(ast)
+  switch (encoded._tag) {
+    case "String":
+    case "Number":
+    case "Symbol":
+    case "TemplateLiteral":
+      return true
+    case "Union":
+      return encoded.types.every(isIndexSignatureParameterEncodedSide)
+    default:
+      return false
+  }
+}
+
 function isIndexSignatureParameter(ast: AST): ast is IndexSignatureParameter {
-  return isIndexSignatureParameterSide(ast) && isIndexSignatureParameterSide(toEncoded(ast))
+  return isIndexSignatureParameterSide(ast) && isIndexSignatureParameterEncodedSide(ast)
 }
 
 /**
@@ -2727,7 +2754,16 @@ export const Objects: new(
     this.encodingChecks = encodingChecks
 
     // Duplicate property signatures
-    const duplicates = propertySignatures.map((ps) => ps.name).filter((name, i, arr) => arr.indexOf(name) !== i)
+    const seen = new Set<PropertyKey>()
+    const duplicates: Array<PropertyKey> = []
+    for (const propertySignature of propertySignatures) {
+      const name = propertySignature.name
+      if (seen.has(name)) {
+        duplicates.push(name)
+      } else {
+        seen.add(name)
+      }
+    }
     if (duplicates.length > 0) {
       throw new Error(`Duplicate identifiers: ${JSON.stringify(duplicates)}. ts(2300)`)
     }
@@ -3780,20 +3816,6 @@ function formatIsOptional(isOptional: boolean | undefined): string {
   return isOptional ? "?" : ""
 }
 
-/** @internal */
-export function memoizeThunk<A>(f: () => A): () => A {
-  let done = false
-  let a: A
-  return () => {
-    if (done) {
-      return a
-    }
-    a = f()
-    done = true
-    return a
-  }
-}
-
 /**
  * AST node for lazy/recursive schemas.
  *
@@ -3866,7 +3888,8 @@ export const Suspend: new(
       throw new Error("Cannot add checks to Suspend")
     }
     super(annotations, undefined, encoding, context)
-    this.thunk = memoizeThunk(thunk)
+    let ast: AST
+    this.thunk = () => ast ??= thunk()
   }
   /** @internal */
   getParser(compile: SchemaParser.Compiler): SchemaParser.Parser {

package/src/SchemaParser.ts

@@ -41,9 +41,10 @@ import * as SchemaIssue from "./SchemaIssue.ts"
  * @since 4.0.0
  */
 export function makeEffect<S extends Schema.Constraint>(schema: S) {
-  const parser = runWithCompiler<S["Type"], never>(constructorCompiler, SchemaAST.toType(schema.ast))
+  const ast = schema.ast
+  let parser: ReturnType<typeof runWithCompiler<S["Type"], never>>
   return (input: S["~type.make.in"], options?: Schema.MakeOptions): Effect.Effect<S["Type"], SchemaIssue.Issue> => {
-    return parser(
+    return (parser ??= runWithCompiler<S["Type"], never>(constructorCompiler, SchemaAST.toType(ast)))(
       input,
       options?.disableChecks
         ? options?.parseOptions ? { ...options.parseOptions, disableChecks: true } : { disableChecks: true }