@nixxie-cms/fields-cron 1.0.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Nixxie International DMCC
+Portions Copyright (c) 2023 Thinkmill Labs Pty Ltd and contributors
+(this software is derived from the KeystoneJS project, https://keystonejs.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @nixxie-cms/fields-cron
+
+A cron-expression field for Nixxie CMS. Stores a validated 5-field schedule
+(`minute hour day-of-month month day-of-week`) using the same syntax subset as
+`@nixxie-cms/jobs`: `*`, literals, ranges (`a-b`), steps (`*/n`, `a/n`, `a-b/n`) and
+comma-separated lists. `L`/`W`/`#` and month/day names are not supported.
+
+```ts
+import { cron } from '@nixxie-cms/fields-cron'
+
+fields: {
+  schedule: cron({ validation: { isRequired: true } }),
+}
+```
+
+Invalid expressions are rejected with the reason, e.g. `minute value 61 is out of range (0-59)`.
+
+## Helpers
+
+```ts
+import { isValidCron, nextRuns, describeCron } from '@nixxie-cms/fields-cron'
+
+isValidCron('*/15 9-17 * * 1-5') // true
+isValidCron('61 * * * *') // false
+
+nextRuns('0 9 * * 1', 3) // next 3 Mondays at 09:00 (scan capped at 366 days ahead)
+nextRuns('*/5 * * * *', 5, new Date('2026-06-12T10:00:00')) // from a specific time
+
+describeCron('* * * * *') // 'every minute'
+describeCron('*/10 * * * *') // 'every 10 minutes'
+describeCron('30 9 * * *') // 'daily at 09:30'
+describeCron('0 8 * * 1') // 'weekly on Monday at 08:00'
+describeCron('15 0 1 * *') // 'monthly on day 1 at 00:15'
+describeCron('0 0 1 1 *') // 'cron: 0 0 1 1 *' (best-effort fallback)
+```
+
+`nextRuns` scans minute-by-minute (like the jobs scheduler) in the server's local time and stops
+after 366 days, so rare or impossible schedules may return fewer dates than requested.

package/dist/declarations/src/index.d.ts

@@ -0,0 +1,30 @@
+import type { TextFieldConfig } from '@nixxie-cms/core/fields';
+import type { BaseCollectionTypeInfo, FieldTypeFunc } from '@nixxie-cms/core/types';
+/** Whether `expr` is a valid 5-field cron expression in the supported subset. */
+export declare function isValidCron(expr: string): boolean;
+/**
+ * Compute the next `count` (default 5) times `expr` will fire after `from` (default now), using
+ * the same minute-by-minute scan as @nixxie-cms/jobs. The scan is capped at 366 days ahead, so
+ * fewer (or zero) dates are returned for expressions that fire rarely or never (e.g. `0 0 31 2 *`).
+ * Throws when the expression is invalid.
+ */
+export declare function nextRuns(expr: string, count?: number, from?: Date): Date[];
+/**
+ * Best-effort human description of a cron expression. Handles the common shapes — "every minute",
+ * "every N minutes", "daily at HH:MM", "weekly on <day> at HH:MM" and "monthly on day N at HH:MM"
+ * — and falls back to `cron: <expr>` for anything else (including invalid expressions).
+ */
+export declare function describeCron(expr: string): string;
+export type CronFieldConfig<CollectionTypeInfo extends BaseCollectionTypeInfo> = Omit<TextFieldConfig<CollectionTypeInfo>, 'validation'> & {
+    validation?: {
+        /** Reject saving when no value is present. */
+        isRequired?: boolean;
+    };
+};
+/**
+ * A cron-expression field storing a validated 5-field schedule (`minute hour dom month dow`).
+ * Built on the core `text` field. Supports the same subset as @nixxie-cms/jobs: `*`, literals,
+ * ranges, steps and comma-separated lists. Whitespace is normalised on save.
+ */
+export declare function cron<CollectionTypeInfo extends BaseCollectionTypeInfo>(config?: CronFieldConfig<CollectionTypeInfo>): FieldTypeFunc<CollectionTypeInfo>;
+//# sourceMappingURL=index.d.ts.map

package/dist/declarations/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"../../../src","sources":["index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAyHnF,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOjD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,EAAE,CAW7E;AAID;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAwBjD;AAID,MAAM,MAAM,eAAe,CAAC,kBAAkB,SAAS,sBAAsB,IAAI,IAAI,CACnF,eAAe,CAAC,kBAAkB,CAAC,EACnC,YAAY,CACb,GAAG;IACF,UAAU,CAAC,EAAE;QACX,8CAA8C;QAC9C,UAAU,CAAC,EAAE,OAAO,CAAA;KACrB,CAAA;CACF,CAAA;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,kBAAkB,SAAS,sBAAsB,EACpE,MAAM,GAAE,eAAe,CAAC,kBAAkB,CAAM,GAC/C,aAAa,CAAC,kBAAkB,CAAC,CA6BnC"}

package/dist/nixxie-cms-fields-cron.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibml4eGllLWNtcy1maWVsZHMtY3Jvbi5janMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4vZGVjbGFyYXRpb25zL3NyYy9pbmRleC5kLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBIn0=

package/dist/nixxie-cms-fields-cron.cjs.js

@@ -0,0 +1,230 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var fields = require('@nixxie-cms/core/fields');
+
+// ── Cron parsing ──
+//
+// Supports the same subset as @nixxie-cms/jobs: five fields (minute hour dom month dow) with
+// `*`, literals, ranges (`a-b`), steps (`*/n`, `a/n`, `a-b/n`) and comma-separated lists of any
+// of the above. L/W/# and names (JAN, MON) are not supported.
+
+const FIELD_SPECS = [{
+  name: 'minute',
+  min: 0,
+  max: 59
+}, {
+  name: 'hour',
+  min: 0,
+  max: 23
+}, {
+  name: 'day-of-month',
+  min: 1,
+  max: 31
+}, {
+  name: 'month',
+  min: 1,
+  max: 12
+}, {
+  name: 'day-of-week',
+  min: 0,
+  max: 6
+}];
+function parseNumber(token, spec) {
+  if (!/^\d+$/.test(token)) {
+    throw new Error(`${spec.name} field has invalid value "${token}"`);
+  }
+  const n = parseInt(token, 10);
+  if (n < spec.min || n > spec.max) {
+    throw new Error(`${spec.name} value ${n} is out of range (${spec.min}-${spec.max})`);
+  }
+  return n;
+}
+
+/** Parse one comma-separated part of a cron field into a matcher; throws on invalid syntax. */
+function parsePart(part, spec) {
+  if (part === '') {
+    throw new Error(`${spec.name} field has an empty entry`);
+  }
+
+  // Step: base/step, where base is '*', a single number, or a range a-b
+  if (part.includes('/')) {
+    const pieces = part.split('/');
+    if (pieces.length !== 2) {
+      throw new Error(`${spec.name} field has invalid step expression "${part}"`);
+    }
+    const [base, stepStr] = pieces;
+    if (!/^\d+$/.test(stepStr) || parseInt(stepStr, 10) <= 0) {
+      throw new Error(`${spec.name} field has invalid step "/${stepStr}" (must be a positive integer)`);
+    }
+    const step = parseInt(stepStr, 10);
+    let from = spec.min;
+    let to = spec.max;
+    if (base !== '*') {
+      if (base.includes('-')) {
+        const range = base.split('-');
+        if (range.length !== 2) {
+          throw new Error(`${spec.name} field has invalid range "${base}"`);
+        }
+        from = parseNumber(range[0], spec);
+        to = parseNumber(range[1], spec);
+        if (from > to) {
+          throw new Error(`${spec.name} range ${from}-${to} is inverted (start must be <= end)`);
+        }
+      } else {
+        // a/n means "starting at a, every n" (open-ended), matching @nixxie-cms/jobs
+        from = parseNumber(base, spec);
+      }
+    }
+    return value => value >= from && value <= to && (value - from) % step === 0;
+  }
+
+  // Range: a-b
+  if (part.includes('-')) {
+    const range = part.split('-');
+    if (range.length !== 2) {
+      throw new Error(`${spec.name} field has invalid range "${part}"`);
+    }
+    const from = parseNumber(range[0], spec);
+    const to = parseNumber(range[1], spec);
+    if (from > to) {
+      throw new Error(`${spec.name} range ${from}-${to} is inverted (start must be <= end)`);
+    }
+    return value => value >= from && value <= to;
+  }
+
+  // Wildcard
+  if (part === '*') return () => true;
+
+  // Literal
+  const literal = parseNumber(part, spec);
+  return value => value === literal;
+}
+function parseField(field, spec) {
+  const matchers = field.split(',').map(part => parsePart(part, spec));
+  return value => matchers.some(m => m(value));
+}
+/** Compile a 5-field cron expression into a Date matcher; throws with the reason when invalid. */
+function compileCron(expr) {
+  if (typeof expr !== 'string' || expr.trim() === '') {
+    throw new Error('cron expression must be a non-empty string');
+  }
+  const fields = expr.trim().split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error(`cron expression must have 5 fields (minute hour day-of-month month day-of-week), got ${fields.length}`);
+  }
+  const [minute, hour, dom, month, dow] = fields.map((field, i) => parseField(field, FIELD_SPECS[i]));
+  return date => minute(date.getMinutes()) && hour(date.getHours()) && dom(date.getDate()) && month(date.getMonth() + 1) && dow(date.getDay());
+}
+
+/** Whether `expr` is a valid 5-field cron expression in the supported subset. */
+function isValidCron(expr) {
+  try {
+    compileCron(expr);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Compute the next `count` (default 5) times `expr` will fire after `from` (default now), using
+ * the same minute-by-minute scan as @nixxie-cms/jobs. The scan is capped at 366 days ahead, so
+ * fewer (or zero) dates are returned for expressions that fire rarely or never (e.g. `0 0 31 2 *`).
+ * Throws when the expression is invalid.
+ */
+function nextRuns(expr, count = 5, from) {
+  var _from$getTime;
+  const matcher = compileCron(expr);
+  const results = [];
+  const start = new Date((_from$getTime = from === null || from === void 0 ? void 0 : from.getTime()) !== null && _from$getTime !== void 0 ? _from$getTime : Date.now());
+  start.setSeconds(0, 0);
+  const limit = 366 * 24 * 60; // cap the scan at ~366 days, covering yearly schedules
+  for (let i = 1; i <= limit && results.length < count; i++) {
+    const candidate = new Date(start.getTime() + i * 60000);
+    if (matcher(candidate)) results.push(candidate);
+  }
+  return results;
+}
+const WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+
+/**
+ * Best-effort human description of a cron expression. Handles the common shapes — "every minute",
+ * "every N minutes", "daily at HH:MM", "weekly on <day> at HH:MM" and "monthly on day N at HH:MM"
+ * — and falls back to `cron: <expr>` for anything else (including invalid expressions).
+ */
+function describeCron(expr) {
+  const fallback = `cron: ${expr}`;
+  if (!isValidCron(expr)) return fallback;
+  const [minute, hour, dom, month, dow] = expr.trim().split(/\s+/);
+  if (minute === '*' && hour === '*' && dom === '*' && month === '*' && dow === '*') {
+    return 'every minute';
+  }
+  const everyN = /^\*\/(\d+)$/.exec(minute);
+  if (everyN && hour === '*' && dom === '*' && month === '*' && dow === '*') {
+    const n = parseInt(everyN[1], 10);
+    return n === 1 ? 'every minute' : `every ${n} minutes`;
+  }
+  if (/^\d+$/.test(minute) && /^\d+$/.test(hour) && month === '*') {
+    const time = `${hour.padStart(2, '0')}:${minute.padStart(2, '0')}`;
+    if (dom === '*' && dow === '*') return `daily at ${time}`;
+    if (dom === '*' && /^\d+$/.test(dow)) return `weekly on ${WEEKDAYS[parseInt(dow, 10)]} at ${time}`;
+    if (dow === '*' && /^\d+$/.test(dom)) return `monthly on day ${parseInt(dom, 10)} at ${time}`;
+  }
+  return fallback;
+}
+
+// ── Field type ──
+
+/**
+ * A cron-expression field storing a validated 5-field schedule (`minute hour dom month dow`).
+ * Built on the core `text` field. Supports the same subset as @nixxie-cms/jobs: `*`, literals,
+ * ranges, steps and comma-separated lists. Whitespace is normalised on save.
+ */
+function cron(config = {}) {
+  const {
+    hooks,
+    validation,
+    ...rest
+  } = config;
+  return fields.text({
+    ...rest,
+    validation: {
+      isRequired: validation === null || validation === void 0 ? void 0 : validation.isRequired
+    },
+    ui: {
+      description: 'Cron expression, e.g. */15 9-17 * * 1-5',
+      ...rest.ui
+    },
+    hooks: {
+      ...hooks,
+      resolveInput: args => {
+        const v = args.resolvedData[args.fieldKey];
+        return typeof v === 'string' ? v.trim().replace(/\s+/g, ' ') : v;
+      },
+      validate: args => {
+        const {
+          resolvedData,
+          fieldKey,
+          addValidationError,
+          operation
+        } = args;
+        if (operation === 'delete') return;
+        const value = resolvedData[fieldKey];
+        if (typeof value === 'string' && value.length > 0) {
+          try {
+            compileCron(value);
+          } catch (err) {
+            addValidationError(`${fieldKey} is not a valid cron expression: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }
+      }
+    }
+  });
+}
+
+exports.cron = cron;
+exports.describeCron = describeCron;
+exports.isValidCron = isValidCron;
+exports.nextRuns = nextRuns;

package/dist/nixxie-cms-fields-cron.esm.js

@@ -0,0 +1,223 @@
+import { text } from '@nixxie-cms/core/fields';
+
+// ── Cron parsing ──
+//
+// Supports the same subset as @nixxie-cms/jobs: five fields (minute hour dom month dow) with
+// `*`, literals, ranges (`a-b`), steps (`*/n`, `a/n`, `a-b/n`) and comma-separated lists of any
+// of the above. L/W/# and names (JAN, MON) are not supported.
+
+const FIELD_SPECS = [{
+  name: 'minute',
+  min: 0,
+  max: 59
+}, {
+  name: 'hour',
+  min: 0,
+  max: 23
+}, {
+  name: 'day-of-month',
+  min: 1,
+  max: 31
+}, {
+  name: 'month',
+  min: 1,
+  max: 12
+}, {
+  name: 'day-of-week',
+  min: 0,
+  max: 6
+}];
+function parseNumber(token, spec) {
+  if (!/^\d+$/.test(token)) {
+    throw new Error(`${spec.name} field has invalid value "${token}"`);
+  }
+  const n = parseInt(token, 10);
+  if (n < spec.min || n > spec.max) {
+    throw new Error(`${spec.name} value ${n} is out of range (${spec.min}-${spec.max})`);
+  }
+  return n;
+}
+
+/** Parse one comma-separated part of a cron field into a matcher; throws on invalid syntax. */
+function parsePart(part, spec) {
+  if (part === '') {
+    throw new Error(`${spec.name} field has an empty entry`);
+  }
+
+  // Step: base/step, where base is '*', a single number, or a range a-b
+  if (part.includes('/')) {
+    const pieces = part.split('/');
+    if (pieces.length !== 2) {
+      throw new Error(`${spec.name} field has invalid step expression "${part}"`);
+    }
+    const [base, stepStr] = pieces;
+    if (!/^\d+$/.test(stepStr) || parseInt(stepStr, 10) <= 0) {
+      throw new Error(`${spec.name} field has invalid step "/${stepStr}" (must be a positive integer)`);
+    }
+    const step = parseInt(stepStr, 10);
+    let from = spec.min;
+    let to = spec.max;
+    if (base !== '*') {
+      if (base.includes('-')) {
+        const range = base.split('-');
+        if (range.length !== 2) {
+          throw new Error(`${spec.name} field has invalid range "${base}"`);
+        }
+        from = parseNumber(range[0], spec);
+        to = parseNumber(range[1], spec);
+        if (from > to) {
+          throw new Error(`${spec.name} range ${from}-${to} is inverted (start must be <= end)`);
+        }
+      } else {
+        // a/n means "starting at a, every n" (open-ended), matching @nixxie-cms/jobs
+        from = parseNumber(base, spec);
+      }
+    }
+    return value => value >= from && value <= to && (value - from) % step === 0;
+  }
+
+  // Range: a-b
+  if (part.includes('-')) {
+    const range = part.split('-');
+    if (range.length !== 2) {
+      throw new Error(`${spec.name} field has invalid range "${part}"`);
+    }
+    const from = parseNumber(range[0], spec);
+    const to = parseNumber(range[1], spec);
+    if (from > to) {
+      throw new Error(`${spec.name} range ${from}-${to} is inverted (start must be <= end)`);
+    }
+    return value => value >= from && value <= to;
+  }
+
+  // Wildcard
+  if (part === '*') return () => true;
+
+  // Literal
+  const literal = parseNumber(part, spec);
+  return value => value === literal;
+}
+function parseField(field, spec) {
+  const matchers = field.split(',').map(part => parsePart(part, spec));
+  return value => matchers.some(m => m(value));
+}
+/** Compile a 5-field cron expression into a Date matcher; throws with the reason when invalid. */
+function compileCron(expr) {
+  if (typeof expr !== 'string' || expr.trim() === '') {
+    throw new Error('cron expression must be a non-empty string');
+  }
+  const fields = expr.trim().split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error(`cron expression must have 5 fields (minute hour day-of-month month day-of-week), got ${fields.length}`);
+  }
+  const [minute, hour, dom, month, dow] = fields.map((field, i) => parseField(field, FIELD_SPECS[i]));
+  return date => minute(date.getMinutes()) && hour(date.getHours()) && dom(date.getDate()) && month(date.getMonth() + 1) && dow(date.getDay());
+}
+
+/** Whether `expr` is a valid 5-field cron expression in the supported subset. */
+function isValidCron(expr) {
+  try {
+    compileCron(expr);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Compute the next `count` (default 5) times `expr` will fire after `from` (default now), using
+ * the same minute-by-minute scan as @nixxie-cms/jobs. The scan is capped at 366 days ahead, so
+ * fewer (or zero) dates are returned for expressions that fire rarely or never (e.g. `0 0 31 2 *`).
+ * Throws when the expression is invalid.
+ */
+function nextRuns(expr, count = 5, from) {
+  var _from$getTime;
+  const matcher = compileCron(expr);
+  const results = [];
+  const start = new Date((_from$getTime = from === null || from === void 0 ? void 0 : from.getTime()) !== null && _from$getTime !== void 0 ? _from$getTime : Date.now());
+  start.setSeconds(0, 0);
+  const limit = 366 * 24 * 60; // cap the scan at ~366 days, covering yearly schedules
+  for (let i = 1; i <= limit && results.length < count; i++) {
+    const candidate = new Date(start.getTime() + i * 60000);
+    if (matcher(candidate)) results.push(candidate);
+  }
+  return results;
+}
+const WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+
+/**
+ * Best-effort human description of a cron expression. Handles the common shapes — "every minute",
+ * "every N minutes", "daily at HH:MM", "weekly on <day> at HH:MM" and "monthly on day N at HH:MM"
+ * — and falls back to `cron: <expr>` for anything else (including invalid expressions).
+ */
+function describeCron(expr) {
+  const fallback = `cron: ${expr}`;
+  if (!isValidCron(expr)) return fallback;
+  const [minute, hour, dom, month, dow] = expr.trim().split(/\s+/);
+  if (minute === '*' && hour === '*' && dom === '*' && month === '*' && dow === '*') {
+    return 'every minute';
+  }
+  const everyN = /^\*\/(\d+)$/.exec(minute);
+  if (everyN && hour === '*' && dom === '*' && month === '*' && dow === '*') {
+    const n = parseInt(everyN[1], 10);
+    return n === 1 ? 'every minute' : `every ${n} minutes`;
+  }
+  if (/^\d+$/.test(minute) && /^\d+$/.test(hour) && month === '*') {
+    const time = `${hour.padStart(2, '0')}:${minute.padStart(2, '0')}`;
+    if (dom === '*' && dow === '*') return `daily at ${time}`;
+    if (dom === '*' && /^\d+$/.test(dow)) return `weekly on ${WEEKDAYS[parseInt(dow, 10)]} at ${time}`;
+    if (dow === '*' && /^\d+$/.test(dom)) return `monthly on day ${parseInt(dom, 10)} at ${time}`;
+  }
+  return fallback;
+}
+
+// ── Field type ──
+
+/**
+ * A cron-expression field storing a validated 5-field schedule (`minute hour dom month dow`).
+ * Built on the core `text` field. Supports the same subset as @nixxie-cms/jobs: `*`, literals,
+ * ranges, steps and comma-separated lists. Whitespace is normalised on save.
+ */
+function cron(config = {}) {
+  const {
+    hooks,
+    validation,
+    ...rest
+  } = config;
+  return text({
+    ...rest,
+    validation: {
+      isRequired: validation === null || validation === void 0 ? void 0 : validation.isRequired
+    },
+    ui: {
+      description: 'Cron expression, e.g. */15 9-17 * * 1-5',
+      ...rest.ui
+    },
+    hooks: {
+      ...hooks,
+      resolveInput: args => {
+        const v = args.resolvedData[args.fieldKey];
+        return typeof v === 'string' ? v.trim().replace(/\s+/g, ' ') : v;
+      },
+      validate: args => {
+        const {
+          resolvedData,
+          fieldKey,
+          addValidationError,
+          operation
+        } = args;
+        if (operation === 'delete') return;
+        const value = resolvedData[fieldKey];
+        if (typeof value === 'string' && value.length > 0) {
+          try {
+            compileCron(value);
+          } catch (err) {
+            addValidationError(`${fieldKey} is not a valid cron expression: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }
+      }
+    }
+  });
+}
+
+export { cron, describeCron, isValidCron, nextRuns };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nixxie-cms/fields-cron",
+  "version": "1.0.0",
+  "license": "MIT",
+  "main": "dist/nixxie-cms-fields-cron.cjs.js",
+  "module": "dist/nixxie-cms-fields-cron.esm.js",
+  "exports": {
+    ".": {
+      "types": "./dist/nixxie-cms-fields-cron.cjs.js",
+      "module": "./dist/nixxie-cms-fields-cron.esm.js",
+      "default": "./dist/nixxie-cms-fields-cron.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.24.7"
+  },
+  "devDependencies": {
+    "@nixxie-cms/core": "^1.1.0"
+  },
+  "peerDependencies": {
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "preconstruct": {
+    "entrypoints": [
+      "index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nixxiecms/nixxie/tree/main/packages/fields-cron"
+  }
+}

package/src/index.ts

@@ -0,0 +1,234 @@
+import { text } from '@nixxie-cms/core/fields'
+import type { TextFieldConfig } from '@nixxie-cms/core/fields'
+import type { BaseCollectionTypeInfo, FieldTypeFunc } from '@nixxie-cms/core/types'
+
+// ── Cron parsing ──
+//
+// Supports the same subset as @nixxie-cms/jobs: five fields (minute hour dom month dow) with
+// `*`, literals, ranges (`a-b`), steps (`*/n`, `a/n`, `a-b/n`) and comma-separated lists of any
+// of the above. L/W/# and names (JAN, MON) are not supported.
+
+type FieldSpec = { name: string; min: number; max: number }
+
+const FIELD_SPECS: FieldSpec[] = [
+  { name: 'minute', min: 0, max: 59 },
+  { name: 'hour', min: 0, max: 23 },
+  { name: 'day-of-month', min: 1, max: 31 },
+  { name: 'month', min: 1, max: 12 },
+  { name: 'day-of-week', min: 0, max: 6 },
+]
+
+type Matcher = (value: number) => boolean
+
+function parseNumber(token: string, spec: FieldSpec): number {
+  if (!/^\d+$/.test(token)) {
+    throw new Error(`${spec.name} field has invalid value "${token}"`)
+  }
+  const n = parseInt(token, 10)
+  if (n < spec.min || n > spec.max) {
+    throw new Error(`${spec.name} value ${n} is out of range (${spec.min}-${spec.max})`)
+  }
+  return n
+}
+
+/** Parse one comma-separated part of a cron field into a matcher; throws on invalid syntax. */
+function parsePart(part: string, spec: FieldSpec): Matcher {
+  if (part === '') {
+    throw new Error(`${spec.name} field has an empty entry`)
+  }
+
+  // Step: base/step, where base is '*', a single number, or a range a-b
+  if (part.includes('/')) {
+    const pieces = part.split('/')
+    if (pieces.length !== 2) {
+      throw new Error(`${spec.name} field has invalid step expression "${part}"`)
+    }
+    const [base, stepStr] = pieces
+    if (!/^\d+$/.test(stepStr) || parseInt(stepStr, 10) <= 0) {
+      throw new Error(`${spec.name} field has invalid step "/${stepStr}" (must be a positive integer)`)
+    }
+    const step = parseInt(stepStr, 10)
+
+    let from = spec.min
+    let to = spec.max
+    if (base !== '*') {
+      if (base.includes('-')) {
+        const range = base.split('-')
+        if (range.length !== 2) {
+          throw new Error(`${spec.name} field has invalid range "${base}"`)
+        }
+        from = parseNumber(range[0], spec)
+        to = parseNumber(range[1], spec)
+        if (from > to) {
+          throw new Error(`${spec.name} range ${from}-${to} is inverted (start must be <= end)`)
+        }
+      } else {
+        // a/n means "starting at a, every n" (open-ended), matching @nixxie-cms/jobs
+        from = parseNumber(base, spec)
+      }
+    }
+    return value => value >= from && value <= to && (value - from) % step === 0
+  }
+
+  // Range: a-b
+  if (part.includes('-')) {
+    const range = part.split('-')
+    if (range.length !== 2) {
+      throw new Error(`${spec.name} field has invalid range "${part}"`)
+    }
+    const from = parseNumber(range[0], spec)
+    const to = parseNumber(range[1], spec)
+    if (from > to) {
+      throw new Error(`${spec.name} range ${from}-${to} is inverted (start must be <= end)`)
+    }
+    return value => value >= from && value <= to
+  }
+
+  // Wildcard
+  if (part === '*') return () => true
+
+  // Literal
+  const literal = parseNumber(part, spec)
+  return value => value === literal
+}
+
+function parseField(field: string, spec: FieldSpec): Matcher {
+  const matchers = field.split(',').map(part => parsePart(part, spec))
+  return value => matchers.some(m => m(value))
+}
+
+type CronMatcher = (date: Date) => boolean
+
+/** Compile a 5-field cron expression into a Date matcher; throws with the reason when invalid. */
+function compileCron(expr: string): CronMatcher {
+  if (typeof expr !== 'string' || expr.trim() === '') {
+    throw new Error('cron expression must be a non-empty string')
+  }
+  const fields = expr.trim().split(/\s+/)
+  if (fields.length !== 5) {
+    throw new Error(
+      `cron expression must have 5 fields (minute hour day-of-month month day-of-week), got ${fields.length}`
+    )
+  }
+  const [minute, hour, dom, month, dow] = fields.map((field, i) =>
+    parseField(field, FIELD_SPECS[i])
+  )
+  return date =>
+    minute(date.getMinutes()) &&
+    hour(date.getHours()) &&
+    dom(date.getDate()) &&
+    month(date.getMonth() + 1) &&
+    dow(date.getDay())
+}
+
+/** Whether `expr` is a valid 5-field cron expression in the supported subset. */
+export function isValidCron(expr: string): boolean {
+  try {
+    compileCron(expr)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Compute the next `count` (default 5) times `expr` will fire after `from` (default now), using
+ * the same minute-by-minute scan as @nixxie-cms/jobs. The scan is capped at 366 days ahead, so
+ * fewer (or zero) dates are returned for expressions that fire rarely or never (e.g. `0 0 31 2 *`).
+ * Throws when the expression is invalid.
+ */
+export function nextRuns(expr: string, count: number = 5, from?: Date): Date[] {
+  const matcher = compileCron(expr)
+  const results: Date[] = []
+  const start = new Date(from?.getTime() ?? Date.now())
+  start.setSeconds(0, 0)
+  const limit = 366 * 24 * 60 // cap the scan at ~366 days, covering yearly schedules
+  for (let i = 1; i <= limit && results.length < count; i++) {
+    const candidate = new Date(start.getTime() + i * 60_000)
+    if (matcher(candidate)) results.push(candidate)
+  }
+  return results
+}
+
+const WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
+
+/**
+ * Best-effort human description of a cron expression. Handles the common shapes — "every minute",
+ * "every N minutes", "daily at HH:MM", "weekly on <day> at HH:MM" and "monthly on day N at HH:MM"
+ * — and falls back to `cron: <expr>` for anything else (including invalid expressions).
+ */
+export function describeCron(expr: string): string {
+  const fallback = `cron: ${expr}`
+  if (!isValidCron(expr)) return fallback
+
+  const [minute, hour, dom, month, dow] = expr.trim().split(/\s+/)
+
+  if (minute === '*' && hour === '*' && dom === '*' && month === '*' && dow === '*') {
+    return 'every minute'
+  }
+
+  const everyN = /^\*\/(\d+)$/.exec(minute)
+  if (everyN && hour === '*' && dom === '*' && month === '*' && dow === '*') {
+    const n = parseInt(everyN[1], 10)
+    return n === 1 ? 'every minute' : `every ${n} minutes`
+  }
+
+  if (/^\d+$/.test(minute) && /^\d+$/.test(hour) && month === '*') {
+    const time = `${hour.padStart(2, '0')}:${minute.padStart(2, '0')}`
+    if (dom === '*' && dow === '*') return `daily at ${time}`
+    if (dom === '*' && /^\d+$/.test(dow)) return `weekly on ${WEEKDAYS[parseInt(dow, 10)]} at ${time}`
+    if (dow === '*' && /^\d+$/.test(dom)) return `monthly on day ${parseInt(dom, 10)} at ${time}`
+  }
+
+  return fallback
+}
+
+// ── Field type ──
+
+export type CronFieldConfig<CollectionTypeInfo extends BaseCollectionTypeInfo> = Omit<
+  TextFieldConfig<CollectionTypeInfo>,
+  'validation'
+> & {
+  validation?: {
+    /** Reject saving when no value is present. */
+    isRequired?: boolean
+  }
+}
+
+/**
+ * A cron-expression field storing a validated 5-field schedule (`minute hour dom month dow`).
+ * Built on the core `text` field. Supports the same subset as @nixxie-cms/jobs: `*`, literals,
+ * ranges, steps and comma-separated lists. Whitespace is normalised on save.
+ */
+export function cron<CollectionTypeInfo extends BaseCollectionTypeInfo>(
+  config: CronFieldConfig<CollectionTypeInfo> = {}
+): FieldTypeFunc<CollectionTypeInfo> {
+  const { hooks, validation, ...rest } = config
+
+  return text<CollectionTypeInfo>({
+    ...(rest as TextFieldConfig<CollectionTypeInfo>),
+    validation: { isRequired: validation?.isRequired },
+    ui: { description: 'Cron expression, e.g. */15 9-17 * * 1-5', ...rest.ui },
+    hooks: {
+      ...hooks,
+      resolveInput: (args: any) => {
+        const v = args.resolvedData[args.fieldKey]
+        return typeof v === 'string' ? v.trim().replace(/\s+/g, ' ') : v
+      },
+      validate: (args: any) => {
+        const { resolvedData, fieldKey, addValidationError, operation } = args
+        if (operation === 'delete') return
+        const value = resolvedData[fieldKey]
+        if (typeof value === 'string' && value.length > 0) {
+          try {
+            compileCron(value)
+          } catch (err) {
+            addValidationError(
+              `${fieldKey} is not a valid cron expression: ${err instanceof Error ? err.message : String(err)}`
+            )
+          }
+        }
+      },
+    },
+  })
+}