effect 4.0.7 → 4.1.0

package/src/FileSystem.ts

@@ -17,6 +17,7 @@ import * as Cause from "./Cause.ts"
 import * as Context from "./Context.ts"
 import * as Effect from "./Effect.ts"
 import { pipe } from "./Function.ts"
+import * as Glob from "./internal/glob.ts"
 import * as Layer from "./Layer.ts"
 import * as Option from "./Option.ts"
 import { badArgument, type PlatformError, systemError } from "./PlatformError.ts"
@@ -130,13 +131,36 @@ export interface FileSystem {
     gid: number
   ) => Effect.Effect<void, PlatformError>
   /**
-   * Glob a directory.
+   * Finds paths under `root` that match a glob pattern.
+   *
+   * **Details**
+   *
+   * Patterns follow `Glob.make`: wildcards skip names that start with `.`
+   * unless the pattern segment starts with `.` or `dot` is `true`, and
+   * `dir/**` includes `dir` itself. Results are `/`-separated paths relative
+   * to `root` (or absolute for an absolute pattern), visited depth-first with
+   * each directory's entries sorted by name. `**` does not traverse symbolic
+   * links to directories, but a link named by another segment is followed.
+   * Paths that match an `exclude` pattern are dropped, and excluded
+   * directories are not read. Entries whose type cannot be determined, such
+   * as broken links, are treated as files.
+   *
+   * Read failures at the root or a leading literal directory propagate. Missing
+   * paths return an empty result; unreadable wildcard-reached directories are
+   * skipped.
+   *
+   * **Gotchas**
+   *
+   * Wildcard matching is case-sensitive. Leading literal segments use `stat`,
+   * so their case sensitivity follows the file system and results retain the
+   * pattern's spelling.
    */
   readonly glob: (
     pattern: string,
     options?: {
       readonly root?: string | undefined
       readonly exclude?: ReadonlyArray<string> | undefined
+      readonly dot?: boolean | undefined
     }
   ) => Effect.Effect<Array<string>, PlatformError>
   /**
@@ -254,6 +278,22 @@ export interface FileSystem {
       readonly recursive?: boolean | undefined
     }
   ) => Effect.Effect<Array<string>, PlatformError>
+  /**
+   * Lists a directory with the type of each entry.
+   *
+   * **Details**
+   *
+   * Returns the same bare names as `readDirectory(path)`, excluding `.` and
+   * `..`, in no particular order. Types describe entries, not symlink targets.
+   * `"Unknown"` is allowed when the listing cannot determine the type, and
+   * `glob` then falls back to `stat`.
+   *
+   * **Gotchas**
+   *
+   * Wrappers that change `readDirectory`, such as by prefixing paths, must
+   * apply the same change here for `glob` to list the correct directory.
+   */
+  readonly readDirectoryEntries: (path: string) => Effect.Effect<ReadonlyArray<DirectoryEntry>, PlatformError>
   /**
    * Read the contents of a file.
    */
@@ -485,6 +525,21 @@ export type OpenFlag =
  */
 export const FileSystem: Context.Service<FileSystem, FileSystem> = Context.Service("effect/FileSystem")
 
+/**
+ * A directory entry with its type, independent of any symlink target.
+ * `"Unknown"` means the listing could not determine the type.
+ *
+ * @see {@link FileSystem} `readDirectoryEntries`, which returns these entries
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface DirectoryEntry {
+  readonly name: string
+  readonly type: File.Type
+}
+
 /**
  * Creates a FileSystem implementation from a partial implementation.
  *
@@ -497,8 +552,10 @@ export const FileSystem: Context.Service<FileSystem, FileSystem> = Context.Servi
  * **Details**
  *
  * This function takes a partial FileSystem implementation and automatically provides
- * default implementations for `exists`, `readFileString`, `stream`, `sink`, and
- * `writeFileString` methods based on the provided core methods.
+ * default implementations for `exists`, `glob`, `readFileString`, `stream`, `sink`,
+ * and `writeFileString` methods based on the provided core methods. `glob` walks
+ * the tree with `readDirectoryEntries`, using `stat` and `readLink` for entries
+ * whose type is `"Unknown"`.
  *
  * @see {@link makeNoop} for a testing stub that accepts method overrides without requiring a complete implementation
  * @see {@link layerNoop} for providing a no-op `FileSystem` as a `Layer` in tests
@@ -508,11 +565,12 @@ export const FileSystem: Context.Service<FileSystem, FileSystem> = Context.Servi
  * @since 4.0.0
  */
 export const make = (
-  impl: Omit<FileSystem, typeof TypeId | "exists" | "readFileString" | "stream" | "sink" | "writeFileString">
+  impl: Omit<FileSystem, typeof TypeId | "exists" | "glob" | "readFileString" | "stream" | "sink" | "writeFileString">
 ): FileSystem =>
   FileSystem.of({
     ...impl,
     [TypeId]: TypeId,
+    glob: Glob.make(impl),
     exists: (path) =>
       pipe(
         impl.access(path),
@@ -702,6 +760,9 @@ export const makeNoop = (fileSystem: Partial<FileSystem>): FileSystem =>
     readDirectory(path) {
       return Effect.fail(notFound("readDirectory", path))
     },
+    readDirectoryEntries(path) {
+      return Effect.fail(notFound("readDirectoryEntries", path))
+    },
     readFile(path) {
       return Effect.fail(notFound("readFile", path))
     },

package/src/Glob.ts

@@ -0,0 +1,205 @@
+/**
+ * Matches `/`-separated paths without accessing the file system, using the
+ * same pattern syntax as `FileSystem.glob`.
+ *
+ * @stability experimental
+ * @since 4.0.0
+ */
+import { format } from "./Formatter.ts"
+import { dual } from "./Function.ts"
+import { type Inspectable, NodeInspectSymbol } from "./Inspectable.ts"
+import * as internal from "./internal/glob.ts"
+import { type Pipeable, pipeArguments } from "./Pipeable.ts"
+
+const TypeId = "~effect/Glob"
+
+/**
+ * A compiled glob pattern.
+ *
+ * **Details**
+ *
+ * `pattern` is the source text and `dot` records whether wildcards match names
+ * that start with `.`. Match paths against it with {@link match}.
+ *
+ * @see {@link make} for compiling a pattern
+ *
+ * @stability experimental
+ * @category models
+ * @since 4.0.0
+ */
+export interface Glob extends Pipeable, Inspectable {
+  readonly [TypeId]: typeof TypeId
+  readonly pattern: string
+  readonly dot: boolean
+}
+
+interface GlobImpl extends Glob {
+  readonly compiled: internal.Compiled
+}
+
+const GlobProto = {
+  [TypeId]: TypeId,
+  toJSON(this: Glob) {
+    return { _id: "Glob", pattern: this.pattern, dot: this.dot }
+  },
+  toString(this: Glob) {
+    return `Glob(${format(this.toJSON())})`
+  },
+  [NodeInspectSymbol](this: Glob) {
+    return this.toJSON()
+  },
+  pipe() {
+    return pipeArguments(this, arguments)
+  }
+}
+
+/**
+ * Compiles a glob pattern into a reusable `Glob`.
+ *
+ * **Details**
+ *
+ * Patterns use `/` as the separator. `*` matches any run of characters within
+ * one path segment, `?` matches one character, and `[...]` matches one
+ * character from a set, with `!` or `^` negating it and POSIX classes such as
+ * `[[:digit:]]` allowed. `{a,b}` expands to each alternative and may nest. A
+ * segment that is exactly `**` matches zero or more whole segments. A trailing
+ * `/` matches only directories, and `\` makes the next character literal.
+ *
+ * **Gotchas**
+ *
+ * Wildcards and `**` skip names that start with `.` unless the pattern segment
+ * itself starts with `.` or `dot` is `true`; they never match `.` or `..`.
+ * `x/.` is the same as `x/`, and a `.` or `..` segment after `**` makes the
+ * pattern match nothing, as does the empty pattern. UNC patterns and paths
+ * such as `//server/share` are not supported and never match. Braces and
+ * commas inside `[...]` are class members. Extended glob syntax and leading
+ * `!` negation are not interpreted, but ordinary wildcards still apply within
+ * them (for example, `?(a)` matches `x(a)`). Malformed syntax, such as an
+ * unclosed `[`, matches literally. Braces also stay literal if expansion would
+ * exceed 10,000 alternatives.
+ *
+ * **Example** (Matching source files)
+ *
+ * ```ts import.meta.vitest
+ * import { Glob } from "effect"
+ *
+ * const sources = Glob.make("src/**\/*.{ts,tsx}")
+ *
+ * Glob.match(sources, "src/index.ts") // => true
+ * Glob.match(sources, "src/ui/Button.tsx") // => true
+ * Glob.match(sources, "src/.cache/index.ts") // => false
+ * Glob.match(sources, "test/index.ts") // => false
+ * ```
+ *
+ * @stability experimental
+ * @category constructors
+ * @since 4.0.0
+ */
+export const make = (pattern: string, options?: {
+  /** Whether wildcards and `**` match names that start with `.`. */
+  readonly dot?: boolean | undefined
+}): Glob => {
+  const dot = options?.dot ?? false
+  const self = Object.create(GlobProto)
+  self.pattern = pattern
+  self.dot = dot
+  self.compiled = internal.compile([pattern], dot)
+  return self
+}
+
+/**
+ * Tests whether a `/`-separated path matches a `Glob`.
+ *
+ * **Details**
+ *
+ * Empty segments and `./` segments in the path are ignored. A trailing `/`
+ * marks the path as a directory, which a pattern ending in `/` requires.
+ *
+ * **Example** (Filtering paths)
+ *
+ * ```ts import.meta.vitest
+ * import { Glob, pipe } from "effect"
+ *
+ * const tests = Glob.make("**\/*.test.ts")
+ * const paths = ["src/a.ts", "src/a.test.ts", "test/b.test.ts"]
+ *
+ * paths.filter((path) => Glob.match(tests, path)) // => ["src/a.test.ts", "test/b.test.ts"]
+ * pipe(tests, Glob.match("./src/a.test.ts")) // => true
+ * ```
+ *
+ * @stability experimental
+ * @category predicates
+ * @since 4.0.0
+ */
+export const match: {
+  /**
+   * Tests whether a `/`-separated path matches a `Glob`.
+   *
+   * **Details**
+   *
+   * Empty segments and `./` segments in the path are ignored. A trailing `/`
+   * marks the path as a directory, which a pattern ending in `/` requires.
+   *
+   * **Example** (Filtering paths)
+   *
+   * ```ts import.meta.vitest
+   * import { Glob, pipe } from "effect"
+   *
+   * const tests = Glob.make("**\/*.test.ts")
+   * const paths = ["src/a.ts", "src/a.test.ts", "test/b.test.ts"]
+   *
+   * paths.filter((path) => Glob.match(tests, path)) // => ["src/a.test.ts", "test/b.test.ts"]
+   * pipe(tests, Glob.match("./src/a.test.ts")) // => true
+   * ```
+   *
+   * @stability experimental
+   * @category predicates
+   * @since 4.0.0
+   */
+  (path: string): (self: Glob) => boolean
+  /**
+   * Tests whether a `/`-separated path matches a `Glob`.
+   *
+   * **Details**
+   *
+   * Empty segments and `./` segments in the path are ignored. A trailing `/`
+   * marks the path as a directory, which a pattern ending in `/` requires.
+   *
+   * **Example** (Filtering paths)
+   *
+   * ```ts import.meta.vitest
+   * import { Glob, pipe } from "effect"
+   *
+   * const tests = Glob.make("**\/*.test.ts")
+   * const paths = ["src/a.ts", "src/a.test.ts", "test/b.test.ts"]
+   *
+   * paths.filter((path) => Glob.match(tests, path)) // => ["src/a.test.ts", "test/b.test.ts"]
+   * pipe(tests, Glob.match("./src/a.test.ts")) // => true
+   * ```
+   *
+   * @stability experimental
+   * @category predicates
+   * @since 4.0.0
+   */
+  (self: Glob, path: string): boolean
+} = dual(2, (self: Glob, path: string): boolean => internal.match((self as GlobImpl).compiled, path))
+
+/**
+ * Escapes glob syntax so a string matches only itself.
+ *
+ * **Example** (Matching a literal file name)
+ *
+ * ```ts import.meta.vitest
+ * import { Glob } from "effect"
+ *
+ * const name = "report[1].txt"
+ *
+ * Glob.match(Glob.make(name), name) // => false
+ * Glob.match(Glob.make(Glob.escape(name)), name) // => true
+ * ```
+ *
+ * @stability experimental
+ * @category utils
+ * @since 4.0.0
+ */
+export const escape = (input: string): string => input.replace(/[\\*?[\]{}]/g, "\\$&")

package/src/Match.ts

@@ -37,6 +37,31 @@ type ValueTagHandlers<I> = {
   readonly [Tag in Types.Tags<"_tag", I> & string]: (_: Extract<I, { readonly _tag: Tag }>) => any
 }
 
+// Members of `R` that a literal record can dispatch on: finite string / number
+// literals whose runtime key no other string / number member can produce.
+// Widened `string` / `number` and template literals add no keys, and a literal
+// is dropped when another member spells the same key (`1` with `"1"` or
+// `string`, `"1"` or `"NaN"` with `number`).
+type LiteralKeys<R, All = Extract<R, string | number>> = R extends string | number
+  ? {} extends Record<R, unknown> ? never
+  : R extends number ? `${R}` extends All ? never : R
+  : R extends `${infer N extends number}` ? N extends All ? never : R
+  : R extends "NaN" | "Infinity" | "-Infinity" ? number extends All ? never : R
+  : R
+  : never
+
+type LiteralHandlers<R, Ret> = [Exclude<R, LiteralKeys<R>>] extends [never] ? {
+    readonly [K in LiteralKeys<R>]: (_: K) => Ret
+  }
+  : never
+
+type PartialLiteralHandlers<R, Ret> = {
+  readonly [K in LiteralKeys<R>]?: ((_: K) => Ret) | undefined
+}
+
+// Only keys with a defined handler remove a literal from the remaining input.
+type HandledLiterals<P> = { readonly [K in keyof P]-?: undefined extends P[K] ? never : K }[keyof P]
+
 /**
  * Marker used by `Matcher` to distinguish matchers created with `Match.value`.
  *
@@ -1391,6 +1416,108 @@ export const tagsExhaustive: <
 ) => [Pr] extends [never] ? (u: I) => Unify<A | ReturnType<P[keyof P]>> : Unify<A | ReturnType<P[keyof P]>> =
   internal.tagsExhaustive
 
+/**
+ * Matches string and number literal values, mapping each literal to a
+ * corresponding handler.
+ *
+ * **Details**
+ *
+ * Each handler receives the matched literal. Handled literals are removed from
+ * the remaining input, while unhandled literals and any other members (such as
+ * `null`, objects, or widened `string` / `number` types) are left for later
+ * cases. Keys must be finite string or number literals of the remaining input;
+ * unions containing both a number and its string spelling, such as
+ * `1 | "1"`, are rejected because both share the same runtime key.
+ *
+ * **Example** (Mapping literal handlers)
+ *
+ * ```ts import.meta.vitest
+ * import { Match } from "effect"
+ *
+ * type Status = "draft" | "review" | "published"
+ *
+ * const isEditable = Match.type<Status>().pipe(
+ *   Match.literals({ draft: () => true, review: () => true }),
+ *   Match.orElse(() => false)
+ * )
+ *
+ * isEditable("review") // => true
+ * isEditable("published") // => false
+ * ```
+ *
+ * @see {@link literalsExhaustive} for handling every literal and finalizing the matcher
+ *
+ * @stability unstable
+ * @category defining patterns
+ * @since 4.1.0
+ */
+export const literals: <
+  R,
+  Ret,
+  P extends
+    & PartialLiteralHandlers<R, Ret>
+    & { readonly [K in Exclude<keyof P, LiteralKeys<R>>]: never }
+>(
+  fields: Contextual<P, PartialLiteralHandlers<R, Ret>>
+) => <I, F, A, Pr>(
+  self: Matcher<I, F, R, A, Pr, Ret>
+) => Matcher<
+  I,
+  Types.AddWithout<F, Extract<R, HandledLiterals<P>>>,
+  Types.ApplyFilters<I, Types.AddWithout<F, Extract<R, HandledLiterals<P>>>>,
+  A | ReturnType<P[keyof P] & {}>,
+  Pr,
+  Ret
+> = internal.literals
+
+/**
+ * Matches string and number literal values and requires handling of all
+ * remaining cases.
+ *
+ * **Details**
+ *
+ * This is the exhaustive variant of {@link literals}. Every remaining member
+ * must be a finite string or number literal with a corresponding handler, so a
+ * missing literal, a widened `string` / `number` type, or any other unhandled
+ * member is reported by TypeScript.
+ *
+ * **Example** (Handling all literal cases)
+ *
+ * ```ts import.meta.vitest
+ * import { Match } from "effect"
+ *
+ * type Status = "draft" | "review" | "published"
+ *
+ * const label = Match.type<Status>().pipe(
+ *   Match.literalsExhaustive({
+ *     draft: () => "Draft",
+ *     review: () => "In review",
+ *     published: () => "Live"
+ *   })
+ * )
+ *
+ * label("review") // => "In review"
+ * ```
+ *
+ * @see {@link literals} for defining literal handlers without finalizing the matcher
+ *
+ * @stability unstable
+ * @category defining patterns
+ * @since 4.1.0
+ */
+export const literalsExhaustive: <
+  R,
+  Ret,
+  P extends
+    & LiteralHandlers<R, Ret>
+    & { readonly [K in Exclude<keyof P, LiteralKeys<R>>]: never }
+>(
+  fields: Contextual<P, LiteralHandlers<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]>> =
+  internal.literalsExhaustive
+
 /**
  * Creates a pattern that excludes a specific value while allowing all others.
  *

package/src/Pool.ts

@@ -10,7 +10,6 @@
  * @stability stable
  * @since 2.0.0
  */
-import type * as Cause from "./Cause.ts"
 import { Clock } from "./Clock.ts"
 import * as Context from "./Context.ts"
 import * as Duration from "./Duration.ts"
@@ -23,7 +22,6 @@ import * as internal from "./internal/effect.ts"
 import { type Pipeable, pipeArguments } from "./Pipeable.ts"
 import { hasProperty } from "./Predicate.ts"
 import * as Queue from "./Queue.ts"
-import { UnhandledLogLevel } from "./References.ts"
 import * as Scope from "./Scope.ts"
 import * as Semaphore from "./Semaphore.ts"
 
@@ -96,6 +94,29 @@ export interface Config<A, E> {
   readonly targetUtilization: number
 }
 
+/**
+ * A point-in-time count of a pool's items and waiting borrowers.
+ *
+ * **Details**
+ *
+ * `idle` and `used` count acquired items, not borrowers, so an item shared by
+ * several borrowers counts once. `pending` counts borrowers waiting for an
+ * item. `min` and `max` are the configured size bounds.
+ *
+ * @see {@link stats} for reading a snapshot
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Stats {
+  readonly idle: number
+  readonly used: number
+  readonly pending: number
+  readonly min: number
+  readonly max: number
+}
+
 /**
  * Mutable runtime state maintained by a `Pool`.
  *
@@ -1026,6 +1047,52 @@ export const reserve: {
     ))
 )
 
+/**
+ * Returns a snapshot of how many items are idle or in use and how many
+ * borrowers are waiting.
+ *
+ * **When to use**
+ *
+ * Use to sample pool occupancy for metrics, such as connection counts for a
+ * database driver.
+ *
+ * **Details**
+ *
+ * - Only successfully acquired items are counted. Items still being acquired
+ *   and failed acquisitions are not.
+ * - An item is used while it has a borrower or a reservation, otherwise idle.
+ * - An invalidated item counts as used until its last borrower returns it.
+ *
+ * **Gotchas**
+ *
+ * The replacement for an invalidated item is acquired while the old one is
+ * still borrowed, so `idle + used` can briefly exceed `max`. A borrower that
+ * has been woken but has not yet taken its item is not counted as pending.
+ *
+ * @see {@link Stats} for the snapshot fields
+ *
+ * @stability unstable
+ * @category getters
+ * @since 4.0.0
+ */
+export const stats = <A, E>(self: Pool<A, E>): Effect.Effect<Stats> =>
+  Effect.sync(() => {
+    let idle = 0
+    let used = 0
+    for (const item of self.state.items) {
+      if (item.exit._tag !== "Success") continue
+      if (item.refCount > 0 || reservations.has(item)) used++
+      else idle++
+    }
+    return {
+      idle,
+      used,
+      pending: self.state.waiters.size,
+      min: self.config.minSize,
+      max: self.config.maxSize
+    }
+  })
+
 const invalidatePoolItem = <A, E>(self: Pool<A, E>, poolItem: PoolItem<A, E>): Effect.Effect<void> =>
   Effect.suspend(() => {
     if (!self.state.items.has(poolItem)) {
@@ -1111,7 +1178,10 @@ const allocate = <A, E>(self: Pool<A, E>): Effect.Effect<PoolItem<A, E>> =>
       const use = Effect.flatMap(Effect.exit(impl[Acquire]), (exit) => {
         const item: PoolItem<A, E> = {
           exit,
-          finalizer: Effect.catchCause(Scope.close(scope, exit), reportUnhandledError),
+          finalizer: Effect.ignoreCause(Scope.close(scope, exit), {
+            log: "Unhandled",
+            message: "Unhandled error in pool finalizer"
+          }),
           refCount: 0,
           idleSince: impl[PoolClock].currentTimeMillisUnsafe(),
           disableReclaim: false,
@@ -1235,15 +1305,3 @@ const strategyUsageTTL = Effect.fnUntraced(function*<A, E>(ttl: Duration.Input)
     reclaim: (_) => Effect.undefined
   })
 })
-
-const reportUnhandledError = <E>(cause: Cause.Cause<E>) =>
-  Effect.withFiber<void>((fiber) => {
-    const unhandledLogLevel = fiber.getRef(UnhandledLogLevel)
-    if (unhandledLogLevel) {
-      return Effect.logWithLevel(unhandledLogLevel)(
-        "Unhandled error in pool finalizer",
-        cause
-      )
-    }
-    return Effect.void
-  })

package/src/Random.ts

@@ -12,6 +12,7 @@
 import type * as Arr from "./Array.ts"
 import * as Cause from "./Cause.ts"
 import type * as Context from "./Context.ts"
+import * as SecureRandom from "./crypto/SecureRandom.ts"
 import * as Effect from "./Effect.ts"
 import { dual } from "./Function.ts"
 import * as random from "./internal/random.ts"
@@ -419,9 +420,8 @@ function ISAAC_CSPRNG(userSeed?: string | number) {
   seed(internalSeed)
 
   function getInitialSeed() {
-    const uint32a = new Uint32Array(2)
-    crypto.getRandomValues(uint32a)
-    return uint32a[0] + uint32a[1]
+    const view = new DataView(SecureRandom.randomBytesUnsafe(8).buffer)
+    return view.getUint32(0) + view.getUint32(4)
   }
 
   function reset() {

package/src/RcMap.ts

@@ -771,6 +771,7 @@ const removeInterrupted = <K, A, E>(
   // Borrowers close the entry on release; an idle entry has none left.
   if (entry.refCount > 0) return
   closeEntry(entry).pipe(
+    Effect.ignoreCause({ log: "Unhandled", message: "Unhandled error in RcMap finalizer" }),
     Effect.runForkWith(context),
     Fiber.runIn(self.scope)
   )
@@ -812,7 +813,10 @@ const release = <K, A, E>(self: RcMap<K, A, E>, key: K, entry: State.Entry<A, E>
         const o = MutableHashMap.get(self.state.map, key)
         if (o._tag === "None" || o.value !== entry) return Effect.void
         MutableHashMap.remove(self.state.map, key)
-        return Scope.close(entry.scope, Exit.void)
+        return Effect.ignoreCause(Scope.close(entry.scope, Exit.void), {
+          log: "Unhandled",
+          message: "Unhandled error in RcMap finalizer"
+        })
       }
       return Effect.flatMap(restore(clock.sleep(Duration.millis(remaining))), () => loop(restore))
     }).pipe(

package/src/Schedule.ts

@@ -809,6 +809,11 @@ const maxDuration = (results: ReadonlyArray<Duration.Duration | undefined>): Dur
  * Returns a new `Schedule` that recurs on the specified `Cron` schedule and
  * outputs the duration between recurrences.
  *
+ * **Details**
+ *
+ * A string expression is parsed with `Cron.parse`, using the optional time zone
+ * and `onDstOverlap` policy. A pre-parsed `Cron` value keeps its own policy.
+ *
  * **Example** (Scheduling work with cron expressions)
  *
  * ```ts import.meta.vitest
@@ -827,6 +832,11 @@ export const cron: {
    * Returns a new `Schedule` that recurs on the specified `Cron` schedule and
    * outputs the duration between recurrences.
    *
+   * **Details**
+   *
+   * A string expression is parsed with `Cron.parse`, using the optional time zone
+   * and `onDstOverlap` policy. A pre-parsed `Cron` value keeps its own policy.
+   *
    * **Example** (Scheduling work with cron expressions)
    *
    * ```ts import.meta.vitest
@@ -845,6 +855,11 @@ export const cron: {
    * Returns a new `Schedule` that recurs on the specified `Cron` schedule and
    * outputs the duration between recurrences.
    *
+   * **Details**
+   *
+   * A string expression is parsed with `Cron.parse`, using the optional time zone
+   * and `onDstOverlap` policy. A pre-parsed `Cron` value keeps its own policy.
+   *
    * **Example** (Scheduling work with cron expressions)
    *
    * ```ts import.meta.vitest
@@ -858,9 +873,17 @@ export const cron: {
    * @category constructors
    * @since 2.0.0
    */
-  (expression: string, tz?: string | DateTime.TimeZone): Schedule<Duration.Duration, unknown, Cron.CronParseError>
-} = (expression: string | Cron.Cron, tz?: string | DateTime.TimeZone) => {
-  const parsed = Cron.isCron(expression) ? Result.succeed(expression) : Cron.parse(expression, tz)
+  (
+    expression: string,
+    tz?: string | DateTime.TimeZone,
+    options?: {
+      readonly onDstOverlap?: Cron.DstOverlapPolicy | undefined
+    }
+  ): Schedule<Duration.Duration, unknown, Cron.CronParseError>
+} = (expression: string | Cron.Cron, tz?: string | DateTime.TimeZone, options?: {
+  readonly onDstOverlap?: Cron.DstOverlapPolicy | undefined
+}) => {
+  const parsed = Cron.isCron(expression) ? Result.succeed(expression) : Cron.parse(expression, tz, options)
   return fromStep(effect.map(effect.fromResult(parsed), (cron) => (now, _) => {
     if (now === Number.POSITIVE_INFINITY) {
       return Cause.done(Duration.zero)