effect 3.10.18 → 3.11.0

package/src/Cron.ts

@@ -2,13 +2,16 @@
  * @since 2.0.0
  */
 import * as Arr from "./Array.js"
+import type * as DateTime from "./DateTime.js"
 import * as Either from "./Either.js"
 import * as Equal from "./Equal.js"
 import * as equivalence from "./Equivalence.js"
 import { dual, pipe } from "./Function.js"
 import * as Hash from "./Hash.js"
 import { format, type Inspectable, NodeInspectSymbol } from "./Inspectable.js"
+import * as dateTime from "./internal/dateTime.js"
 import * as N from "./Number.js"
+import * as Option from "./Option.js"
 import { type Pipeable, pipeArguments } from "./Pipeable.js"
 import { hasProperty } from "./Predicate.js"
 import * as String from "./String.js"
@@ -32,6 +35,7 @@ export type TypeId = typeof TypeId
  */
 export interface Cron extends Pipeable, Equal.Equal, Inspectable {
   readonly [TypeId]: TypeId
+  readonly tz: Option.Option<DateTime.TimeZone>
   readonly minutes: ReadonlySet<number>
   readonly hours: ReadonlySet<number>
   readonly days: ReadonlySet<number>
@@ -39,14 +43,15 @@ export interface Cron extends Pipeable, Equal.Equal, Inspectable {
   readonly weekdays: ReadonlySet<number>
 }
 
-const CronProto: Omit<Cron, "minutes" | "hours" | "days" | "months" | "weekdays"> = {
+const CronProto: Omit<Cron, "minutes" | "hours" | "days" | "months" | "weekdays" | "tz"> = {
   [TypeId]: TypeId,
   [Equal.symbol](this: Cron, that: unknown) {
     return isCron(that) && equals(this, that)
   },
   [Hash.symbol](this: Cron): number {
     return pipe(
-      Hash.array(Arr.fromIterable(this.minutes)),
+      Hash.hash(this.tz),
+      Hash.combine(Hash.array(Arr.fromIterable(this.minutes))),
       Hash.combine(Hash.array(Arr.fromIterable(this.hours))),
       Hash.combine(Hash.array(Arr.fromIterable(this.days))),
       Hash.combine(Hash.array(Arr.fromIterable(this.months))),
@@ -60,6 +65,7 @@ const CronProto: Omit<Cron, "minutes" | "hours" | "days" | "months" | "weekdays"
   toJSON(this: Cron) {
     return {
       _id: "Cron",
+      tz: this.tz,
       minutes: Arr.fromIterable(this.minutes),
       hours: Arr.fromIterable(this.hours),
       days: Arr.fromIterable(this.days),
@@ -86,7 +92,7 @@ const CronProto: Omit<Cron, "minutes" | "hours" | "days" | "months" | "weekdays"
 export const isCron = (u: unknown): u is Cron => hasProperty(u, TypeId)
 
 /**
- * Creates a `Cron` instance from.
+ * Creates a `Cron` instance.
  *
  * @param constraints - The cron constraints.
  *
@@ -98,6 +104,7 @@ export const make = ({
   hours,
   minutes,
   months,
+  tz,
   weekdays
 }: {
   readonly minutes: Iterable<number>
@@ -105,6 +112,7 @@ export const make = ({
   readonly days: Iterable<number>
   readonly months: Iterable<number>
   readonly weekdays: Iterable<number>
+  readonly tz?: DateTime.TimeZone | undefined
 }): Cron => {
   const o: Mutable<Cron> = Object.create(CronProto)
   o.minutes = new Set(Arr.sort(minutes, N.Order))
@@ -112,6 +120,7 @@ export const make = ({
   o.days = new Set(Arr.sort(days, N.Order))
   o.months = new Set(Arr.sort(months, N.Order))
   o.weekdays = new Set(Arr.sort(weekdays, N.Order))
+  o.tz = Option.fromNullable(tz)
   return o
 }
 
@@ -170,6 +179,7 @@ export const isParseError = (u: unknown): u is ParseError => hasProperty(u, Pars
  * @param cron - The cron expression to parse.
  *
  * @example
+ * ```ts
  * import { Cron, Either } from "effect"
  *
  * // At 04:00 on every day-of-month from 8 through 14.
@@ -180,11 +190,12 @@ export const isParseError = (u: unknown): u is ParseError => hasProperty(u, Pars
  *   months: [],
  *   weekdays: []
  * })))
+ * ```
  *
  * @since 2.0.0
  * @category constructors
  */
-export const parse = (cron: string): Either.Either<Cron, ParseError> => {
+export const parse = (cron: string, tz?: DateTime.TimeZone): Either.Either<Cron, ParseError> => {
   const segments = cron.split(" ").filter(String.isNonEmpty)
   if (segments.length !== 5) {
     return Either.left(ParseError(`Invalid number of segments in cron expression`, cron))
@@ -197,57 +208,58 @@ export const parse = (cron: string): Either.Either<Cron, ParseError> => {
     days: parseSegment(days, dayOptions),
     months: parseSegment(months, monthOptions),
     weekdays: parseSegment(weekdays, weekdayOptions)
-  }).pipe(Either.map((segments) => make(segments)))
+  }).pipe(Either.map((segments) => make({ ...segments, tz })))
 }
 
 /**
  * Checks if a given `Date` falls within an active `Cron` time window.
  *
+ * @throws `IllegalArgumentException` if the given `DateTime.Input` is invalid.
+ *
  * @param cron - The `Cron` instance.
  * @param date - The `Date` to check against.
  *
  * @example
+ * ```ts
  * import { Cron, Either } from "effect"
  *
  * const cron = Either.getOrThrow(Cron.parse("0 4 8-14 * *"))
  * assert.deepStrictEqual(Cron.match(cron, new Date("2021-01-08 04:00:00")), true)
  * assert.deepStrictEqual(Cron.match(cron, new Date("2021-01-08 05:00:00")), false)
+ * ```
  *
  * @since 2.0.0
  */
-export const match = (cron: Cron, date: Date): boolean => {
-  const { days, hours, minutes, months, weekdays } = cron
+export const match = (cron: Cron, date: DateTime.DateTime.Input): boolean => {
+  const zoned = dateTime.unsafeMakeZoned(date)
+  const adjusted = Option.isSome(cron.tz) ? dateTime.setZone(zoned, cron.tz.value) : zoned
+  const parts = dateTime.toParts(adjusted)
 
-  const minute = date.getMinutes()
-  if (minutes.size !== 0 && !minutes.has(minute)) {
+  if (cron.minutes.size !== 0 && !cron.minutes.has(parts.minutes)) {
     return false
   }
 
-  const hour = date.getHours()
-  if (hours.size !== 0 && !hours.has(hour)) {
+  if (cron.hours.size !== 0 && !cron.hours.has(parts.hours)) {
     return false
   }
 
-  const month = date.getMonth() + 1
-  if (months.size !== 0 && !months.has(month)) {
+  if (cron.months.size !== 0 && !cron.months.has(parts.month)) {
     return false
   }
 
-  if (days.size === 0 && weekdays.size === 0) {
+  if (cron.days.size === 0 && cron.weekdays.size === 0) {
     return true
   }
 
-  const day = date.getDate()
-  if (weekdays.size === 0) {
-    return days.has(day)
+  if (cron.weekdays.size === 0) {
+    return cron.days.has(parts.day)
   }
 
-  const weekday = date.getDay()
-  if (days.size === 0) {
-    return weekdays.has(weekday)
+  if (cron.days.size === 0) {
+    return cron.weekdays.has(parts.weekDay)
   }
 
-  return days.has(day) || weekdays.has(weekday)
+  return cron.days.has(parts.day) || cron.weekdays.has(parts.weekDay)
 }
 
 /**
@@ -255,19 +267,24 @@ export const match = (cron: Cron, date: Date): boolean => {
  *
  * Uses the current time as a starting point if no value is provided for `now`.
  *
+ * @throws `IllegalArgumentException` if the given `DateTime.Input` is invalid.
+ * @throws `Error` if the next run date cannot be found within 10,000 iterations.
+ *
  * @example
+ * ```ts
  * import { Cron, Either } from "effect"
  *
  * const after = new Date("2021-01-01 00:00:00")
  * const cron = Either.getOrThrow(Cron.parse("0 4 8-14 * *"))
  * assert.deepStrictEqual(Cron.next(cron, after), new Date("2021-01-08 04:00:00"))
+ * ```
  *
  * @param cron - The `Cron` instance.
  * @param now - The `Date` to start searching from.
  *
  * @since 2.0.0
  */
-export const next = (cron: Cron, now?: Date): Date => {
+export const next = (cron: Cron, now?: DateTime.DateTime.Input): Date => {
   const { days, hours, minutes, months, weekdays } = cron
 
   const restrictMinutes = minutes.size !== 0
@@ -276,61 +293,67 @@ export const next = (cron: Cron, now?: Date): Date => {
   const restrictMonths = months.size !== 0
   const restrictWeekdays = weekdays.size !== 0
 
-  const current = now ? new Date(now.getTime()) : new Date()
-  // Increment by one minute to ensure we don't match the current date.
-  current.setMinutes(current.getMinutes() + 1)
-  current.setSeconds(0)
-  current.setMilliseconds(0)
-
-  // Only search 8 years into the future.
-  const limit = new Date(current).setFullYear(current.getFullYear() + 8)
-  while (current.getTime() <= limit) {
-    if (restrictMonths && !months.has(current.getMonth() + 1)) {
-      current.setMonth(current.getMonth() + 1)
-      current.setDate(1)
-      current.setHours(0)
-      current.setMinutes(0)
-      continue
-    }
-
-    if (restrictDays && restrictWeekdays) {
-      if (!days.has(current.getDate()) && !weekdays.has(current.getDay())) {
-        current.setDate(current.getDate() + 1)
-        current.setHours(0)
-        current.setMinutes(0)
+  // TODO: This is unsafe.
+  const zoned = dateTime.unsafeMakeZoned(now ?? new Date())
+  const adjusted = Option.isSome(cron.tz) ? dateTime.setZone(zoned, cron.tz.value) : zoned
+
+  // TODO: This algorithm can be optimized to avoid some unnecessary iterations.
+  const result = dateTime.mutate(adjusted, (current) => {
+    // Increment by one minute to ensure we don't match the current date.
+    current.setUTCMinutes(current.getUTCMinutes() + 1)
+    current.setUTCSeconds(0)
+    current.setUTCMilliseconds(0)
+
+    for (let i = 0; i < 10_000; i++) {
+      if (restrictMonths && !months.has(current.getUTCMonth() + 1)) {
+        current.setUTCMonth(current.getUTCMonth() + 1)
+        current.setUTCDate(1)
+        current.setUTCHours(0)
+        current.setUTCMinutes(0)
         continue
       }
-    } else if (restrictDays) {
-      if (!days.has(current.getDate())) {
-        current.setDate(current.getDate() + 1)
-        current.setHours(0)
-        current.setMinutes(0)
-        continue
+
+      if (restrictDays && restrictWeekdays) {
+        if (!days.has(current.getUTCDate()) && !weekdays.has(current.getUTCDay())) {
+          current.setUTCDate(current.getUTCDate() + 1)
+          current.setUTCHours(0)
+          current.setUTCMinutes(0)
+          continue
+        }
+      } else if (restrictDays) {
+        if (!days.has(current.getUTCDate())) {
+          current.setUTCDate(current.getUTCDate() + 1)
+          current.setUTCHours(0)
+          current.setUTCMinutes(0)
+          continue
+        }
+      } else if (restrictWeekdays) {
+        if (!weekdays.has(current.getUTCDay())) {
+          current.setUTCDate(current.getUTCDate() + 1)
+          current.setUTCHours(0)
+          current.setUTCMinutes(0)
+          continue
+        }
       }
-    } else if (restrictWeekdays) {
-      if (!weekdays.has(current.getDay())) {
-        current.setDate(current.getDate() + 1)
-        current.setHours(0)
-        current.setMinutes(0)
+
+      if (restrictHours && !hours.has(current.getUTCHours())) {
+        current.setUTCHours(current.getUTCHours() + 1)
+        current.setUTCMinutes(0)
         continue
       }
-    }
 
-    if (restrictHours && !hours.has(current.getHours())) {
-      current.setHours(current.getHours() + 1)
-      current.setMinutes(0)
-      continue
-    }
+      if (restrictMinutes && !minutes.has(current.getUTCMinutes())) {
+        current.setUTCMinutes(current.getUTCMinutes() + 1)
+        continue
+      }
 
-    if (restrictMinutes && !minutes.has(current.getMinutes())) {
-      current.setMinutes(current.getMinutes() + 1)
-      continue
+      return
     }
 
-    return current
-  }
+    throw new Error("Unable to find next cron date")
+  })
 
-  throw new Error("Unable to find next cron date")
+  return dateTime.toDateUtc(result)
 }
 
 /**
@@ -341,7 +364,7 @@ export const next = (cron: Cron, now?: Date): Date => {
  *
  * @since 2.0.0
  */
-export const sequence = function*(cron: Cron, now?: Date): IterableIterator<Date> {
+export const sequence = function*(cron: Cron, now?: DateTime.DateTime.Input): IterableIterator<Date> {
   while (true) {
     yield now = next(cron, now)
   }

package/src/Data.ts

@@ -27,6 +27,7 @@ export declare namespace Case {
 
 /**
  * @example
+ * ```ts
  * import { Data, Equal } from "effect"
  *
  * const alice = Data.struct({ name: "Alice", age: 30 })
@@ -38,6 +39,7 @@ export declare namespace Case {
  *
  * assert.deepStrictEqual(Equal.equals(alice, { name: "Alice", age: 30 }), false)
  * assert.deepStrictEqual(Equal.equals(alice, bob), false)
+ * ```
  *
  * @category constructors
  * @since 2.0.0
@@ -53,6 +55,7 @@ export const unsafeStruct = <A extends Record<string, any>>(as: A): { readonly [
 
 /**
  * @example
+ * ```ts
  * import { Data, Equal } from "effect"
  *
  * const alice = Data.tuple("Alice", 30)
@@ -64,6 +67,7 @@ export const unsafeStruct = <A extends Record<string, any>>(as: A): { readonly [
  *
  * assert.deepStrictEqual(Equal.equals(alice, ["Alice", 30]), false)
  * assert.deepStrictEqual(Equal.equals(alice, bob), false)
+ * ```
  *
  * @category constructors
  * @since 2.0.0
@@ -72,6 +76,7 @@ export const tuple = <As extends ReadonlyArray<any>>(...as: As): Readonly<As> =>
 
 /**
  * @example
+ * ```ts
  * import { Data, Equal } from "effect"
  *
  * const alice = Data.struct({ name: "Alice", age: 30 })
@@ -89,6 +94,7 @@ export const tuple = <As extends ReadonlyArray<any>>(...as: As): Readonly<As> =>
  *   ),
  *   true
  * )
+ * ```
  *
  * @category constructors
  * @since 2.0.0
@@ -110,6 +116,7 @@ export {
    * Provides a constructor for the specified `Case`.
    *
    * @example
+   * ```ts
    * import { Data, Equal } from "effect"
    *
    * interface Person {
@@ -128,6 +135,7 @@ export {
    * assert.deepStrictEqual(Equal.equals(mike1, mike2), true)
    * assert.deepStrictEqual(Equal.equals(mike1, john), false)
    *
+   * ```
    * @since 2.0.0
    * @category constructors
    */
@@ -138,6 +146,7 @@ export {
  * Provides a tagged constructor for the specified `Case`.
  *
  * @example
+ * ```ts
  * import { Data } from "effect"
  *
  * interface Person {
@@ -150,6 +159,7 @@ export {
  * const mike = Person({ name: "Mike" })
  *
  * assert.deepEqual(mike, { _tag: "Person", name: "Mike" })
+ * ```
  *
  * @since 2.0.0
  * @category constructors
@@ -167,6 +177,7 @@ export const tagged = <A extends { readonly _tag: string }>(
  * Provides a constructor for a Case Class.
  *
  * @example
+ * ```ts
  * import { Data, Equal } from "effect"
  *
  * class Person extends Data.Class<{ readonly name: string }> {}
@@ -179,6 +190,7 @@ export const tagged = <A extends { readonly _tag: string }>(
  * // Checking equality
  * assert.deepStrictEqual(Equal.equals(mike1, mike2), true)
  * assert.deepStrictEqual(Equal.equals(mike1, john), false)
+ * ```
  *
  * @since 2.0.0
  * @category constructors
@@ -192,6 +204,7 @@ export const Class: new<A extends Record<string, any> = {}>(
  * Provides a Tagged constructor for a Case Class.
  *
  * @example
+ * ```ts
  * import { Data, Equal } from "effect"
  *
  * class Person extends Data.TaggedClass("Person")<{ readonly name: string }> {}
@@ -206,6 +219,7 @@ export const Class: new<A extends Record<string, any> = {}>(
  * assert.deepStrictEqual(Equal.equals(mike1, john), false)
  *
  * assert.deepStrictEqual(mike1._tag, "Person")
+ * ```
  *
  * @since 2.0.0
  * @category constructors
@@ -403,6 +417,7 @@ export declare namespace TaggedEnum {
  * the constructor.
  *
  * @example
+ * ```ts
  * import { Data } from "effect"
  *
  * const { BadRequest, NotFound } = Data.taggedEnum<
@@ -411,6 +426,7 @@ export declare namespace TaggedEnum {
  * >()
  *
  * const notFound = NotFound({ status: 404, message: "Not Found" })
+ * ```
  *
  * @example
  * import { Data } from "effect"
@@ -437,6 +453,7 @@ export const taggedEnum: {
    * the constructor.
    *
    * @example
+   * ```ts
    * import { Data } from "effect"
    *
    * const { BadRequest, NotFound } = Data.taggedEnum<
@@ -445,6 +462,7 @@ export const taggedEnum: {
    * >()
    *
    * const notFound = NotFound({ status: 404, message: "Not Found" })
+   * ```
    *
    * @example
    * import { Data } from "effect"
@@ -482,6 +500,7 @@ export const taggedEnum: {
    * the constructor.
    *
    * @example
+   * ```ts
    * import { Data } from "effect"
    *
    * const { BadRequest, NotFound } = Data.taggedEnum<
@@ -490,6 +509,7 @@ export const taggedEnum: {
    * >()
    *
    * const notFound = NotFound({ status: 404, message: "Not Found" })
+   * ```
    *
    * @example
    * import { Data } from "effect"
@@ -527,6 +547,7 @@ export const taggedEnum: {
    * the constructor.
    *
    * @example
+   * ```ts
    * import { Data } from "effect"
    *
    * const { BadRequest, NotFound } = Data.taggedEnum<
@@ -535,6 +556,7 @@ export const taggedEnum: {
    * >()
    *
    * const notFound = NotFound({ status: 404, message: "Not Found" })
+   * ```
    *
    * @example
    * import { Data } from "effect"
@@ -572,6 +594,7 @@ export const taggedEnum: {
    * the constructor.
    *
    * @example
+   * ```ts
    * import { Data } from "effect"
    *
    * const { BadRequest, NotFound } = Data.taggedEnum<
@@ -580,6 +603,7 @@ export const taggedEnum: {
    * >()
    *
    * const notFound = NotFound({ status: 404, message: "Not Found" })
+   * ```
    *
    * @example
    * import { Data } from "effect"
@@ -617,6 +641,7 @@ export const taggedEnum: {
    * the constructor.
    *
    * @example
+   * ```ts
    * import { Data } from "effect"
    *
    * const { BadRequest, NotFound } = Data.taggedEnum<
@@ -625,6 +650,7 @@ export const taggedEnum: {
    * >()
    *
    * const notFound = NotFound({ status: 404, message: "Not Found" })
+   * ```
    *
    * @example
    * import { Data } from "effect"