effect 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/Cron.d.ts

@@ -13,7 +13,8 @@ declare const TypeId = "~effect/time/Cron";
  * seconds, minutes, hours, days, months, and weekdays constraints.
  * It also supports timezone-aware scheduling.
  *
- * @example
+ * **Example** (Creating a cron schedule)
+ *
  * ```ts
  * import { Cron } from "effect"
  *
@@ -63,8 +64,8 @@ declare const TypeId = "~effect/time/Cron";
  * console.log(matches) // true if it's 9 AM on a weekday
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Cron extends Pipeable, Equal.Equal, Inspectable {
     readonly [TypeId]: typeof TypeId;
@@ -83,7 +84,8 @@ export interface Cron extends Pipeable, Equal.Equal, Inspectable {
  * value is a valid Cron instance by checking for the presence of the
  * Cron type identifier.
  *
- * @example
+ * **Example** (Checking cron values)
+ *
  * ```ts
  * import { Cron } from "effect"
  *
@@ -100,8 +102,8 @@ export interface Cron extends Pipeable, Equal.Equal, Inspectable {
  * console.log(Cron.isCron("not a cron")) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export declare const isCron: (u: unknown) => u is Cron;
 /**
@@ -111,7 +113,8 @@ export declare const isCron: (u: unknown) => u is Cron;
  * days, months, and weekdays the schedule should match. Empty arrays mean
  * "match all" for that time unit.
  *
- * @example
+ * **Example** (Creating schedules from constraints)
+ *
  * ```ts
  * import { Cron } from "effect"
  *
@@ -198,8 +201,8 @@ export declare const isCron: (u: unknown) => u is Cron;
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const make: (values: {
     readonly seconds?: Iterable<number> | undefined;
@@ -221,7 +224,8 @@ declare const CronParseError_base: new <A extends Record<string, any> = {}>(args
  * the parsing process, including the error message and optionally the
  * input that caused the error.
  *
- * @example
+ * **Example** (Handling cron parse failures)
+ *
  * ```ts
  * import { Cron, Result } from "effect"
  *
@@ -233,8 +237,8 @@ declare const CronParseError_base: new <A extends Record<string, any> = {}>(args
  * }
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export declare class CronParseError extends CronParseError_base<{
     readonly message: string;
@@ -249,7 +253,8 @@ export declare class CronParseError extends CronParseError_base<{
  * value is a CronParseError by checking for the presence of the
  * CronParseError type identifier.
  *
- * @example
+ * **Example** (Checking cron parse errors)
+ *
  * ```ts
  * import { Cron, Result } from "effect"
  *
@@ -263,16 +268,21 @@ export declare class CronParseError extends CronParseError_base<{
  * console.log(Cron.isCronParseError("not an error")) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export declare const isCronParseError: (u: unknown) => u is CronParseError;
 /**
- * Parses a cron expression into a `Cron` instance.
+ * Parses a cron expression into a `Cron` instance, returning a `Result` instead
+ * of throwing.
  *
- * @param cron - The cron expression to parse.
+ * The expression may contain five fields, where seconds default to `0`, or six
+ * fields including seconds. Fields support `*`, comma-separated values, ranges,
+ * steps, and month or weekday aliases. Invalid expressions fail with
+ * `CronParseError`.
+ *
+ * **Example** (Parsing cron expressions)
  *
- * @example
  * ```ts
  * import { Cron, Result } from "effect"
  * import * as assert from "node:assert"
@@ -291,8 +301,10 @@ export declare const isCronParseError: (u: unknown) => u is CronParseError;
  * )
  * ```
  *
- * @since 2.0.0
+ * @param cron - The cron expression to parse.
+ *
  * @category constructors
+ * @since 2.0.0
  */
 export declare const parse: (cron: string, tz?: DateTime.TimeZone | string) => Result.Result<Cron, CronParseError>;
 /**
@@ -302,7 +314,8 @@ export declare const parse: (cron: string, tz?: DateTime.TimeZone | string) => R
  * when you're confident the input is valid and want to avoid handling
  * the Result type.
  *
- * @example
+ * **Example** (Parsing cron expressions unsafely)
+ *
  * ```ts
  * import { Cron } from "effect"
  *
@@ -316,18 +329,20 @@ export declare const parse: (cron: string, tz?: DateTime.TimeZone | string) => R
  * // const invalid = Cron.parseUnsafe("invalid expression")
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const parseUnsafe: (cron: string, tz?: DateTime.TimeZone | string) => Cron;
 /**
- * Checks if a given date/time falls within an active Cron time window.
+ * Returns `true` when a date/time matches a `Cron` schedule.
  *
- * This function determines whether a specific date and time matches
- * the cron schedule, taking into account all time constraints and
- * the optional timezone.
+ * Seconds, minutes, hours, months, and the optional timezone are checked
+ * directly. For day constraints, an empty `days` or `weekdays` set means that
+ * field matches every value; when both sets are non-empty, a date matches if
+ * either the day-of-month or weekday matches.
+ *
+ * **Example** (Matching dates against a schedule)
  *
- * @example
  * ```ts
  * import { Cron, Result } from "effect"
  *
@@ -344,8 +359,8 @@ export declare const parseUnsafe: (cron: string, tz?: DateTime.TimeZone | string
  * console.log(matches3) // false - wrong day
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare const match: (cron: Cron, date: DateTime.DateTime.Input) => boolean;
 /**
@@ -355,7 +370,8 @@ export declare const match: (cron: Cron, date: DateTime.DateTime.Input) => boole
  * should trigger, starting from the specified date (or current time if
  * not provided).
  *
- * @example
+ * **Example** (Finding the next occurrence)
+ *
  * ```ts
  * import { Cron, Result } from "effect"
  *
@@ -371,15 +387,15 @@ export declare const match: (cron: Cron, date: DateTime.DateTime.Input) => boole
  * console.log(nextFromNow) // Next occurrence from now
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare const next: (cron: Cron, now?: DateTime.DateTime.Input) => Date;
 /**
  * Returns the previous scheduled date/time for the given Cron instance.
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export declare const prev: (cron: Cron, now?: DateTime.DateTime.Input) => Date;
 /**
@@ -389,7 +405,8 @@ export declare const prev: (cron: Cron, now?: DateTime.DateTime.Input) => Date;
  * of dates when the cron schedule should trigger, starting from the
  * specified date.
  *
- * @example
+ * **Example** (Iterating scheduled occurrences)
+ *
  * ```ts
  * import { Cron, Result } from "effect"
  *
@@ -403,18 +420,19 @@ export declare const prev: (cron: Cron, now?: DateTime.DateTime.Input) => Date;
  * // [Mon Jan 02 2023 09:00:00, Tue Jan 03 2023 09:00:00, ...]
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare const sequence: (cron: Cron, now?: DateTime.DateTime.Input) => IterableIterator<Date>;
 /**
- * An Equivalence instance for comparing Cron schedules.
+ * An `Equivalence` instance for comparing the field restrictions of two `Cron`
+ * schedules.
+ *
+ * This comparison checks seconds, minutes, hours, days, months, and weekdays.
+ * It does not compare the optional timezone.
  *
- * This equivalence compares two Cron instances by checking if their
- * time constraints (seconds, minutes, hours, days, months, weekdays)
- * are equivalent, regardless of the internal order.
+ * **Example** (Comparing schedules with equivalence)
  *
- * @example
  * ```ts
  * import { Cron } from "effect"
  *
@@ -437,17 +455,18 @@ export declare const sequence: (cron: Cron, now?: DateTime.DateTime.Input) => It
  * console.log(Cron.Equivalence(cron1, cron2)) // true
  * ```
  *
- * @since 2.0.0
  * @category instances
+ * @since 2.0.0
  */
 export declare const Equivalence: Equ.Equivalence<Cron>;
 /**
- * Checks if two Cron instances are equal.
+ * Checks whether two `Cron` instances have the same field restrictions.
+ *
+ * The comparison checks seconds, minutes, hours, days, months, and weekdays.
+ * It does not compare the optional timezone.
  *
- * This function compares two Cron instances to determine if they represent
- * the same schedule by checking all their time constraints for equality.
+ * **Example** (Checking schedule equality)
  *
- * @example
  * ```ts
  * import { Cron } from "effect"
  *
@@ -471,17 +490,18 @@ export declare const Equivalence: Equ.Equivalence<Cron>;
  * console.log(Cron.equals(cron1)(cron2)) // true (curried form)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export declare const equals: {
     /**
-     * Checks if two Cron instances are equal.
+     * Checks whether two `Cron` instances have the same field restrictions.
+     *
+     * The comparison checks seconds, minutes, hours, days, months, and weekdays.
+     * It does not compare the optional timezone.
      *
-     * This function compares two Cron instances to determine if they represent
-     * the same schedule by checking all their time constraints for equality.
+     * **Example** (Checking schedule equality)
      *
-     * @example
      * ```ts
      * import { Cron } from "effect"
      *
@@ -505,17 +525,18 @@ export declare const equals: {
      * console.log(Cron.equals(cron1)(cron2)) // true (curried form)
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (that: Cron): (self: Cron) => boolean;
     /**
-     * Checks if two Cron instances are equal.
+     * Checks whether two `Cron` instances have the same field restrictions.
+     *
+     * The comparison checks seconds, minutes, hours, days, months, and weekdays.
+     * It does not compare the optional timezone.
      *
-     * This function compares two Cron instances to determine if they represent
-     * the same schedule by checking all their time constraints for equality.
+     * **Example** (Checking schedule equality)
      *
-     * @example
      * ```ts
      * import { Cron } from "effect"
      *
@@ -539,8 +560,8 @@ export declare const equals: {
      * console.log(Cron.equals(cron1)(cron2)) // true (curried form)
      * ```
      *
-     * @since 2.0.0
      * @category predicates
+     * @since 2.0.0
      */
     (self: Cron, that: Cron): boolean;
 };

package/dist/Cron.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Cron.d.ts","sourceRoot":"","sources":["../src/Cron.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Cron.d.ts","sourceRoot":"","sources":["../src/Cron.ts"],"names":[],"mappings":"AA+CA,OAAO,KAAK,KAAK,QAAQ,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,GAAG,MAAM,kBAAkB,CAAA;AAIvC,OAAO,EAAE,KAAK,WAAW,EAAqB,MAAM,kBAAkB,CAAA;AAGtE,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,KAAK,QAAQ,EAAiB,MAAM,eAAe,CAAA;AAE5D,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAIrC,QAAA,MAAM,MAAM,sBAAsB,CAAA;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,WAAW,IAAK,SAAQ,QAAQ,EAAE,KAAK,CAAC,KAAK,EAAE,WAAW;IAC9D,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,MAAM,CAAA;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAC7C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACnC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAClC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACpC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAqCvC;AAyDD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,MAAM,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,IAA8B,CAAA;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AACH,eAAO,MAAM,IAAI,GAAI,QAAQ;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IAClC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IAChC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IAC/B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACnC,QAAQ,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,QAAQ,GAAG,SAAS,CAAA;CAC5C,KAAG,IAsDH,CAAA;AAmCD,QAAA,MAAM,oBAAoB,qCAAqC,CAAA;;;;AAE/D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,cAAe,SAAQ,oBAAmC;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB,CAAC;IACA,QAAQ,CAAC,CAAC,oBAAoB,CAAC,EAAE,OAAO,oBAAoB,CAAuB;CACpF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,gBAAgB,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,cAAsD,CAAA;AAEzG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,EAAE,KAAK,QAAQ,CAAC,QAAQ,GAAG,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,cAAc,CA2BvG,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,EAAE,KAAK,QAAQ,CAAC,QAAQ,GAAG,MAAM,KAAG,IAA0C,CAAA;AAEtH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,KAAK,GAAI,MAAM,IAAI,EAAE,MAAM,QAAQ,CAAC,QAAQ,CAAC,KAAK,KAAG,OAkCjE,CAAA;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,IAAI,GAAI,MAAM,IAAI,EAAE,MAAM,QAAQ,CAAC,QAAQ,CAAC,KAAK,KAAG,IAEhE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,MAAM,IAAI,EAAE,MAAM,QAAQ,CAAC,QAAQ,CAAC,KAAK,KAAG,IAEhE,CAAA;AA4JD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,QAAQ,GAAa,MAAM,IAAI,EAAE,MAAM,QAAQ,CAAC,QAAQ,CAAC,KAAK,KAAG,gBAAgB,CAAC,IAAI,CAIlG,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,WAAW,EAAE,GAAG,CAAC,WAAW,CAAC,IAAI,CAO7C,CAAA;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,MAAM,EAAE;IACnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAA;IACrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAA;CACsC,CAAA"}

package/dist/Cron.js

@@ -1,4 +1,46 @@
 /**
+ * The `Cron` module provides utilities for representing recurring calendar
+ * schedules with cron expressions. A `Cron` value stores allowed seconds,
+ * minutes, hours, days of month, months, weekdays, and an optional time zone,
+ * then uses those constraints to test dates and find scheduled occurrences.
+ *
+ * **Mental model**
+ *
+ * - A cron schedule is a set of allowed values for each time field
+ * - Expressions may use five fields (`minute hour day month weekday`) or six
+ *   fields (`second minute hour day month weekday`); five-field expressions
+ *   default seconds to `0`
+ * - Each field supports `*`, comma-separated values, ranges, and step syntax
+ * - Month and weekday fields support aliases such as `JAN`, `DEC`, `SUN`, and
+ *   `MON`
+ * - Empty internal field sets represent an unconstrained field, the same idea
+ *   as `*`
+ * - When both day-of-month and weekday are constrained, matching uses cron's
+ *   inclusive behavior: either field may match
+ *
+ * **Common tasks**
+ *
+ * - Build directly from field constraints: {@link make}
+ * - Parse expressions safely: {@link parse}
+ * - Parse expressions and throw on invalid input: {@link parseUnsafe}
+ * - Check whether a date satisfies a schedule: {@link match}
+ * - Find adjacent scheduled dates: {@link next}, {@link prev}
+ * - Iterate future scheduled dates: {@link sequence}
+ * - Compare schedule constraints: {@link equals}, {@link Equivalence}
+ * - Detect parse failures: {@link CronParseError}, {@link isCronParseError}
+ *
+ * **Gotchas**
+ *
+ * - Weekdays are numbered `0` through `6`, with `0` representing Sunday
+ * - Months are numbered `1` through `12`, while JavaScript `Date` months are
+ *   zero-based
+ * - `*` normalizes to an empty set internally, so inspect schedules with the
+ *   public helpers instead of assuming every allowed value is stored
+ * - `next` and `prev` search strictly after or before the provided instant
+ * - Time-zone-aware schedules account for daylight saving transitions; during
+ *   a fall-back transition, repeated local times are emitted once when moving
+ *   forward
+ *
  * @since 2.0.0
  */
 import * as Arr from "./Array.js";
@@ -69,7 +111,8 @@ const CronProto = {
  * value is a valid Cron instance by checking for the presence of the
  * Cron type identifier.
  *
- * @example
+ * **Example** (Checking cron values)
+ *
  * ```ts
  * import { Cron } from "effect"
  *
@@ -86,8 +129,8 @@ const CronProto = {
  * console.log(Cron.isCron("not a cron")) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export const isCron = u => hasProperty(u, TypeId);
 /**
@@ -97,7 +140,8 @@ export const isCron = u => hasProperty(u, TypeId);
  * days, months, and weekdays the schedule should match. Empty arrays mean
  * "match all" for that time unit.
  *
- * @example
+ * **Example** (Creating schedules from constraints)
+ *
  * ```ts
  * import { Cron } from "effect"
  *
@@ -184,8 +228,8 @@ export const isCron = u => hasProperty(u, TypeId);
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = values => {
   const o = Object.create(CronProto);
@@ -269,7 +313,8 @@ const CronParseErrorTypeId = "~effect/time/Cron/CronParseError";
  * the parsing process, including the error message and optionally the
  * input that caused the error.
  *
- * @example
+ * **Example** (Handling cron parse failures)
+ *
  * ```ts
  * import { Cron, Result } from "effect"
  *
@@ -281,8 +326,8 @@ const CronParseErrorTypeId = "~effect/time/Cron/CronParseError";
  * }
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class CronParseError extends /*#__PURE__*/Data.TaggedError("CronParseError") {
   [CronParseErrorTypeId] = CronParseErrorTypeId;
@@ -294,7 +339,8 @@ export class CronParseError extends /*#__PURE__*/Data.TaggedError("CronParseErro
  * value is a CronParseError by checking for the presence of the
  * CronParseError type identifier.
  *
- * @example
+ * **Example** (Checking cron parse errors)
+ *
  * ```ts
  * import { Cron, Result } from "effect"
  *
@@ -308,16 +354,21 @@ export class CronParseError extends /*#__PURE__*/Data.TaggedError("CronParseErro
  * console.log(Cron.isCronParseError("not an error")) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export const isCronParseError = u => hasProperty(u, CronParseErrorTypeId);
 /**
- * Parses a cron expression into a `Cron` instance.
+ * Parses a cron expression into a `Cron` instance, returning a `Result` instead
+ * of throwing.
  *
- * @param cron - The cron expression to parse.
+ * The expression may contain five fields, where seconds default to `0`, or six
+ * fields including seconds. Fields support `*`, comma-separated values, ranges,
+ * steps, and month or weekday aliases. Invalid expressions fail with
+ * `CronParseError`.
+ *
+ * **Example** (Parsing cron expressions)
  *
- * @example
  * ```ts
  * import { Cron, Result } from "effect"
  * import * as assert from "node:assert"
@@ -336,8 +387,10 @@ export const isCronParseError = u => hasProperty(u, CronParseErrorTypeId);
  * )
  * ```
  *
- * @since 2.0.0
+ * @param cron - The cron expression to parse.
+ *
  * @category constructors
+ * @since 2.0.0
  */
 export const parse = (cron, tz) => {
   const segments = cron.split(" ").filter(String.isNonEmpty);
@@ -372,7 +425,8 @@ export const parse = (cron, tz) => {
  * when you're confident the input is valid and want to avoid handling
  * the Result type.
  *
- * @example
+ * **Example** (Parsing cron expressions unsafely)
+ *
  * ```ts
  * import { Cron } from "effect"
  *
@@ -386,18 +440,20 @@ export const parse = (cron, tz) => {
  * // const invalid = Cron.parseUnsafe("invalid expression")
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const parseUnsafe = (cron, tz) => Result.getOrThrow(parse(cron, tz));
 /**
- * Checks if a given date/time falls within an active Cron time window.
+ * Returns `true` when a date/time matches a `Cron` schedule.
+ *
+ * Seconds, minutes, hours, months, and the optional timezone are checked
+ * directly. For day constraints, an empty `days` or `weekdays` set means that
+ * field matches every value; when both sets are non-empty, a date matches if
+ * either the day-of-month or weekday matches.
  *
- * This function determines whether a specific date and time matches
- * the cron schedule, taking into account all time constraints and
- * the optional timezone.
+ * **Example** (Matching dates against a schedule)
  *
- * @example
  * ```ts
  * import { Cron, Result } from "effect"
  *
@@ -414,8 +470,8 @@ export const parseUnsafe = (cron, tz) => Result.getOrThrow(parse(cron, tz));
  * console.log(matches3) // false - wrong day
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const match = (cron, date) => {
   const parts = dateTime.makeZonedUnsafe(date, {
@@ -452,7 +508,8 @@ const daysInMonth = date => new Date(Date.UTC(date.getUTCFullYear(), date.getUTC
  * should trigger, starting from the specified date (or current time if
  * not provided).
  *
- * @example
+ * **Example** (Finding the next occurrence)
+ *
  * ```ts
  * import { Cron, Result } from "effect"
  *
@@ -468,8 +525,8 @@ const daysInMonth = date => new Date(Date.UTC(date.getUTCFullYear(), date.getUTC
  * console.log(nextFromNow) // Next occurrence from now
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const next = (cron, now) => {
   return stepCron(cron, now, "next");
@@ -477,8 +534,8 @@ export const next = (cron, now) => {
 /**
  * Returns the previous scheduled date/time for the given Cron instance.
  *
- * @since 4.0.0
  * @category utils
+ * @since 4.0.0
  */
 export const prev = (cron, now) => {
   return stepCron(cron, now, "prev");
@@ -623,7 +680,8 @@ const stepCron = (cron, now, direction) => {
  * of dates when the cron schedule should trigger, starting from the
  * specified date.
  *
- * @example
+ * **Example** (Iterating scheduled occurrences)
+ *
  * ```ts
  * import { Cron, Result } from "effect"
  *
@@ -637,8 +695,8 @@ const stepCron = (cron, now, direction) => {
  * // [Mon Jan 02 2023 09:00:00, Tue Jan 03 2023 09:00:00, ...]
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const sequence = function* (cron, now) {
   while (true) {
@@ -646,13 +704,14 @@ export const sequence = function* (cron, now) {
   }
 };
 /**
- * An Equivalence instance for comparing Cron schedules.
+ * An `Equivalence` instance for comparing the field restrictions of two `Cron`
+ * schedules.
  *
- * This equivalence compares two Cron instances by checking if their
- * time constraints (seconds, minutes, hours, days, months, weekdays)
- * are equivalent, regardless of the internal order.
+ * This comparison checks seconds, minutes, hours, days, months, and weekdays.
+ * It does not compare the optional timezone.
+ *
+ * **Example** (Comparing schedules with equivalence)
  *
- * @example
  * ```ts
  * import { Cron } from "effect"
  *
@@ -675,19 +734,20 @@ export const sequence = function* (cron, now) {
  * console.log(Cron.Equivalence(cron1, cron2)) // true
  * ```
  *
- * @since 2.0.0
  * @category instances
+ * @since 2.0.0
  */
 export const Equivalence = /*#__PURE__*/Equ.make((self, that) => restrictionsEquals(self.seconds, that.seconds) && restrictionsEquals(self.minutes, that.minutes) && restrictionsEquals(self.hours, that.hours) && restrictionsEquals(self.days, that.days) && restrictionsEquals(self.months, that.months) && restrictionsEquals(self.weekdays, that.weekdays));
 const restrictionsArrayEquals = /*#__PURE__*/Equ.Array(/*#__PURE__*/Equ.strictEqual());
 const restrictionsEquals = (self, that) => restrictionsArrayEquals(Arr.fromIterable(self), Arr.fromIterable(that));
 /**
- * Checks if two Cron instances are equal.
+ * Checks whether two `Cron` instances have the same field restrictions.
+ *
+ * The comparison checks seconds, minutes, hours, days, months, and weekdays.
+ * It does not compare the optional timezone.
  *
- * This function compares two Cron instances to determine if they represent
- * the same schedule by checking all their time constraints for equality.
+ * **Example** (Checking schedule equality)
  *
- * @example
  * ```ts
  * import { Cron } from "effect"
  *
@@ -711,8 +771,8 @@ const restrictionsEquals = (self, that) => restrictionsArrayEquals(Arr.fromItera
  * console.log(Cron.equals(cron1)(cron2)) // true (curried form)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const equals = /*#__PURE__*/dual(2, (self, that) => Equivalence(self, that));
 const secondOptions = {