bazis 0.133.0 → 0.134.0

package/library/workflow/cron.ts

@@ -1,4 +1,4 @@
-/** A parsed five-field cron expression, evaluated in UTC. */
+/** A parsed five-field cron expression, evaluated in UTC or in a time zone. */
 export interface CronSchedule {
   /** Whether the expression fires at this minute. */
   matches(date: Date): boolean;
@@ -15,14 +15,53 @@ const FIELDS = [
 ] as const;
 
 const MINUTE = 60_000;
+const DAY_MINUTES = 24 * 60;
+/** Clock changes are never longer than this: a day is skipped up to here, the rest hour by hour. */
+const CLOCK_CHANGE_MINUTES = 3 * 60;
+
+const formats = new Map<string, Intl.DateTimeFormat>();
+
+function formatOf(timezone: string): Intl.DateTimeFormat {
+  let format = formats.get(timezone);
+  if (format === undefined) {
+    format = new Intl.DateTimeFormat("en-US", { timeZone: timezone, hourCycle: "h23", year: "numeric", month: "numeric", day: "numeric", hour: "numeric", minute: "numeric", second: "numeric" });
+    formats.set(timezone, format);
+  }
+  return format;
+}
+
+/** Whether this is an IANA time zone: `Europe/Moscow`, `UTC`. */
+export function isTimeZone(value: unknown): value is string {
+  if (typeof value !== "string" || value === "") return false;
+  try {
+    formatOf(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** How far the clocks of the zone are ahead of UTC at this moment, in milliseconds. */
+function offsetOf(timezone: string | undefined, time: number): number {
+  if (timezone === undefined) return 0;
+  const parts: Record<string, number> = {};
+  for (const { type, value } of formatOf(timezone).formatToParts(time)) parts[type] = Number(value);
+  return Date.UTC(parts.year!, parts.month! - 1, parts.day!, parts.hour!, parts.minute!, parts.second!) - Math.floor(time / 1000) * 1000;
+}
 
 /**
  * Parses `minute hour day-of-month month day-of-week` with `*`, numbers,
  * ranges `a-b`, steps `/n` and lists `a,b`. Day of week 0 and 7 are Sunday.
  * When both day fields are restricted, either one matching is enough, as in
- * classic cron. Returns `undefined` for an invalid expression.
+ * classic cron. Returns `undefined` for an invalid expression or time zone.
+ *
+ * With a `timezone` the fields are read on its clocks. A schedule with a set
+ * hour fires once a day whatever the clocks do: a time skipped when they go
+ * forward fires right after the change, a time repeated when they go back fires
+ * the first time only. A schedule with `*` in the hour simply follows the clocks.
  */
-export function parseCron(expression: string): CronSchedule | undefined {
+export function parseCron(expression: string, timezone?: string): CronSchedule | undefined {
+  if (timezone !== undefined && !isTimeZone(timezone)) return undefined;
   const parts = expression.trim().split(/\s+/);
   if (parts.length !== 5) return undefined;
   const sets: Set<number>[] = [];
@@ -35,34 +74,74 @@ export function parseCron(expression: string): CronSchedule | undefined {
   if (weekdays.has(7)) weekdays.add(0);
   const daysRestricted = parts[2] !== "*";
   const weekdaysRestricted = parts[4] !== "*";
+  const hourSet = parts[1] !== "*";
 
-  const dayMatches = (date: Date): boolean => {
-    const day = days.has(date.getUTCDate());
-    const weekday = weekdays.has(date.getUTCDay());
-    return daysRestricted && weekdaysRestricted ? day || weekday : day && weekday;
+  /** The date part of a time on the clocks of the zone, kept in the UTC fields of a `Date`. */
+  const dayMatches = (clock: Date): boolean => {
+    const day = days.has(clock.getUTCDate());
+    const weekday = weekdays.has(clock.getUTCDay());
+    return months.has(clock.getUTCMonth() + 1) && (daysRestricted && weekdaysRestricted ? day || weekday : day && weekday);
   };
 
-  const matches = (date: Date): boolean =>
-    minutes.has(date.getUTCMinutes()) && hours.has(date.getUTCHours()) && months.has(date.getUTCMonth() + 1) && dayMatches(date);
+  const clockMatches = (clock: Date): boolean => minutes.has(clock.getUTCMinutes()) && hours.has(clock.getUTCHours()) && dayMatches(clock);
+
+  /** Whether the clocks show this time for the second time: they went back a moment ago. */
+  const repeated = (time: number, offset: number): boolean => {
+    const before = offsetOf(timezone, time - CLOCK_CHANGE_MINUTES * MINUTE);
+    if (before <= offset) return false;
+    const first = time - (before - offset);
+    return offsetOf(timezone, first) === before;
+  };
+
+  /** When the clocks jumped forward between two moments, if a firing fell into the skipped time. */
+  const skippedFiring = (from: number, to: number): number | undefined => {
+    const before = offsetOf(timezone, from);
+    const after = offsetOf(timezone, to);
+    if (after <= before) return undefined;
+    let low = from;
+    let high = to;
+    while (high - low > MINUTE) {
+      const middle = Math.floor((low + high) / 2 / MINUTE) * MINUTE;
+      if (offsetOf(timezone, middle) === before) low = middle;
+      else high = middle;
+    }
+    for (let clock = high + before; clock < high + after; clock += MINUTE) {
+      if (clockMatches(new Date(clock))) return high;
+    }
+    return undefined;
+  };
 
   return {
-    matches,
+    matches(date: Date): boolean {
+      const offset = offsetOf(timezone, date.getTime());
+      if (!clockMatches(new Date(date.getTime() + offset))) return false;
+      return !(hourSet && timezone !== undefined && repeated(Math.floor(date.getTime() / MINUTE) * MINUTE, offset));
+    },
     next(after: Date): Date | undefined {
-      const limit = after.getTime() + 5 * 366 * 24 * 60 * MINUTE;
-      const date = new Date(Math.floor(after.getTime() / MINUTE) * MINUTE + MINUTE);
-      while (date.getTime() <= limit) {
-        if (!months.has(date.getUTCMonth() + 1)) {
-          date.setUTCMonth(date.getUTCMonth() + 1, 1);
-          date.setUTCHours(0, 0, 0, 0);
-        } else if (!dayMatches(date)) {
-          date.setUTCDate(date.getUTCDate() + 1);
-          date.setUTCHours(0, 0, 0, 0);
-        } else if (!hours.has(date.getUTCHours())) {
-          date.setUTCHours(date.getUTCHours() + 1, 0, 0, 0);
-        } else if (!minutes.has(date.getUTCMinutes())) {
-          date.setTime(date.getTime() + MINUTE);
+      const limit = after.getTime() + 5 * 366 * DAY_MINUTES * MINUTE;
+      let time = Math.floor(after.getTime() / MINUTE) * MINUTE + MINUTE;
+      let previous = time - MINUTE;
+      while (time <= limit) {
+        if (hourSet && timezone !== undefined) {
+          const skipped = skippedFiring(previous, time);
+          if (skipped !== undefined) return new Date(skipped);
+        }
+        previous = time;
+        const offset = offsetOf(timezone, time);
+        const clock = new Date(time + offset);
+        const minutesOfDay = clock.getUTCHours() * 60 + clock.getUTCMinutes();
+        if (!dayMatches(clock)) {
+          // Close to midnight hour by hour: the day may be shorter than its clocks say.
+          const left = DAY_MINUTES - minutesOfDay;
+          time += (timezone === undefined ? left : left > CLOCK_CHANGE_MINUTES ? left - CLOCK_CHANGE_MINUTES : 60 - clock.getUTCMinutes()) * MINUTE;
+        } else if (!hours.has(clock.getUTCHours())) {
+          time += (60 - clock.getUTCMinutes()) * MINUTE;
+        } else if (!minutes.has(clock.getUTCMinutes())) {
+          time += MINUTE;
+        } else if (hourSet && timezone !== undefined && repeated(time, offset)) {
+          time += MINUTE;
         } else {
-          return date;
+          return new Date(time);
         }
       }
       return undefined;

package/library/workflow/index.ts

@@ -20,7 +20,7 @@ export {
   type ProcessNode,
   type ProcessSettings,
 } from "./ProcessDocument";
-export { NODE_KINDS, nodeKindOf, ISO_DURATION, MAX_ITERATIONS, MAX_LOOP_PARALLEL, PROCESS_KEY, type JsonSchema, type NodeKindDefinition, type NodeRole } from "./nodeKinds";
+export { NODE_KINDS, nodeKindOf, ISO_DURATION, MAX_ITERATIONS, MAX_LOOP_PARALLEL, PROCESS_KEY, ISO_MOMENT, type JsonSchema, type NodeKindDefinition, type NodeRole } from "./nodeKinds";
 export { PROCESS_LIMITS, validateProcess, hasErrors, type ProcessIssue, type ProcessIssueCode, type ValidateProcessOptions } from "./validateProcess";
 export { DATA_PATH, DATA_PATHS, isPath, readPath, resolveInput, type InstanceData } from "./paths";
 export {
@@ -42,7 +42,7 @@ export {
 } from "./expressions";
 export { ExpressionSyntaxError, parseExpression, printExpression } from "./expressionSyntax";
 export { durationMs } from "./duration";
-export { parseCron, type CronSchedule } from "./cron";
+export { isTimeZone, parseCron, type CronSchedule } from "./cron";
 export { processToMermaid } from "./mermaid";
 export { PERSONAL_MASK, maskByMapping, maskBySchema, masksPersonal, personalPaths, personalVariables, readsPersonal } from "./masking";
 export { allTexts, checkLocalizedText, textOf, type LocalizedText } from "./localized";

package/library/workflow/nodeKinds.ts

@@ -1,4 +1,4 @@
-import { parseCron } from "./cron";
+import { isTimeZone, parseCron } from "./cron";
 import { FIELD_NAME, checkFormSpec } from "./formFields";
 import { DATA_PATH } from "./paths";
 import type { NodeKind } from "./ProcessDocument";
@@ -52,11 +52,42 @@ function first(...checks: (string | null)[]): string | null {
   return checks.find((check) => check !== null) ?? null;
 }
 
-/** Five cron fields: minute, hour, day of month, month, day of week. */
-function cron(config: Record<string, unknown>): string | null {
-  const value = config.cron;
-  if (typeof value !== "string") return "config.cron is required";
-  return parseCron(value) === undefined ? "config.cron must be five valid fields: minute hour day month weekday (UTC)" : null;
+/** A moment with its zone: `2026-11-01T09:00:00+03:00`. */
+export const ISO_MOMENT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})$/;
+
+function moment(config: Record<string, unknown>, key: string): string | null {
+  const value = config[key];
+  if (value === undefined) return null;
+  return typeof value === "string" && ISO_MOMENT.test(value) && !Number.isNaN(Date.parse(value)) ? null : `config.${key} must be a moment with its zone: 2026-11-01T09:00:00+03:00`;
+}
+
+/** A scheduled start: five cron fields (minute, hour, day of month, month, day of week), where and when it runs. */
+function schedule(config: Record<string, unknown>): string | null {
+  const { cron, timezone, from, until, overlap, partitions } = config;
+  if (typeof cron !== "string") return "config.cron is required";
+  if (parseCron(cron) === undefined) return "config.cron must be five valid fields: minute hour day month weekday";
+  if (timezone !== undefined && !isTimeZone(timezone)) return "config.timezone must be an IANA time zone: Europe/Moscow";
+  const period = first(moment(config, "from"), moment(config, "until"), boolean(config, "catchUp"));
+  if (period !== null) return period;
+  if (typeof from === "string" && typeof until === "string" && Date.parse(from) >= Date.parse(until)) return "config.from must be before config.until";
+  if (overlap !== undefined && overlap !== "skip" && overlap !== "queue" && overlap !== "parallel") return "config.overlap must be skip, queue or parallel";
+  if (partitions !== undefined && partitions !== "none" && partitions !== "all") {
+    if (!Array.isArray(partitions) || partitions.length === 0 || partitions.length > 1000 || !partitions.every((item) => typeof item === "string" && item !== "" && item.length <= 200)) return "config.partitions must be none, all or a list of partitions";
+  }
+  return null;
+}
+
+/** An event start; its expressions are checked with the whole document. */
+function eventStart(config: Record<string, unknown>): string | null {
+  const { debounce } = config;
+  if (debounce !== undefined) {
+    if (typeof debounce !== "object" || debounce === null || Array.isArray(debounce)) return "config.debounce must be an object";
+    const { key } = debounce as { key?: unknown };
+    if (key === undefined) return "config.debounce.key is required";
+    const problem = string(debounce as Record<string, unknown>, "window", ISO_DURATION);
+    if (problem !== null) return problem.replace("config.", "config.debounce.");
+  }
+  return first(string(config, "event", DOTTED_KEY), string(config, "delay", ISO_DURATION, false), boolean(config, "ignoreOwn"));
 }
 
 /** A timer: either `duration` (ISO 8601) or `at`, a path to a date in instance data. */
@@ -158,8 +189,32 @@ const fields = { type: "object", properties: { fields: { type: "array", items: {
 
 export const NODE_KINDS: readonly NodeKindDefinition[] = Object.freeze([
   { kind: "manualStart", role: "start", check: none, config: object({}) },
-  { kind: "scheduleStart", role: "start", check: cron, config: object({ cron: text }, ["cron"]) },
-  { kind: "eventStart", role: "start", check: (c) => string(c, "event", DOTTED_KEY), config: object({ event: text }, ["event"]) },
+  {
+    kind: "scheduleStart",
+    role: "start",
+    check: schedule,
+    config: object({
+      cron: text,
+      timezone: { type: "string", description: "An IANA time zone; UTC by default" },
+      from: { type: "string", format: "date-time" },
+      until: { type: "string", format: "date-time" },
+      overlap: { enum: ["skip", "queue", "parallel"] },
+      catchUp: flag,
+      partitions: { description: "none, all or a list of partitions", oneOf: [{ enum: ["none", "all"] }, { type: "array", items: text }] },
+    }, ["cron"]),
+  },
+  {
+    kind: "eventStart",
+    role: "start",
+    check: eventStart,
+    config: object({
+      event: text,
+      filter: expression,
+      debounce: object({ key: expression, window: duration }, ["key", "window"]),
+      delay: duration,
+      ignoreOwn: flag,
+    }, ["event"]),
+  },
   {
     kind: "userTask",
     role: "activity",
@@ -218,7 +273,7 @@ export const NODE_KINDS: readonly NodeKindDefinition[] = Object.freeze([
     kind: "eventWait",
     role: "activity",
     check: (c) => first(string(c, "event", DOTTED_KEY), string(c, "correlation", DATA_PATH, false), string(c, "saveTo", FIELD_NAME, false)),
-    config: object({ event: text, correlation: dataPath, saveTo }, ["event"]),
+    config: object({ event: text, correlation: dataPath, saveTo, until: expression }, ["event"]),
   },
   { kind: "exclusiveGateway", role: "gateway", check: none, config: object({}) },
   { kind: "parallelGateway", role: "gateway", check: none, config: object({}) },

package/library/workflow/paths.ts

@@ -10,7 +10,7 @@ export interface InstanceData {
   readonly nodes: Readonly<Record<string, unknown>>;
   /** The data of the event that started or continued the process. */
   readonly event?: unknown;
-  /** How it was started: `{ via, at, actor, eventKey?, cause? }`. */
+  /** How it was started: `{ via, at, actor, eventKey?, cause?, scheduledAt? }`. */
   readonly trigger?: unknown;
   /** `{ id, processKey, version, partition, test }`. */
   readonly run?: unknown;
@@ -31,7 +31,7 @@ export const DATA_PATHS: readonly { readonly path: string; readonly description:
   { path: "$vars.<name>", description: "A variable of the process" },
   { path: "$nodes.<node>.<field>", description: "The result of a passed step" },
   { path: "$event", description: "The data of the event that started or continued the process" },
-  { path: "$trigger", description: "How it was started: { via, at, actor, eventKey?, cause? }" },
+  { path: "$trigger", description: "How it was started: { via, at, actor, eventKey?, cause?, scheduledAt? }" },
   { path: "$run", description: "This run: { id, processKey, version, partition, test }" },
   { path: "$now", description: "The engine's time" },
   { path: "$item", description: "Inside a loop body: the element of this iteration" },

package/library/workflow/validateProcess.ts

@@ -451,6 +451,18 @@ function configExpressionProblems(kind: string, config: Json, scope: ExpressionS
     const problem = checkExpression(config.over, scope);
     if (problem) out.push(`config.over: ${problem}`);
   }
+  if (kind === "eventWait" && config.until !== undefined) {
+    const problem = checkExpression(config.until, scope);
+    if (problem) out.push(`config.until: ${problem}`);
+  }
+  if (kind === "eventStart") {
+    // Before an instance exists there is only the event: nothing to read in the input, variables and steps.
+    const before: ExpressionScope = { input: new Set(), vars: new Set(), nodes: new Set(), loop: false };
+    const filter = config.filter === undefined ? null : checkExpression(config.filter, before);
+    if (filter) out.push(`config.filter: ${filter}`);
+    const debounceKey = isObject(config.debounce) ? checkExpression(config.debounce.key, before) : null;
+    if (debounceKey) out.push(`config.debounce.key: ${debounceKey}`);
+  }
   for (const key of ["at", "correlation"]) {
     if (typeof config[key] === "string") {
       const problem = checkPath(config[key], scope);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.133.0",
+  "version": "0.134.0",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",
@@ -44,6 +44,7 @@
     "./core/kernel": "./core/kernel/index.ts",
     "./core/orm": "./core/orm/index.ts",
     "./core/testing": "./core/testing/index.ts",
+    "./core/tools": "./core/tools/index.ts",
     "./core/websocket": "./core/websocket/index.ts",
     "./core/workflow": "./core/workflow/index.ts",
     "./core/workflow/testing": "./core/workflow/testing/index.ts",