stacks 0.58.50 → 0.58.52

package/core/scheduler/src/types/cron.ts

@@ -0,0 +1,98 @@
+import type { SpawnOptions } from 'node:child_process'
+import type { DateTime } from 'luxon'
+import type { CONSTRAINTS, TIME_UNITS_MAP } from '../constants'
+import type { CronJob } from '../job'
+import type { IntRange } from './utils'
+
+interface BaseCronJobParams<
+  OC extends CronOnCompleteCommand | null = null,
+  C = null,
+> {
+  cronTime: string | Date | DateTime
+  onTick: CronCommand<C, WithOnComplete<OC>>
+  onComplete?: OC
+  start?: boolean | null
+  context?: C
+  runOnInit?: boolean | null
+  unrefTimeout?: boolean | null
+}
+
+export type CronJobParams<
+  OC extends CronOnCompleteCommand | null = null,
+  C = null,
+> = BaseCronJobParams<OC, C> &
+(
+  | {
+    timeZone?: string | null
+    utcOffset?: never
+  }
+  | {
+    timeZone?: never
+    utcOffset?: number | null
+  }
+  )
+
+export type CronContext<C> = C extends null ? CronJob : NonNullable<C>
+
+export type CronCallback<C, WithOnCompleteBool extends boolean = false> = (
+  this: CronContext<C>,
+  onComplete: WithOnCompleteBool extends true ? CronOnCompleteCallback : never
+) => void | Promise<void>
+
+export type CronOnCompleteCallback = () => void | Promise<void>
+
+export type CronSystemCommand =
+  | string
+  | {
+    command: string
+    args?: readonly string[] | null
+    options?: SpawnOptions | null
+  }
+
+export type CronCommand<C, WithOnCompleteBool extends boolean = false> =
+  | CronCallback<C, WithOnCompleteBool>
+  | CronSystemCommand
+
+export type CronOnCompleteCommand = CronOnCompleteCallback | CronSystemCommand
+
+export type WithOnComplete<OC> = OC extends null ? false : true
+
+export type TimeUnit = (typeof TIME_UNITS_MAP)[keyof typeof TIME_UNITS_MAP]
+
+export type TimeUnitField<T extends TimeUnit> = Partial<
+  Record<Ranges[T], boolean>
+>
+
+export interface Ranges {
+  second: SecondRange
+  minute: MinuteRange
+  hour: HourRange
+  dayOfMonth: DayOfMonthRange
+  month: MonthRange
+  dayOfWeek: DayOfWeekRange
+}
+
+export type SecondRange = IntRange<
+  (typeof CONSTRAINTS)['second'][0],
+  (typeof CONSTRAINTS)['second'][1]
+>
+export type MinuteRange = IntRange<
+  (typeof CONSTRAINTS)['minute'][0],
+  (typeof CONSTRAINTS)['minute'][1]
+>
+export type HourRange = IntRange<
+  (typeof CONSTRAINTS)['hour'][0],
+  (typeof CONSTRAINTS)['hour'][1]
+>
+export type DayOfMonthRange = IntRange<
+  (typeof CONSTRAINTS)['dayOfMonth'][0],
+  (typeof CONSTRAINTS)['dayOfMonth'][1]
+>
+export type MonthRange = IntRange<
+  (typeof CONSTRAINTS)['month'][0],
+  (typeof CONSTRAINTS)['month'][1]
+>
+export type DayOfWeekRange = IntRange<
+  (typeof CONSTRAINTS)['dayOfWeek'][0],
+  (typeof CONSTRAINTS)['dayOfWeek'][1]
+>

package/core/scheduler/src/types/utils.ts

@@ -0,0 +1,14 @@
+export type IntRange<F extends number, T extends number> = Exclude<
+  Enumerate<T>,
+  Enumerate<F, false>
+>
+
+type Enumerate<
+  N extends number,
+  WithTail extends boolean = true,
+  Acc extends number[] = [],
+> = Acc['length'] extends N
+  ? WithTail extends true
+    ? [...Acc, Acc['length']][number]
+    : Acc[number]
+  : Enumerate<N, WithTail, [...Acc, Acc['length']]>

package/core/scheduler/src/utils.ts

@@ -0,0 +1,19 @@
+import type { Ranges } from './types/cron'
+import { ExclusiveParametersError } from './errors'
+
+export function getRecordKeys<K extends Ranges[keyof Ranges]>(record: Partial<Record<K, boolean>>) {
+  return Object.keys(record) as unknown as (keyof typeof record)[]
+}
+
+export function getTimeZoneAndOffset(timeZone?: string | null, utcOffset?: number | null) {
+  if (timeZone != null && utcOffset != null)
+    throw new ExclusiveParametersError('timeZone', 'utcOffset')
+
+  if (timeZone != null)
+    return { timeZone, utcOffset: null }
+
+  if (utcOffset != null)
+    return { timeZone: null, utcOffset }
+
+  return { timeZone: null, utcOffset: null }
+}

package/core/scheduler/tests/cron.fuzz.ts

@@ -0,0 +1,120 @@
+import { fc, test } from '@fast-check/jest'
+import { CronJob } from '../src'
+import { CronError } from '../src/errors'
+
+/**
+ * fuzzing might result in an infinite loop in our code, so Jest will simply timeout.
+ * experimental worker implementation of ```@fast-check/jest``` could help detect that issue
+ * that would be better as it would also give the counter-example that causes the bug
+ * but since it is still experimental, simply uncomment the log line in testCronJob
+ * function, so you can see the input causing the infinite loop.
+ */
+function testCronJob(
+  {
+    cronTime,
+    start,
+    timeZone,
+    runOnInit,
+    utcOffset,
+    unrefTimeout,
+    tzOrOffset,
+  }: {
+    cronTime: string
+    start: boolean
+    timeZone: string
+    runOnInit: boolean
+    utcOffset: number
+    unrefTimeout: boolean
+    tzOrOffset: boolean
+  },
+  checkError: (err: unknown) => boolean,
+) {
+  // console.debug(cronTime, '|', timeZone, '|', utcOffset);
+  try {
+    const job = new CronJob(
+      cronTime,
+      () => {},
+      null,
+      start,
+      (tzOrOffset ? timeZone : null) as typeof tzOrOffset extends true
+        ? string
+        : null,
+      null,
+      runOnInit,
+      (tzOrOffset ? null : utcOffset) as typeof tzOrOffset extends true
+        ? null
+        : number,
+      unrefTimeout,
+    )
+
+    expect(job.running).toBe(start)
+    job.stop()
+    expect(job.running).toBe(false)
+
+    expect(job.cronTime.source).toBe(cronTime)
+  }
+  catch (error) {
+    const isOk = checkError(error)
+    if (!isOk) {
+      console.error(error)
+      console.error(
+        'Make sure the relevant code is using an instance of CronError (or derived) when throwing.',
+      )
+    }
+    expect(isOk).toBe(true)
+  }
+}
+
+test.prop(
+  {
+    cronTime: fc.stringMatching(/^(((\d+,)+\d+|(\d+(\/|-)\d+)|\d+|\*) ){5,6}$/),
+    start: fc.boolean(),
+    timeZone: fc.stringMatching(
+      /^((?:Z|[+-](?:2[0-3]|[01][0-9]):[0-5][0-9])|(Africa\/Abidjan|Asia\/Singapore|Australia\/Sydney|CET|EST|Europe\/Paris|America\/New_York))$/,
+    ),
+    runOnInit: fc.boolean(),
+    utcOffset: fc.integer(),
+    unrefTimeout: fc.boolean(),
+    tzOrOffset: fc.boolean(),
+  },
+  { numRuns: 100_000 },
+)(
+  'CronJob should behave as expected and not error unexpectedly (with matching inputs)',
+  params => testCronJob(params, err => err instanceof CronError),
+)
+
+test.prop(
+  {
+    cronTime: fc.string(),
+    start: fc.boolean(),
+    timeZone: fc.string(),
+    runOnInit: fc.boolean(),
+    utcOffset: fc.integer(),
+    unrefTimeout: fc.boolean(),
+    tzOrOffset: fc.boolean(),
+  },
+  { numRuns: 100_000 },
+)(
+  'CronJob should behave as expected and not error unexpectedly (with random inputs)',
+  params => testCronJob(params, err => err instanceof CronError),
+)
+
+test.prop(
+  {
+    cronTime: fc.anything(),
+    start: fc.anything(),
+    timeZone: fc.anything(),
+    runOnInit: fc.anything(),
+    utcOffset: fc.anything(),
+    unrefTimeout: fc.anything(),
+    tzOrOffset: fc.boolean(),
+  },
+  { numRuns: 100_000 },
+)(
+  'CronJob should behave as expected and not error unexpectedly (with anything inputs)',
+  params =>
+    testCronJob(
+      params as any,
+      err => err instanceof CronError || err instanceof TypeError,
+    ),
+)