@svgrid/enterprise 2.5.2 → 2.6.0

package/src/scheduling.ts

@@ -1,293 +0,0 @@
-/**
- * Scheduling - client-side, cron-driven automation for grid actions.
- *
- * Two everyday jobs that normally need a backend job runner - "email me this
- * report every weekday at 17:30" and "remind the desk at 09:00 to reconcile" -
- * are, in a long-lived data app, just a timer plus an action you already have:
- * an export (`api.exportCsv` / `@svgrid/enterprise` Excel/PDF) or an alert
- * (`toast`). This module supplies the missing middle: a pure cron matcher and a
- * small runtime that fires your callback when a schedule comes due.
- *
- * Everything here is pure and injectable (`now`), so the matching logic is
- * unit-testable without wall-clock flakiness, and the render/app layer just
- * wires `onFire` to whatever action it wants.
- *
- * ```ts
- * import { createScheduler } from '@svgrid/enterprise'
- * import { toast } from '@svgrid/grid'
- *
- * const scheduler = createScheduler({
- *   schedules: [
- *     { id: 'eod', name: 'End-of-day CSV', cron: '30 17 * * 1-5' },
- *     { id: 'standup', name: 'Stand-up reminder', cron: '0 9 * * *' },
- *   ],
- *   onFire(schedule) {
- *     if (schedule.id === 'eod') api.exportCsv({ filename: 'eod' })
- *     else toast.info(`${schedule.name}`)
- *   },
- * })
- * scheduler.start()   // stop() on teardown
- * ```
- *
- * Caveat, by design: schedules run entirely in the browser tab, so the app has
- * to be open when a schedule is due. Pair with a server job for guaranteed
- * delivery; use this for the far more common "the dashboard is always up on the
- * wall" case where a backend cron is overkill.
- */
-
-/** A field in the range [min, max] that a parsed cron sub-expression matches. */
-type CronField = { min: number; max: number; match: (n: number) => boolean }
-
-export type Schedule = {
-  /** Stable id - used to dedupe fires and to key your `onFire` switch. */
-  id: string
-  /** Human label shown in a schedules panel / toast. */
-  name?: string
-  /**
-   * Recurring trigger: a standard 5-field cron expression
-   * `"minute hour day-of-month month day-of-week"`. Ignored when `runAt` is set.
-   * Supports `*`, lists (`1,15`), ranges (`1-5`), and steps (`*​/15`, `9-17/2`).
-   * Day-of-week is `0-6` with Sunday `0` (`7` also accepted for Sunday).
-   */
-  cron?: string
-  /**
-   * One-off trigger: an ISO datetime string. Fires a single time when the
-   * wall clock reaches that minute, then never again. Takes precedence over
-   * `cron` when both are present.
-   */
-  runAt?: string
-  /** Set `false` to keep the definition but stop it firing. Default `true`. */
-  enabled?: boolean
-}
-
-const RANGES = {
-  minute: [0, 59],
-  hour: [0, 23],
-  dom: [1, 31],
-  month: [1, 12],
-  dow: [0, 6],
-} as const
-
-/** Parse one cron field (e.g. `*​/15`, `1-5`, `0,30`) into a matcher. */
-function parseField(raw: string, min: number, max: number): CronField {
-  const allowed = new Set<number>()
-  for (const part of raw.split(',')) {
-    const [rangePart, stepPart] = part.split('/')
-    const step = stepPart ? parseInt(stepPart, 10) : 1
-    if (!Number.isFinite(step) || step < 1) {
-      throw new Error(`Invalid cron step in "${raw}"`)
-    }
-    let lo: number
-    let hi: number
-    if (rangePart === '*' || rangePart === '') {
-      lo = min
-      hi = max
-    } else if (rangePart!.includes('-')) {
-      const [a, b] = rangePart!.split('-')
-      lo = parseInt(a!, 10)
-      hi = parseInt(b!, 10)
-    } else {
-      lo = parseInt(rangePart!, 10)
-      hi = lo
-    }
-    if (!Number.isFinite(lo) || !Number.isFinite(hi)) {
-      throw new Error(`Invalid cron field "${raw}"`)
-    }
-    for (let n = lo; n <= hi; n += step) {
-      if (n >= min && n <= max) allowed.add(n)
-    }
-  }
-  return { min, max, match: (n) => allowed.has(n) }
-}
-
-type ParsedCron = {
-  minute: CronField
-  hour: CronField
-  dom: CronField
-  month: CronField
-  dow: CronField
-  /** True when BOTH day-of-month and day-of-week are restricted (not `*`). */
-  domAndDowRestricted: boolean
-}
-
-/**
- * Parse a 5-field cron expression. Throws on the wrong field count or an
- * unparseable field, so a bad schedule surfaces at setup, not silently at 3am.
- */
-export function parseCron(expr: string): ParsedCron {
-  const fields = expr.trim().split(/\s+/)
-  if (fields.length !== 5) {
-    throw new Error(
-      `Cron needs 5 fields "min hour dom month dow", got ${fields.length}: "${expr}"`,
-    )
-  }
-  const [min, hour, dom, month, dow] = fields
-  // Day-of-week 7 is an alias for Sunday (0); normalize before parsing.
-  const dowNorm = dow!.replace(/7/g, '0')
-  return {
-    minute: parseField(min!, ...RANGES.minute),
-    hour: parseField(hour!, ...RANGES.hour),
-    dom: parseField(dom!, ...RANGES.dom),
-    month: parseField(month!, ...RANGES.month),
-    dow: parseField(dowNorm, ...RANGES.dow),
-    domAndDowRestricted: dom !== '*' && dow !== '*',
-  }
-}
-
-/** Whether a parsed cron matches a specific `Date` to the minute. */
-export function cronMatchesParsed(parsed: ParsedCron, date: Date): boolean {
-  if (!parsed.minute.match(date.getMinutes())) return false
-  if (!parsed.hour.match(date.getHours())) return false
-  if (!parsed.month.match(date.getMonth() + 1)) return false
-  const domOk = parsed.dom.match(date.getDate())
-  const dowOk = parsed.dow.match(date.getDay())
-  // Standard cron semantics: when both day fields are restricted the match is
-  // the UNION (fires if either matches); otherwise plain AND.
-  return parsed.domAndDowRestricted ? domOk || dowOk : domOk && dowOk
-}
-
-/** Whether a cron expression matches a `Date` to the minute. */
-export function cronMatches(expr: string, date: Date): boolean {
-  return cronMatchesParsed(parseCron(expr), date)
-}
-
-/** Two dates fall in the same wall-clock minute. */
-function sameMinute(a: Date, b: Date): boolean {
-  return (
-    a.getFullYear() === b.getFullYear() &&
-    a.getMonth() === b.getMonth() &&
-    a.getDate() === b.getDate() &&
-    a.getHours() === b.getHours() &&
-    a.getMinutes() === b.getMinutes()
-  )
-}
-
-/** Whether a schedule is due to fire during the minute containing `date`. */
-export function isScheduleDue(schedule: Schedule, date: Date): boolean {
-  if (schedule.enabled === false) return false
-  if (schedule.runAt) {
-    const at = new Date(schedule.runAt)
-    return !Number.isNaN(at.getTime()) && sameMinute(at, date)
-  }
-  if (schedule.cron) return cronMatches(schedule.cron, date)
-  return false
-}
-
-/**
- * The next `Date` (to the minute) at or after `from` that `schedule` fires,
- * or `null` if it never will again (past one-off, or no match within a year).
- * Handy for a "next run" column in a schedules panel.
- */
-export function nextRun(schedule: Schedule, from: Date): Date | null {
-  if (schedule.enabled === false) return null
-  if (schedule.runAt) {
-    const at = new Date(schedule.runAt)
-    if (Number.isNaN(at.getTime())) return null
-    // Compare at minute granularity - a runAt in the current minute is "now".
-    const floor = new Date(from)
-    floor.setSeconds(0, 0)
-    return at.getTime() >= floor.getTime() ? at : null
-  }
-  if (!schedule.cron) return null
-  const parsed = parseCron(schedule.cron)
-  const cursor = new Date(from)
-  cursor.setSeconds(0, 0)
-  // Scan minute-by-minute for up to ~366 days (527040 minutes).
-  for (let i = 0; i < 527_040; i += 1) {
-    if (cronMatchesParsed(parsed, cursor)) return new Date(cursor)
-    cursor.setMinutes(cursor.getMinutes() + 1)
-  }
-  return null
-}
-
-export type SchedulerOptions = {
-  /** The schedules to run. Read once per tick, so you may mutate the array. */
-  schedules: ReadonlyArray<Schedule>
-  /** Called when a schedule comes due. Receives the schedule + the fire time. */
-  onFire: (schedule: Schedule, firedAt: Date) => void
-  /**
-   * Clock source, injectable for tests. Default `() => new Date()`.
-   */
-  now?: () => Date
-  /**
-   * How often to check, in ms. Default 30_000 (twice a minute) so a fire is
-   * never more than ~30s late; per-minute dedupe keeps it firing once.
-   */
-  intervalMs?: number
-}
-
-export type Scheduler = {
-  /** Begin ticking. No-op if already started. */
-  start: () => void
-  /** Stop ticking and clear the timer. */
-  stop: () => void
-  /**
-   * Run one check against `at` (default now) and fire anything due. Exposed for
-   * tests and for a "run due now" button; the internal tick calls this too.
-   */
-  tick: (at?: Date) => void
-  /** Upcoming fire time per schedule id, from `at` (default now). */
-  upcoming: (at?: Date) => Array<{ id: string; at: Date | null }>
-}
-
-/**
- * A client-side scheduler: ticks on an interval, fires `onFire` for every
- * schedule due in the current minute, and guarantees at most one fire per
- * schedule per minute (and exactly one, ever, for a one-off).
- */
-export function createScheduler(options: SchedulerOptions): Scheduler {
-  const now = options.now ?? (() => new Date())
-  const intervalMs = options.intervalMs ?? 30_000
-  // Per-schedule guard: the minute-key we last fired, so a twice-a-minute tick
-  // (or a manual tick) never double-fires the same minute. One-offs are marked
-  // done so they never fire again even across minutes.
-  const lastFiredKey = new Map<string, string>()
-  const oneOffDone = new Set<string>()
-  let timer: ReturnType<typeof setInterval> | null = null
-
-  const minuteKey = (d: Date) =>
-    `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}-${d.getHours()}-${d.getMinutes()}`
-
-  function tick(at: Date = now()): void {
-    const key = minuteKey(at)
-    for (const schedule of options.schedules) {
-      if (schedule.enabled === false) continue
-      const oneOff = !!schedule.runAt
-      if (oneOff && oneOffDone.has(schedule.id)) continue
-      if (lastFiredKey.get(schedule.id) === key) continue
-      if (!isScheduleDue(schedule, at)) continue
-      lastFiredKey.set(schedule.id, key)
-      if (oneOff) oneOffDone.add(schedule.id)
-      options.onFire(schedule, at)
-    }
-  }
-
-  return {
-    start() {
-      if (timer != null) return
-      timer = setInterval(() => tick(), intervalMs)
-    },
-    stop() {
-      if (timer != null) {
-        clearInterval(timer)
-        timer = null
-      }
-    },
-    tick,
-    upcoming(at: Date = now()) {
-      return options.schedules.map((s) => ({ id: s.id, at: nextRun(s, at) }))
-    },
-  }
-}
-
-/** A few common cron expressions, for docs, presets, and pickers. */
-export const CRON_PRESETS: ReadonlyArray<{ label: string; cron: string }> = [
-  { label: 'Every minute', cron: '* * * * *' },
-  { label: 'Every 15 minutes', cron: '*/15 * * * *' },
-  { label: 'Hourly, on the hour', cron: '0 * * * *' },
-  { label: 'Every weekday at 09:00', cron: '0 9 * * 1-5' },
-  { label: 'Weekdays at 17:30', cron: '30 17 * * 1-5' },
-  { label: 'Daily at midnight', cron: '0 0 * * *' },
-  { label: 'Monday mornings at 08:00', cron: '0 8 * * 1' },
-  { label: 'First of the month at 06:00', cron: '0 6 1 * *' },
-]

package/src/schema-designer.test.ts

@@ -1,121 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import type { EntitySchema } from './schema'
-import {
-  addField,
-  blankField,
-  isSchemaValid,
-  moveField,
-  removeField,
-  sampleRows,
-  updateField,
-  validateSchema,
-} from './schema-designer'
-
-function base(): EntitySchema {
-  return {
-    name: 'customers',
-    idField: 'id',
-    fields: [
-      { field: 'id', type: 'text', primaryKey: true, readonly: true },
-      { field: 'name', type: 'text' },
-      { field: 'tier', type: 'enum', options: [{ value: 'free', label: 'Free' }] },
-    ],
-  }
-}
-
-describe('blankField / addField', () => {
-  it('adds a uniquely named blank field', () => {
-    const s = addField(base())
-    expect(s.fields).toHaveLength(4)
-    const added = s.fields[3]!
-    expect(added.type).toBe('text')
-    expect(base().fields.map((f) => f.field)).not.toContain(added.field)
-  })
-
-  it('avoids name collisions', () => {
-    const s: EntitySchema = { name: 't', fields: [{ field: 'field1', type: 'text' }] }
-    expect(blankField(s).field).not.toBe('field1')
-  })
-})
-
-describe('removeField', () => {
-  it('removes and clears idField if it pointed there', () => {
-    const s = removeField(base(), 'id')
-    expect(s.fields.map((f) => f.field)).toEqual(['name', 'tier'])
-    expect(s.idField).toBeUndefined()
-  })
-})
-
-describe('updateField', () => {
-  it('patches a field', () => {
-    const s = updateField(base(), 'name', { label: 'Full Name', required: true })
-    const f = s.fields.find((x) => x.field === 'name')!
-    expect(f.label).toBe('Full Name')
-    expect(f.required).toBe(true)
-  })
-
-  it('enforces a single primary key', () => {
-    const s = updateField(base(), 'name', { primaryKey: true })
-    expect(s.fields.find((f) => f.field === 'id')!.primaryKey).toBe(false)
-    expect(s.fields.find((f) => f.field === 'name')!.primaryKey).toBe(true)
-  })
-
-  it('drops options when a field leaves the enum type', () => {
-    const s = updateField(base(), 'tier', { type: 'text' })
-    expect(s.fields.find((f) => f.field === 'tier')!.options).toBeUndefined()
-  })
-})
-
-describe('moveField', () => {
-  it('reorders and is a no-op at the ends', () => {
-    expect(moveField(base(), 'name', -1).fields.map((f) => f.field)).toEqual(['name', 'id', 'tier'])
-    expect(moveField(base(), 'id', -1).fields.map((f) => f.field)).toEqual(['id', 'name', 'tier'])
-  })
-})
-
-describe('validateSchema', () => {
-  it('is clean for a well-formed schema', () => {
-    expect(validateSchema(base())).toEqual([])
-    expect(isSchemaValid(base())).toBe(true)
-  })
-
-  it('errors on duplicate names', () => {
-    const s: EntitySchema = {
-      name: 't',
-      idField: 'id',
-      fields: [{ field: 'id', type: 'text' }, { field: 'id', type: 'number' }],
-    }
-    expect(validateSchema(s).some((i) => i.level === 'error' && /Duplicate/.test(i.message))).toBe(true)
-  })
-
-  it('errors when no primary key resolves', () => {
-    const s: EntitySchema = { name: 't', fields: [{ field: 'x', type: 'text' }] }
-    expect(isSchemaValid(s)).toBe(false)
-    expect(validateSchema(s).some((i) => /primary key/.test(i.message))).toBe(true)
-  })
-
-  it('warns on an enum with no options and an incomplete relation', () => {
-    const s: EntitySchema = {
-      name: 't',
-      idField: 'id',
-      fields: [
-        { field: 'id', type: 'text', primaryKey: true },
-        { field: 'k', type: 'enum' },
-        { field: 'r', type: 'relation' },
-      ],
-    }
-    const warnings = validateSchema(s).filter((i) => i.level === 'warning')
-    expect(warnings.map((w) => w.field).sort()).toEqual(['k', 'r'])
-  })
-})
-
-describe('sampleRows', () => {
-  it('produces deterministic, type-appropriate sample data', () => {
-    const rows = sampleRows(base(), 2)
-    expect(rows).toHaveLength(2)
-    expect(rows[0]!.tier).toBe('free') // first enum option
-    expect(typeof rows[0]!.name).toBe('string')
-    // deterministic: same input, same output
-    expect(sampleRows(base(), 2)).toEqual(rows)
-  })
-})

package/src/schema-designer.ts

@@ -1,142 +0,0 @@
-/**
- * Schema-designer logic. The testable core behind `SvSchemaDesigner.svelte`:
- * immutable operations that edit an `EntitySchema` (add / remove / reorder /
- * retype fields, set the primary key), validation of the schema being designed,
- * and sample-row generation for the live grid preview.
- *
- * Pure (no Svelte, no DOM), mirroring the pivot-designer / edit-panel split.
- * Every mutation returns a NEW schema so Svelte reactivity and undo stay simple.
- */
-import type { EntityField, EntityFieldType, EntitySchema } from './schema'
-import { resolveIdField } from './schema'
-import { generateRows } from './studio/sample-data'
-
-/** All field types the designer offers, in menu order. */
-export const FIELD_TYPES: ReadonlyArray<EntityFieldType> = [
-  'text',
-  'number',
-  'boolean',
-  'date',
-  'dateString',
-  'datetime',
-  'enum',
-  'relation',
-  'json',
-]
-
-/** A fresh field with a name unique within the schema. */
-export function blankField(schema: EntitySchema): EntityField {
-  const taken = new Set(schema.fields.map((f) => f.field))
-  let n = schema.fields.length + 1
-  let name = `field${n}`
-  while (taken.has(name)) name = `field${++n}`
-  return { field: name, type: 'text' }
-}
-
-/** Append a field (a blank one when none is given). */
-export function addField(schema: EntitySchema, field?: EntityField): EntitySchema {
-  return { ...schema, fields: [...schema.fields, field ?? blankField(schema)] }
-}
-
-/** Remove a field by name. Clears `idField` if it pointed at the removed field. */
-export function removeField(schema: EntitySchema, fieldName: string): EntitySchema {
-  const fields = schema.fields.filter((f) => f.field !== fieldName)
-  const idField = schema.idField === fieldName ? undefined : schema.idField
-  return { ...schema, fields, idField }
-}
-
-/**
- * Patch a field by name. Setting `primaryKey: true` clears it on every other
- * field (a schema has at most one). Switching `type` drops now-irrelevant
- * `options` (leaving enum) / `relation` (leaving relation).
- */
-export function updateField(
-  schema: EntitySchema,
-  fieldName: string,
-  patch: Partial<EntityField>,
-): EntitySchema {
-  const makesPrimary = patch.primaryKey === true
-  const fields = schema.fields.map((f) => {
-    if (f.field !== fieldName) {
-      return makesPrimary && f.primaryKey ? { ...f, primaryKey: false } : f
-    }
-    const next: EntityField = { ...f, ...patch }
-    if (patch.type && patch.type !== f.type) {
-      if (patch.type !== 'enum') delete next.options
-      if (patch.type !== 'relation') delete next.relation
-    }
-    return next
-  })
-  return { ...schema, fields }
-}
-
-/** Move a field one slot up (`-1`) or down (`+1`). No-op at the ends. */
-export function moveField(schema: EntitySchema, fieldName: string, dir: -1 | 1): EntitySchema {
-  const i = schema.fields.findIndex((f) => f.field === fieldName)
-  const j = i + dir
-  if (i < 0 || j < 0 || j >= schema.fields.length) return schema
-  const fields = [...schema.fields]
-  const a = fields[i]!
-  const b = fields[j]!
-  fields[i] = b
-  fields[j] = a
-  return { ...schema, fields }
-}
-
-export type SchemaIssueLevel = 'error' | 'warning'
-export type SchemaIssue = { level: SchemaIssueLevel; message: string; field?: string }
-
-/**
- * Validate the schema under construction. Errors block code generation;
- * warnings are advisory. Covers: at least one field, unique field names, a
- * resolvable primary key, enums with options, and complete relations.
- */
-export function validateSchema(schema: EntitySchema): SchemaIssue[] {
-  const issues: SchemaIssue[] = []
-
-  if (schema.fields.length === 0) {
-    issues.push({ level: 'error', message: 'Add at least one field.' })
-  }
-
-  const seen = new Set<string>()
-  for (const f of schema.fields) {
-    if (!f.field.trim()) {
-      issues.push({ level: 'error', message: 'A field has an empty name.' })
-    } else if (seen.has(f.field)) {
-      issues.push({ level: 'error', message: `Duplicate field name "${f.field}".`, field: f.field })
-    }
-    seen.add(f.field)
-
-    if (f.type === 'enum' && (!f.options || f.options.length === 0)) {
-      issues.push({ level: 'warning', message: `Enum "${f.field}" has no options.`, field: f.field })
-    }
-    if (f.type === 'relation' && (!f.relation?.entity || !f.relation?.labelField)) {
-      issues.push({
-        level: 'warning',
-        message: `Relation "${f.field}" needs a related entity and label field.`,
-        field: f.field,
-      })
-    }
-  }
-
-  try {
-    resolveIdField(schema)
-  } catch {
-    issues.push({
-      level: 'error',
-      message: 'No primary key: flag a field as primary key, set idField, or name a field "id".',
-    })
-  }
-
-  return issues
-}
-
-/** True when the schema has no error-level issues (warnings are allowed). */
-export function isSchemaValid(schema: EntitySchema): boolean {
-  return !validateSchema(schema).some((i) => i.level === 'error')
-}
-
-/** Deterministic, realistic sample rows for the designer's grid preview. */
-export function sampleRows(schema: EntitySchema, count = 3): Array<Record<string, unknown>> {
-  return generateRows(schema.fields, count)
-}