@manablox/workflows 0.2.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@manablox/workflows",
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "@manablox/core": "0.2.0",
+    "@manablox/db": "0.2.0",
+    "nodemailer": "^10.0.0",
+    "web-push": "^3.6.7"
+  },
+  "devDependencies": {
+    "@manablox/config-typescript": "0.0.0",
+    "@manablox/fields": "0.2.0",
+    "@manablox/services": "0.2.0",
+    "@types/node": "^26.4.1",
+    "@types/nodemailer": "^8.0.1",
+    "@types/web-push": "^3.6.4",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/conditions.ts

@@ -0,0 +1,88 @@
+import type {
+  WorkflowConditionRule,
+  WorkflowConditionStep,
+  WorkflowRunContext,
+} from '@manablox/core';
+import { render, resolvePath, stringify } from './template.js';
+
+const isEmpty = (value: unknown): boolean =>
+  value === null ||
+  value === undefined ||
+  value === '' ||
+  (Array.isArray(value) && value.length === 0) ||
+  (typeof value === 'object' && !Array.isArray(value) && Object.keys(value as object).length === 0);
+
+const asNumber = (value: unknown): number | null => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string' && value.trim() !== '' && !Number.isNaN(Number(value))) {
+    return Number(value);
+  }
+  return null;
+};
+
+/** Loose equality across the types a field can hold: `"true"` matches `true`, `"3"` matches `3`. */
+const same = (actual: unknown, expected: string): boolean => {
+  if (typeof actual === 'string') return actual === expected;
+  if (typeof actual === 'number' || typeof actual === 'boolean') return String(actual) === expected;
+  if (actual === null || actual === undefined) return expected === '' || expected === 'null';
+  return stringify(actual) === expected;
+};
+
+/** `changed` compares the path under `content` with the same path under `previous`. */
+function previousValue(context: WorkflowRunContext, field: string): unknown {
+  if (!field.startsWith('content')) return undefined;
+  const rest = field.slice('content'.length);
+  return resolvePath(context.previous, rest.replace(/^\./, ''));
+}
+
+export function evaluateRule(rule: WorkflowConditionRule, context: WorkflowRunContext): boolean {
+  const actual = resolvePath(context, rule.field);
+  // The expected side may itself be a template, so a rule can compare two paths.
+  const expected = render(rule.value ?? '', context);
+
+  switch (rule.operator) {
+    case 'equals':
+      return same(actual, expected);
+    case 'notEquals':
+      return !same(actual, expected);
+    case 'contains':
+      return Array.isArray(actual)
+        ? actual.some((entry) => same(entry, expected))
+        : stringify(actual).toLowerCase().includes(expected.toLowerCase());
+    case 'notContains':
+      return Array.isArray(actual)
+        ? !actual.some((entry) => same(entry, expected))
+        : !stringify(actual).toLowerCase().includes(expected.toLowerCase());
+    case 'startsWith':
+      return stringify(actual).toLowerCase().startsWith(expected.toLowerCase());
+    case 'isEmpty':
+      return isEmpty(actual);
+    case 'isNotEmpty':
+      return !isEmpty(actual);
+    case 'greaterThan': {
+      const a = asNumber(actual);
+      const b = asNumber(expected);
+      return a !== null && b !== null ? a > b : stringify(actual) > expected;
+    }
+    case 'lessThan': {
+      const a = asNumber(actual);
+      const b = asNumber(expected);
+      return a !== null && b !== null ? a < b : stringify(actual) < expected;
+    }
+    case 'changed': {
+      // Without a previous row every field is new, which is what "changed" means then.
+      if (!context.previous) return true;
+      return stringify(actual) !== stringify(previousValue(context, rule.field));
+    }
+  }
+}
+
+/** Whether the run may continue past this step. */
+export function evaluateCondition(
+  step: Pick<WorkflowConditionStep, 'match' | 'rules'>,
+  context: WorkflowRunContext,
+): boolean {
+  if (step.rules.length === 0) return true;
+  const results = step.rules.map((rule) => evaluateRule(rule, context));
+  return step.match === 'any' ? results.some(Boolean) : results.every(Boolean);
+}

package/src/cron.ts

@@ -0,0 +1,181 @@
+/**
+ * Five-field cron — `minute hour day-of-month month day-of-week` — matched against a
+ * wall-clock in a named timezone. Only matching is needed: the scheduler wakes every
+ * minute and asks "is now a match?", so there is no next-run arithmetic to get wrong.
+ */
+
+export interface CronSpec {
+  minute: Set<number>;
+  hour: Set<number>;
+  dayOfMonth: Set<number>;
+  month: Set<number>;
+  dayOfWeek: Set<number>;
+  /** `*` in the day-of-month field; decides how the two day fields combine. */
+  anyDayOfMonth: boolean;
+  anyDayOfWeek: boolean;
+}
+
+const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+const DAYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+
+interface FieldSpec {
+  min: number;
+  max: number;
+  names?: string[];
+  /** Day-of-week accepts 7 for Sunday as well as 0. */
+  alias?: Record<number, number>;
+}
+
+const FIELDS: FieldSpec[] = [
+  { min: 0, max: 59 },
+  { min: 0, max: 23 },
+  { min: 1, max: 31 },
+  { min: 1, max: 12, names: MONTHS },
+  { min: 0, max: 6, names: DAYS, alias: { 7: 0 } },
+];
+
+function parseValue(raw: string, field: FieldSpec): number | null {
+  const lower = raw.toLowerCase();
+  if (field.names) {
+    const index = field.names.indexOf(lower);
+    if (index !== -1) return field.min + index;
+  }
+  if (!/^\d+$/.test(raw)) return null;
+  let value = Number(raw);
+  if (field.alias && value in field.alias) value = field.alias[value] as number;
+  if (value < field.min || value > field.max) return null;
+  return value;
+}
+
+/** One comma-separated part: `*`, `n`, `a-b`, `*​/s`, `a-b/s`, `a/s`. */
+function parsePart(part: string, field: FieldSpec, into: Set<number>): boolean {
+  const [rangePart, stepPart] = part.split('/');
+  if (rangePart === undefined || stepPart === '') return false;
+
+  let step = 1;
+  if (stepPart !== undefined) {
+    if (!/^\d+$/.test(stepPart)) return false;
+    step = Number(stepPart);
+    if (step < 1) return false;
+  }
+
+  let from: number;
+  let to: number;
+  if (rangePart === '*') {
+    from = field.min;
+    to = field.max;
+  } else if (rangePart.includes('-')) {
+    const [a, b] = rangePart.split('-');
+    const start = a === undefined ? null : parseValue(a, field);
+    const end = b === undefined ? null : parseValue(b, field);
+    if (start === null || end === null || end < start) return false;
+    from = start;
+    to = end;
+  } else {
+    const value = parseValue(rangePart, field);
+    if (value === null) return false;
+    from = value;
+    // `5/10` means "from 5 on, every 10"; a bare `5` is just 5.
+    to = stepPart !== undefined ? field.max : value;
+  }
+
+  for (let value = from; value <= to; value += step) into.add(value);
+  return true;
+}
+
+export function parseCron(expression: string): CronSpec | null {
+  const fields = expression.trim().split(/\s+/);
+  if (fields.length !== 5) return null;
+
+  const sets: Set<number>[] = [];
+  for (const [index, raw] of fields.entries()) {
+    const field = FIELDS[index] as FieldSpec;
+    const set = new Set<number>();
+    for (const part of raw.split(',')) {
+      if (!part || !parsePart(part, field, set)) return null;
+    }
+    sets.push(set);
+  }
+
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = sets as [
+    Set<number>,
+    Set<number>,
+    Set<number>,
+    Set<number>,
+    Set<number>,
+  ];
+  return {
+    minute,
+    hour,
+    dayOfMonth,
+    month,
+    dayOfWeek,
+    anyDayOfMonth: fields[2] === '*',
+    anyDayOfWeek: fields[4] === '*',
+  };
+}
+
+export function isValidCron(expression: string): boolean {
+  return parseCron(expression) !== null;
+}
+
+export function isValidTimezone(timezone: string): boolean {
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface WallClock {
+  minute: number;
+  hour: number;
+  dayOfMonth: number;
+  month: number;
+  dayOfWeek: number;
+}
+
+/** The wall-clock reading of an instant in a timezone. */
+export function wallClock(date: Date, timezone: string): WallClock {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone: timezone,
+    hourCycle: 'h23',
+    minute: 'numeric',
+    hour: 'numeric',
+    day: 'numeric',
+    month: 'numeric',
+    weekday: 'short',
+  }).formatToParts(date);
+  const read = (type: string) => parts.find((part) => part.type === type)?.value ?? '';
+  return {
+    minute: Number(read('minute')),
+    hour: Number(read('hour')) % 24,
+    dayOfMonth: Number(read('day')),
+    month: Number(read('month')),
+    dayOfWeek: DAYS.indexOf(read('weekday').toLowerCase().slice(0, 3)),
+  };
+}
+
+/**
+ * Whether the minute containing `date` matches. As in Vixie cron, when both day fields
+ * are restricted a match on either is enough.
+ */
+export function cronMatches(spec: CronSpec, date: Date, timezone: string): boolean {
+  const clock = wallClock(date, timezone);
+  if (!spec.minute.has(clock.minute)) return false;
+  if (!spec.hour.has(clock.hour)) return false;
+  if (!spec.month.has(clock.month)) return false;
+
+  const domMatch = spec.dayOfMonth.has(clock.dayOfMonth);
+  const dowMatch = spec.dayOfWeek.has(clock.dayOfWeek);
+  if (spec.anyDayOfMonth && spec.anyDayOfWeek) return true;
+  if (spec.anyDayOfMonth) return dowMatch;
+  if (spec.anyDayOfWeek) return domMatch;
+  return domMatch || dowMatch;
+}
+
+/** The start of the minute an instant falls in — the unit the scheduler claims. */
+export function floorToMinute(date: Date): Date {
+  return new Date(Math.floor(date.getTime() / 60_000) * 60_000);
+}