@sixb/core 0.0.1

package/src/schedules/builders.ts

@@ -0,0 +1,257 @@
+import type { EventSelectorSpec } from "../events/selectors"
+import { eventSelectorSpec } from "../events/selectors"
+import {
+  allPredicates,
+  anyPredicates,
+  assertPredicateShape,
+  createFieldPredicate,
+  createPropertyPredicateBuilder,
+  notPredicate,
+  type Predicate,
+  type RuntimePropertyPredicateBuilder,
+} from "../predicates"
+import { createCronMatcher } from "./cron"
+import { ScheduleValidationError } from "./errors"
+import type {
+  CronScheduleDefinition,
+  EventScheduleCondition,
+  EventScheduleConditionScope,
+  EventScheduleDefinition,
+  EventScheduleScopedPredicate,
+  ScheduleBuilder,
+} from "./types"
+
+type RuntimeEventSchedulePropertyPredicateBuilder =
+  RuntimePropertyPredicateBuilder<EventScheduleScopedPredicate>
+
+type RuntimeEventSchedulePredicateSubject = {
+  p: Record<string, RuntimeEventSchedulePropertyPredicateBuilder>
+  all(...predicates: EventScheduleCondition[]): EventScheduleCondition
+  any(...predicates: EventScheduleCondition[]): EventScheduleCondition
+  not(predicate: EventScheduleCondition): EventScheduleCondition
+}
+
+type RuntimeEventSchedulePredicateContext = {
+  object?: RuntimeEventSchedulePredicateSubject
+  link?: RuntimeEventSchedulePredicateSubject
+  target?: RuntimeEventScheduleTargetPredicateSubject
+}
+
+type RuntimeEventScheduleTargetPredicateSubject = {
+  is(objectType: { readonly id: string }): EventScheduleCondition
+  id: { eq(value: string): EventScheduleCondition }
+}
+
+function assertNonEmpty(value: string, field: string): void {
+  if (!value.trim()) {
+    throw new ScheduleValidationError(`Schedule ${field} must not be empty.`)
+  }
+}
+
+function validateTimezone(timezone: string): void {
+  try {
+    Intl.DateTimeFormat(undefined, { timeZone: timezone })
+  } catch {
+    throw new ScheduleValidationError(`Invalid timezone '${timezone}'.`)
+  }
+}
+
+function createCondition(
+  scope: EventScheduleConditionScope,
+  predicate: Predicate
+): EventScheduleCondition {
+  return {
+    kind: "becomesTrue",
+    scope,
+    predicate,
+  }
+}
+
+function createEventSchedulePropertyPredicateBuilder(
+  scope: EventScheduleConditionScope,
+  propertyId: string
+): RuntimeEventSchedulePropertyPredicateBuilder {
+  return createPropertyPredicateBuilder(propertyId, {
+    subject: "Schedule",
+    createError: (message) => new ScheduleValidationError(message),
+    wrap: (predicate) => createCondition(scope, predicate),
+  })
+}
+
+function createPredicateSubject(
+  scope: EventScheduleConditionScope
+): RuntimeEventSchedulePredicateSubject {
+  const properties = new Proxy<Record<string, RuntimeEventSchedulePropertyPredicateBuilder>>(
+    {},
+    {
+      get(target, property) {
+        if (typeof property !== "string") return undefined
+        target[property] ??= createEventSchedulePropertyPredicateBuilder(scope, property)
+        return target[property]
+      },
+    }
+  )
+
+  return {
+    p: properties,
+    all(...conditions) {
+      return createCondition(
+        scope,
+        allPredicates(conditions.map((condition) => condition.predicate))
+      )
+    },
+    any(...conditions) {
+      return createCondition(
+        scope,
+        anyPredicates(conditions.map((condition) => condition.predicate))
+      )
+    },
+    not(condition) {
+      return createCondition(scope, notPredicate(condition.predicate))
+    },
+  }
+}
+
+function createTargetPredicateSubject(): RuntimeEventScheduleTargetPredicateSubject {
+  const condition = (field: string, value: string) =>
+    createCondition(
+      "event.link",
+      createFieldPredicate(field, value, {
+        subject: "Schedule",
+        createError: (message) => new ScheduleValidationError(message),
+      })
+    )
+
+  return {
+    is(objectType) {
+      assertNonEmpty(objectType.id, "target object type id")
+      return condition("target.objectTypeId", objectType.id)
+    },
+    id: {
+      eq(value) {
+        assertNonEmpty(value, "target object id")
+        return condition("target.primaryId", value)
+      },
+    },
+  }
+}
+
+function createPredicateContext(selector: EventSelectorSpec): RuntimeEventSchedulePredicateContext {
+  if (selector.topic === "objects") {
+    return { object: createPredicateSubject("event.object") }
+  }
+
+  if (selector.topic === "links") {
+    return {
+      link: createPredicateSubject("event.link"),
+      target: createTargetPredicateSubject(),
+    }
+  }
+
+  return {}
+}
+
+function assertEventSource(source: EventSelectorSpec): void {
+  if (!source.types || source.types.length === 0) {
+    throw new ScheduleValidationError(
+      "Schedule event source must select an event operation, e.g. .created(), .updated(), or .succeeded()."
+    )
+  }
+
+  switch (source.topic) {
+    case "objects":
+      assertNonEmpty(source.objectTypeId ?? "", "event source objectTypeId")
+      return
+    case "links":
+      assertNonEmpty(source.objectTypeId ?? "", "event source objectTypeId")
+      assertNonEmpty(source.linkId ?? "", "event source linkId")
+      return
+    case "rules":
+      assertNonEmpty(source.ruleId ?? "", "event source ruleId")
+      return
+    case "actions":
+      assertNonEmpty(source.actionId ?? "", "event source actionId")
+      return
+    case "datasets":
+      assertNonEmpty(source.datasetId ?? "", "event source datasetId")
+      return
+    case "syncs":
+      assertNonEmpty(source.syncId ?? "", "event source syncId")
+      return
+    case "pipelines":
+      assertNonEmpty(source.pipelineId ?? "", "event source pipelineId")
+      return
+    default:
+      throw new ScheduleValidationError(
+        "Schedule event source must select object, link, rule, action, dataset, sync, or pipeline events."
+      )
+  }
+}
+
+/** Define an inert, reusable policy describing when work should run. */
+export function defineSchedule<const TId extends string>(id: TId): ScheduleBuilder<TId>
+export function defineSchedule(id: string): ScheduleBuilder<string> {
+  assertNonEmpty(id, "id")
+
+  return {
+    cron(expression, options): CronScheduleDefinition {
+      assertNonEmpty(expression, "cron expression")
+      createCronMatcher(expression)
+
+      if (options?.timezone !== undefined) validateTimezone(options.timezone)
+
+      return {
+        kind: "schedule",
+        id,
+        trigger: {
+          type: "cron",
+          expression,
+          ...(options?.timezone !== undefined ? { timezone: options.timezone } : {}),
+        },
+      }
+    },
+    on(selector: EventSelectorSpec): unknown {
+      const source = eventSelectorSpec(selector)
+      assertEventSource(source)
+
+      const base = {
+        kind: "schedule" as const,
+        id,
+        trigger: {
+          type: "event" as const,
+          source,
+        },
+      }
+
+      if (source.topic !== "objects" && source.topic !== "links") {
+        return base satisfies EventScheduleDefinition
+      }
+
+      Object.defineProperty(base, "where", {
+        enumerable: false,
+        value(callback: (event: RuntimeEventSchedulePredicateContext) => EventScheduleCondition) {
+          const condition = callback(createPredicateContext(source))
+          if (!condition || condition.kind !== "becomesTrue") {
+            throw new ScheduleValidationError(
+              "Schedule condition must be built from the event DSL."
+            )
+          }
+          assertPredicateShape(condition.predicate, {
+            subject: "Schedule",
+            createError: (message) => new ScheduleValidationError(message),
+          })
+
+          return {
+            ...base,
+            trigger: {
+              ...base.trigger,
+              condition,
+            },
+          } satisfies EventScheduleDefinition
+        },
+      })
+
+      return base
+    },
+  } as ScheduleBuilder<string>
+}

package/src/schedules/cron.ts

@@ -0,0 +1,166 @@
+import { CronValidationError } from "./errors"
+
+export interface CronFieldMatcher {
+  readonly isAny: boolean
+  readonly values: ReadonlySet<number> | null
+  matches(value: number): boolean
+}
+
+function parseInteger(input: string, fieldName: string): number {
+  if (!/^\d+$/.test(input)) {
+    throw new CronValidationError(`Invalid ${fieldName}: '${input}'.`)
+  }
+
+  return Number.parseInt(input, 10)
+}
+
+export function createCronFieldMatcher(params: {
+  field: string
+  min: number
+  max: number
+  fieldName: string
+  normalize?: (value: number) => number
+}): CronFieldMatcher {
+  const { field, min, max, fieldName } = params
+  const normalize = params.normalize ?? ((value: number) => value)
+  const input = field.trim()
+
+  if (!input) {
+    throw new CronValidationError(`Empty cron ${fieldName} field.`)
+  }
+
+  if (input === "*") {
+    return {
+      isAny: true,
+      values: null,
+      matches: () => true,
+    }
+  }
+
+  const allowed = new Set<number>()
+  const segments = input.split(",")
+
+  for (const segment of segments) {
+    if (!segment) {
+      throw new CronValidationError(`Invalid cron ${fieldName} field: '${input}'.`)
+    }
+
+    const stepParts = segment.split("/")
+    if (stepParts.length > 2) {
+      throw new CronValidationError(`Invalid cron ${fieldName} segment: '${segment}'.`)
+    }
+
+    const base = stepParts[0]
+    const step =
+      stepParts[1] === undefined
+        ? 1
+        : parseInteger(stepParts[1], `cron ${fieldName} step for '${segment}'`)
+
+    if (step <= 0) {
+      throw new CronValidationError(`Cron ${fieldName} step must be > 0 in segment '${segment}'.`)
+    }
+
+    let rangeStart: number
+    let rangeEnd: number
+
+    if (base === "*") {
+      rangeStart = min
+      rangeEnd = max
+    } else if (base.includes("-")) {
+      const [rawStart, rawEnd] = base.split("-")
+      if (!rawStart || !rawEnd) {
+        throw new CronValidationError(`Invalid cron ${fieldName} range: '${base}'.`)
+      }
+
+      rangeStart = parseInteger(rawStart, `cron ${fieldName} range start for '${base}'`)
+      rangeEnd = parseInteger(rawEnd, `cron ${fieldName} range end for '${base}'`)
+    } else {
+      const value = parseInteger(base, `cron ${fieldName} value '${base}'`)
+      rangeStart = value
+      rangeEnd = value
+    }
+
+    if (rangeStart > rangeEnd) {
+      throw new CronValidationError(
+        `Cron ${fieldName} range start must be <= end in segment '${segment}'.`
+      )
+    }
+
+    for (let value = rangeStart; value <= rangeEnd; value += step) {
+      const normalized = normalize(value)
+      if (normalized < min || normalized > max) {
+        throw new CronValidationError(
+          `Cron ${fieldName} value ${value} is outside range ${min}-${max}.`
+        )
+      }
+      allowed.add(normalized)
+    }
+  }
+
+  return {
+    isAny: false,
+    values: allowed,
+    matches(value: number) {
+      const normalized = normalize(value)
+      return allowed.has(normalized)
+    },
+  }
+}
+
+export function createCronMatcher(expression: string): (now: Date) => boolean {
+  const parts = expression.trim().split(/\s+/)
+  if (parts.length !== 5) {
+    throw new CronValidationError(
+      `Invalid cron expression '${expression}'. Expected 5 fields (minute hour day month weekday).`
+    )
+  }
+
+  const [minuteField, hourField, dayOfMonthField, monthField, dayOfWeekField] = parts
+
+  const minute = createCronFieldMatcher({
+    field: minuteField,
+    min: 0,
+    max: 59,
+    fieldName: "minute",
+  })
+  const hour = createCronFieldMatcher({
+    field: hourField,
+    min: 0,
+    max: 23,
+    fieldName: "hour",
+  })
+  const dayOfMonth = createCronFieldMatcher({
+    field: dayOfMonthField,
+    min: 1,
+    max: 31,
+    fieldName: "day-of-month",
+  })
+  const month = createCronFieldMatcher({
+    field: monthField,
+    min: 1,
+    max: 12,
+    fieldName: "month",
+  })
+  const dayOfWeek = createCronFieldMatcher({
+    field: dayOfWeekField,
+    min: 0,
+    max: 6,
+    fieldName: "day-of-week",
+    normalize: (value) => (value === 7 ? 0 : value),
+  })
+
+  return (now: Date) => {
+    if (!minute.matches(now.getMinutes())) return false
+    if (!hour.matches(now.getHours())) return false
+    if (!month.matches(now.getMonth() + 1)) return false
+
+    const dayOfMonthMatches = dayOfMonth.matches(now.getDate())
+    const dayOfWeekMatches = dayOfWeek.matches(now.getDay())
+    const dayMatches =
+      dayOfMonth.isAny || dayOfWeek.isAny
+        ? dayOfMonthMatches && dayOfWeekMatches
+        : dayOfMonthMatches || dayOfWeekMatches
+
+    return dayMatches
+  }
+}

package/src/schedules/errors.ts

@@ -0,0 +1,7 @@
+export class ScheduleValidationError extends Error {
+  readonly name = "ScheduleValidationError"
+}
+
+export class CronValidationError extends Error {
+  readonly name = "CronValidationError"
+}

package/src/schedules/index.ts

@@ -0,0 +1,44 @@
+export { defineSchedule } from "./builders"
+export type { CronFieldMatcher } from "./cron"
+export { createCronFieldMatcher, createCronMatcher } from "./cron"
+export { CronValidationError, ScheduleValidationError } from "./errors"
+export { nextCronOccurrence } from "./next-occurrence"
+export type {
+  EventScheduleEvaluationResult,
+  RuntimeEventScheduleContext,
+  RuntimeEventScheduleDefinition,
+} from "./runtime"
+export {
+  buildEventScheduleContext,
+  evaluateEventSchedule,
+  eventScheduleSubscribedEventTypes,
+} from "./runtime"
+export type {
+  CronScheduleBuilder,
+  CronScheduleDefinition,
+  CronScheduleTriggerDefinition,
+  EventScheduleBuilder,
+  EventScheduleCondition,
+  EventScheduleConditionFor,
+  EventScheduleConditionScope,
+  EventScheduleDefinition,
+  EventSchedulePredicateContext,
+  EventSchedulePropertyPredicateBuilder,
+  EventScheduleSourceBuilder,
+  EventScheduleTargetPredicateSubject,
+  EventScheduleTriggerDefinition,
+  EventScheduleWhereBuilder,
+  InferScheduleEvent,
+  ScheduleBuilder,
+  ScheduleDefinition,
+  ScheduleDefinitionForEvent,
+  ScheduleReference,
+  ScheduleTriggerDefinition,
+} from "./types"
+export { isScheduleReference } from "./types"
+export type { ValidateSchedulesAtStartupOptions } from "./validation"
+export {
+  assertScheduleDefinition,
+  isScheduleDefinition,
+  validateSchedulesAtStartup,
+} from "./validation"

package/src/schedules/next-occurrence.ts

@@ -0,0 +1,217 @@
+import { type CronFieldMatcher, createCronFieldMatcher } from "./cron"
+import { CronValidationError } from "./errors"
+
+const MAX_SEARCH_MS = 4 * 365.25 * 24 * 60 * 60 * 1000 // ~4 years
+
+interface LocalComponents {
+  minute: number
+  hour: number
+  dayOfMonth: number
+  month: number // 1-based
+  dayOfWeek: number // 0=Sunday
+}
+
+// Intl.DateTimeFormat construction is expensive (~30-100µs each); the search
+// loop in nextCronOccurrence calls getLocalComponents many times for sparse
+// crons, so we cache one formatter per timezone for the lifetime of the process.
+const timezoneFormatterCache = new Map<string, Intl.DateTimeFormat>()
+
+function getTimezoneFormatter(timezone: string): Intl.DateTimeFormat {
+  let formatter = timezoneFormatterCache.get(timezone)
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat("en-US", {
+      timeZone: timezone,
+      year: "numeric",
+      month: "numeric",
+      day: "numeric",
+      hour: "numeric",
+      minute: "numeric",
+      weekday: "short",
+      hour12: false,
+    })
+    timezoneFormatterCache.set(timezone, formatter)
+  }
+  return formatter
+}
+
+function getLocalComponents(date: Date, timezone: string | undefined): LocalComponents {
+  if (timezone === undefined) {
+    return {
+      minute: date.getUTCMinutes(),
+      hour: date.getUTCHours(),
+      dayOfMonth: date.getUTCDate(),
+      month: date.getUTCMonth() + 1,
+      dayOfWeek: date.getUTCDay(),
+    }
+  }
+
+  const formatter = getTimezoneFormatter(timezone)
+  const parts = formatter.formatToParts(date)
+  const get = (type: Intl.DateTimeFormatPartTypes): string => {
+    const part = parts.find((p) => p.type === type)
+    if (!part) throw new CronValidationError(`Failed to extract ${type} for timezone ${timezone}.`)
+    return part.value
+  }
+
+  const weekdayStr = get("weekday")
+  const weekdayMap: Record<string, number> = {
+    Sun: 0,
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6,
+  }
+
+  return {
+    minute: Number.parseInt(get("minute"), 10),
+    hour: Number.parseInt(get("hour"), 10) % 24,
+    dayOfMonth: Number.parseInt(get("day"), 10),
+    month: Number.parseInt(get("month"), 10),
+    dayOfWeek: weekdayMap[weekdayStr] ?? 0,
+  }
+}
+
+function matchesDay(
+  dayOfMonth: CronFieldMatcher,
+  dayOfWeek: CronFieldMatcher,
+  comp: LocalComponents
+): boolean {
+  const domMatches = dayOfMonth.matches(comp.dayOfMonth)
+  const dowMatches = dayOfWeek.matches(comp.dayOfWeek)
+
+  if (dayOfMonth.isAny || dayOfWeek.isAny) {
+    return domMatches && dowMatches
+  }
+  return domMatches || dowMatches
+}
+
+/**
+ * Compute the next occurrence of a cron expression after `after`.
+ *
+ * The returned Date is always in UTC. When `timezone` is provided, the cron
+ * fields are evaluated against wall-clock time in that timezone.
+ *
+ * The current minute is never returned — the earliest possible result is
+ * `after` rounded up to the next whole minute.
+ */
+export function nextCronOccurrence(expression: string, after: Date, timezone?: string): Date {
+  const parts = expression.trim().split(/\s+/)
+  if (parts.length !== 5) {
+    throw new CronValidationError(
+      `Invalid cron expression '${expression}'. Expected 5 fields (minute hour day month weekday).`
+    )
+  }
+
+  const [minuteField, hourField, dayOfMonthField, monthField, dayOfWeekField] = parts
+
+  const minuteMatcher = createCronFieldMatcher({
+    field: minuteField,
+    min: 0,
+    max: 59,
+    fieldName: "minute",
+  })
+  const hourMatcher = createCronFieldMatcher({
+    field: hourField,
+    min: 0,
+    max: 23,
+    fieldName: "hour",
+  })
+  const dayOfMonthMatcher = createCronFieldMatcher({
+    field: dayOfMonthField,
+    min: 1,
+    max: 31,
+    fieldName: "day-of-month",
+  })
+  const monthMatcher = createCronFieldMatcher({
+    field: monthField,
+    min: 1,
+    max: 12,
+    fieldName: "month",
+  })
+  const dayOfWeekMatcher = createCronFieldMatcher({
+    field: dayOfWeekField,
+    min: 0,
+    max: 6,
+    fieldName: "day-of-week",
+    normalize: (value) => (value === 7 ? 0 : value),
+  })
+
+  // Start from the next whole minute after `after`
+  const startMs = after.getTime()
+  let candidateMs = Math.ceil(startMs / 60_000) * 60_000
+  if (candidateMs <= startMs) candidateMs += 60_000
+
+  const limitMs = startMs + MAX_SEARCH_MS
+
+  while (candidateMs <= limitMs) {
+    const candidate = new Date(candidateMs)
+    const comp = getLocalComponents(candidate, timezone)
+
+    // Month check — skip ahead if no match
+    if (!monthMatcher.matches(comp.month)) {
+      if (timezone === undefined) {
+        const next = findNextMatchingMonth(candidate, monthMatcher)
+        candidateMs = next.getTime()
+      } else {
+        // Skip to next local day boundary, then continue
+        candidateMs += ((24 - comp.hour) * 60 - comp.minute) * 60_000
+      }
+      continue
+    }
+
+    // Day check — skip ahead if no match
+    if (!matchesDay(dayOfMonthMatcher, dayOfWeekMatcher, comp)) {
+      if (timezone === undefined) {
+        const next = new Date(candidateMs)
+        next.setUTCDate(next.getUTCDate() + 1)
+        next.setUTCHours(0, 0, 0, 0)
+        candidateMs = next.getTime()
+      } else {
+        // Skip to next local day boundary
+        candidateMs += ((24 - comp.hour) * 60 - comp.minute) * 60_000
+      }
+      continue
+    }
+
+    // Hour check — skip ahead if no match
+    if (!hourMatcher.matches(comp.hour)) {
+      if (timezone === undefined) {
+        const next = new Date(candidateMs)
+        next.setUTCHours(next.getUTCHours() + 1, 0, 0, 0)
+        candidateMs = next.getTime()
+      } else {
+        // Skip to next local hour boundary
+        candidateMs += (60 - comp.minute) * 60_000
+      }
+      continue
+    }
+
+    // Minute check
+    if (!minuteMatcher.matches(comp.minute)) {
+      candidateMs += 60_000
+      continue
+    }
+
+    return candidate
+  }
+
+  throw new CronValidationError(`No matching occurrence found for '${expression}' within 4 years.`)
+}
+
+function findNextMatchingMonth(current: Date, monthMatcher: CronFieldMatcher): Date {
+  const d = new Date(current)
+  d.setUTCDate(1)
+  d.setUTCHours(0, 0, 0, 0)
+  d.setUTCMonth(d.getUTCMonth() + 1)
+
+  for (let i = 0; i < 48; i++) {
+    if (monthMatcher.matches(d.getUTCMonth() + 1)) {
+      return d
+    }
+    d.setUTCMonth(d.getUTCMonth() + 1)
+  }
+
+  return d
+}