@nixxie-cms/jobs 1.0.1

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/dist/declarations/src/JobsService.d.ts

@@ -0,0 +1,27 @@
+import type { NixxieJobDefinition, NixxieJobInfo, NixxieJobsService } from '@nixxie-cms/core';
+import type { JobsConfig } from "./types.js";
+export declare class JobsService implements NixxieJobsService {
+    private jobs;
+    private config;
+    private cronTimer;
+    private cronStarted;
+    private lastCronMinute;
+    private cronFormatter?;
+    private closed;
+    constructor(config: JobsConfig);
+    /** Lazily-built (and reused) Intl formatter for the configured cron timezone, if any. */
+    private getCronFormatter;
+    define(job: NixxieJobDefinition): void;
+    remove(name: string): void;
+    trigger(name: string): Promise<void>;
+    list(): NixxieJobInfo[];
+    get(name: string): NixxieJobInfo | undefined;
+    close(): Promise<void>;
+    private schedule;
+    /** Compute the next time a job will run (exact for intervals, next matching minute for cron). */
+    private computeNextRun;
+    private startCronTick;
+    private runJob;
+    private clearTimer;
+}
+//# sourceMappingURL=JobsService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"JobsService.d.ts","sourceRoot":"../../../src","sources":["JobsService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAC7F,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAe;AAuGzC,qBAAa,WAAY,YAAW,iBAAiB;IACnD,OAAO,CAAC,IAAI,CAA8B;IAC1C,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,SAAS,CAA6C;IAC9D,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,aAAa,CAAC,CAAqB;IAC3C,OAAO,CAAC,MAAM,CAAQ;gBAEV,MAAM,EAAE,UAAU;IAQ9B,yFAAyF;IACzF,OAAO,CAAC,gBAAgB;IAgBxB,MAAM,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI;IA2BtC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOpB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1C,IAAI,IAAI,aAAa,EAAE;IAIvB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAKtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB5B,OAAO,CAAC,QAAQ;IAgBhB,iGAAiG;IACjG,OAAO,CAAC,cAAc;IAuBtB,OAAO,CAAC,aAAa;YAqCP,MAAM;IA2DpB,OAAO,CAAC,UAAU;CAMnB"}

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

@@ -0,0 +1,7 @@
+import type { JobsConfig } from "./types.js";
+import { JobsService } from "./JobsService.js";
+export declare function createJobs(config?: JobsConfig): JobsService;
+export { JobsService };
+export type { JobsConfig } from "./types.js";
+export type { NixxieJobDefinition, NixxieJobInfo, NixxieJobsService } from '@nixxie-cms/core';
+//# 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":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAe;AACzC,OAAO,EAAE,WAAW,EAAE,yBAAqB;AAE3C,wBAAgB,UAAU,CAAC,MAAM,GAAE,UAAe,GAAG,WAAW,CAE/D;AAED,OAAO,EAAE,WAAW,EAAE,CAAA;AACtB,YAAY,EAAE,UAAU,EAAE,mBAAe;AACzC,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA"}

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

@@ -0,0 +1,28 @@
+import type { NixxieJobDefinition, NixxieJobInfo, NixxieJobsService } from '@nixxie-cms/core';
+export type { NixxieJobDefinition, NixxieJobInfo, NixxieJobsService };
+export type JobsConfig = {
+    /**
+     * Job definitions to register on start.
+     * Can also be registered later via `service.define()`.
+     */
+    jobs?: NixxieJobDefinition[];
+    /**
+     * Timezone to use for cron expression evaluation.
+     * Defaults to the system timezone.
+     */
+    timezone?: string;
+    /**
+     * How long (ms) to wait for in-flight jobs to finish on close().
+     * @default 5000
+     */
+    shutdownTimeout?: number;
+    /**
+     * Called when a job throws an error.
+     */
+    onError?: (name: string, error: Error) => void;
+    /**
+     * Called after each successful job execution.
+     */
+    onComplete?: (name: string, duration: number) => void;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"../../../src","sources":["types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAE7F,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,iBAAiB,EAAE,CAAA;AAErE,MAAM,MAAM,UAAU,GAAG;IACvB;;;OAGG;IACH,IAAI,CAAC,EAAE,mBAAmB,EAAE,CAAA;IAE5B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAE9C;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;CACtD,CAAA"}

package/dist/nixxie-cms-jobs.cjs.d.ts

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

package/dist/nixxie-cms-jobs.cjs.js

@@ -0,0 +1,320 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _defineProperty = require('@babel/runtime/helpers/defineProperty');
+
+function parseCron(expr) {
+  // Minimal cron parser: minute hour dom month dow
+  // Returns true if the given wall-clock parts match the expression
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) throw new Error(`Invalid cron expression: "${expr}"`);
+  const [minute, hour, dom, month, dow] = parts;
+
+  // Supported subset: *, literals, ranges (a-b), step (*/n, a-b/n, a/n) and
+  // comma-separated lists of any of the above. L/W/# are not supported.
+  function matches(field, value) {
+    // Comma list: any sub-expression matches
+    if (field.includes(',')) {
+      return field.split(',').some(part => matches(part, value));
+    }
+    // Step: base/step, where base is '*', a single number, or a range a-b
+    if (field.includes('/')) {
+      const [base, stepStr] = field.split('/');
+      const step = parseInt(stepStr, 10);
+      if (!Number.isFinite(step) || step <= 0) return false;
+      let from = 0;
+      let to = Infinity;
+      if (base !== '*' && base !== '') {
+        if (base.includes('-')) {
+          const [a, b] = base.split('-').map(Number);
+          from = a;
+          to = b;
+        } else {
+          from = parseInt(base, 10);
+        }
+      }
+      if (value < from || value > to) return false;
+      return (value - from) % step === 0;
+    }
+    // Range: a-b
+    if (field.includes('-')) {
+      const [from, to] = field.split('-').map(Number);
+      return value >= from && value <= to;
+    }
+    // Wildcard
+    if (field === '*') return true;
+    // Literal
+    return parseInt(field, 10) === value;
+  }
+  return parts => matches(minute, parts.minute) && matches(hour, parts.hour) && matches(dom, parts.dom) && matches(month, parts.month) && matches(dow, parts.dow);
+}
+/**
+ * Extract the cron-relevant wall-clock parts of `now`. When a timezone formatter is given the
+ * parts are computed in that timezone; otherwise the server's local time is used.
+ */
+function cronPartsOf(now, fmt) {
+  var _weekdays$get;
+  if (!fmt) {
+    return {
+      minute: now.getMinutes(),
+      hour: now.getHours(),
+      dom: now.getDate(),
+      month: now.getMonth() + 1,
+      dow: now.getDay()
+    };
+  }
+  const parts = fmt.formatToParts(now);
+  const get = type => {
+    var _parts$find$value, _parts$find;
+    return (_parts$find$value = (_parts$find = parts.find(p => p.type === type)) === null || _parts$find === void 0 ? void 0 : _parts$find.value) !== null && _parts$find$value !== void 0 ? _parts$find$value : '';
+  };
+  const weekdays = {
+    Sun: 0,
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6
+  };
+  let hour = parseInt(get('hour'), 10);
+  if (hour === 24) hour = 0; // some ICU builds render midnight as '24' under hour12:false
+  return {
+    minute: parseInt(get('minute'), 10),
+    hour,
+    dom: parseInt(get('day'), 10),
+    month: parseInt(get('month'), 10),
+    dow: (_weekdays$get = weekdays[get('weekday')]) !== null && _weekdays$get !== void 0 ? _weekdays$get : 0
+  };
+}
+class JobsService {
+  constructor(config) {
+    _defineProperty(this, "jobs", new Map());
+    _defineProperty(this, "cronTimer", null);
+    _defineProperty(this, "cronStarted", false);
+    _defineProperty(this, "lastCronMinute", -1);
+    _defineProperty(this, "closed", false);
+    this.config = config;
+    for (const job of (_config$jobs = config.jobs) !== null && _config$jobs !== void 0 ? _config$jobs : []) {
+      var _config$jobs;
+      this.define(job);
+    }
+  }
+
+  /** Lazily-built (and reused) Intl formatter for the configured cron timezone, if any. */
+  getCronFormatter() {
+    if (!this.config.timezone) return undefined;
+    if (!this.cronFormatter) {
+      this.cronFormatter = new Intl.DateTimeFormat('en-US', {
+        timeZone: this.config.timezone,
+        hour12: false,
+        weekday: 'short',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit'
+      });
+    }
+    return this.cronFormatter;
+  }
+  define(job) {
+    if (this.jobs.has(job.name)) {
+      this.remove(job.name);
+    }
+    const state = {
+      definition: job,
+      info: {
+        name: job.name,
+        status: job.enabled === false ? 'disabled' : 'idle',
+        runs: 0
+      },
+      timer: null,
+      running: false
+    };
+    this.jobs.set(job.name, state);
+    if (job.enabled !== false) {
+      this.schedule(state);
+    }
+    if (job.runImmediately) {
+      void this.runJob(state);
+    }
+  }
+  remove(name) {
+    const state = this.jobs.get(name);
+    if (!state) return;
+    this.clearTimer(state);
+    this.jobs.delete(name);
+  }
+  async trigger(name) {
+    const state = this.jobs.get(name);
+    if (!state) throw new Error(`Job "${name}" is not registered`);
+    await this.runJob(state);
+  }
+  list() {
+    return Array.from(this.jobs.values()).map(s => ({
+      ...s.info
+    }));
+  }
+  get(name) {
+    const state = this.jobs.get(name);
+    return state ? {
+      ...state.info
+    } : undefined;
+  }
+  async close() {
+    var _this$config$shutdown;
+    this.closed = true;
+    if (this.cronTimer) {
+      clearTimeout(this.cronTimer);
+      this.cronTimer = null;
+    }
+    this.cronStarted = false;
+    for (const state of this.jobs.values()) {
+      this.clearTimer(state);
+    }
+    const timeout = (_this$config$shutdown = this.config.shutdownTimeout) !== null && _this$config$shutdown !== void 0 ? _this$config$shutdown : 5000;
+    const deadline = Date.now() + timeout;
+
+    // Wait for running jobs
+    while (Date.now() < deadline) {
+      const anyRunning = Array.from(this.jobs.values()).some(s => s.running);
+      if (!anyRunning) break;
+      await new Promise(r => setTimeout(r, 100));
+    }
+  }
+  schedule(state) {
+    const {
+      definition
+    } = state;
+    const schedule = definition.schedule;
+    if (typeof schedule === 'number') {
+      // Interval in ms
+      state.timer = setInterval(() => void this.runJob(state), schedule);
+    } else {
+      // Cron expression — a single shared per-minute ticker drives all cron jobs.
+      if (!this.cronStarted) {
+        this.startCronTick();
+      }
+    }
+    state.info.nextRun = this.computeNextRun(state);
+  }
+
+  /** Compute the next time a job will run (exact for intervals, next matching minute for cron). */
+  computeNextRun(state) {
+    const schedule = state.definition.schedule;
+    if (typeof schedule === 'number') {
+      return new Date(Date.now() + schedule);
+    }
+    let matcher;
+    try {
+      matcher = parseCron(schedule);
+    } catch {
+      return undefined;
+    }
+    const fmt = this.getCronFormatter();
+    const start = new Date();
+    start.setSeconds(0, 0);
+    // Search minute-by-minute up to ~366 days ahead (covers yearly schedules). The loop exits on
+    // the first match, so frequent schedules are cheap.
+    for (let i = 1; i <= 366 * 24 * 60; i++) {
+      const candidate = new Date(start.getTime() + i * 60000);
+      if (matcher(cronPartsOf(candidate, fmt))) return candidate;
+    }
+    return undefined;
+  }
+  startCronTick() {
+    this.cronStarted = true;
+    const scheduleNext = () => {
+      if (this.closed) return;
+      // Re-arm to the next minute boundary every tick. A fixed `setInterval(…, 60_000)` accumulates
+      // drift and can eventually skip a whole minute, silently losing a cron execution.
+      const ms = 60000 - Date.now() % 60000;
+      this.cronTimer = setTimeout(tick, ms);
+    };
+    const tick = () => {
+      this.cronTimer = null;
+      if (this.closed) return;
+      const now = new Date();
+      const minuteKey = Math.floor(now.getTime() / 60000);
+      // Only evaluate each wall-clock minute once, even if a tick fires slightly late/twice.
+      if (minuteKey !== this.lastCronMinute) {
+        this.lastCronMinute = minuteKey;
+        const parts = cronPartsOf(now, this.getCronFormatter());
+        for (const state of this.jobs.values()) {
+          if (typeof state.definition.schedule !== 'string') continue;
+          if (state.info.status === 'disabled' || state.running) continue;
+          try {
+            const matcher = parseCron(state.definition.schedule);
+            if (matcher(parts)) void this.runJob(state);
+          } catch (err) {
+            console.error(`[nixxie/jobs] Invalid cron for "${state.definition.name}":`, err);
+          }
+        }
+      }
+      scheduleNext();
+    };
+    scheduleNext();
+  }
+  async runJob(state) {
+    if (state.running || this.closed) return;
+    state.running = true;
+    state.info.status = 'running';
+    const start = Date.now();
+    const scheduledAt = new Date();
+    const run = Promise.resolve(state.definition.handler({
+      jobId: state.definition.name,
+      scheduledAt
+    }));
+    try {
+      var _this$config$onComple, _this$config;
+      const timeoutMs = state.definition.timeout;
+      if (timeoutMs) {
+        let timer;
+        try {
+          await Promise.race([run, new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`Job "${state.definition.name}" timed out after ${timeoutMs}ms`)), timeoutMs);
+          })]);
+        } finally {
+          if (timer) clearTimeout(timer);
+        }
+      } else {
+        await run;
+      }
+      state.info.status = 'idle';
+      state.info.lastRun = new Date();
+      state.info.runs++;
+      state.info.lastError = undefined;
+      (_this$config$onComple = (_this$config = this.config).onComplete) === null || _this$config$onComple === void 0 || _this$config$onComple.call(_this$config, state.definition.name, Date.now() - start);
+    } catch (err) {
+      var _this$config$onError, _this$config2;
+      const error = err instanceof Error ? err : new Error(String(err));
+      state.info.status = 'error';
+      state.info.lastRun = new Date();
+      state.info.lastError = error.message;
+      (_this$config$onError = (_this$config2 = this.config).onError) === null || _this$config$onError === void 0 || _this$config$onError.call(_this$config2, state.definition.name, error);
+      console.error(`[nixxie/jobs] Job "${state.definition.name}" failed:`, error);
+    } finally {
+      // Release the overlap lock only once the handler actually settles. On timeout we stopped
+      // *waiting* for it, but it may still be running in the background — releasing synchronously
+      // would let the next tick start a second concurrent run. (Normally `run` is already settled.)
+      void run.catch(() => {}).then(() => {
+        state.running = false;
+        if (!this.closed) state.info.nextRun = this.computeNextRun(state);
+      });
+    }
+  }
+  clearTimer(state) {
+    if (state.timer) {
+      clearInterval(state.timer);
+      state.timer = null;
+    }
+  }
+}
+
+function createJobs(config = {}) {
+  return new JobsService(config);
+}
+
+exports.JobsService = JobsService;
+exports.createJobs = createJobs;

package/dist/nixxie-cms-jobs.esm.js

@@ -0,0 +1,315 @@
+import _defineProperty from '@babel/runtime/helpers/esm/defineProperty';
+
+function parseCron(expr) {
+  // Minimal cron parser: minute hour dom month dow
+  // Returns true if the given wall-clock parts match the expression
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) throw new Error(`Invalid cron expression: "${expr}"`);
+  const [minute, hour, dom, month, dow] = parts;
+
+  // Supported subset: *, literals, ranges (a-b), step (*/n, a-b/n, a/n) and
+  // comma-separated lists of any of the above. L/W/# are not supported.
+  function matches(field, value) {
+    // Comma list: any sub-expression matches
+    if (field.includes(',')) {
+      return field.split(',').some(part => matches(part, value));
+    }
+    // Step: base/step, where base is '*', a single number, or a range a-b
+    if (field.includes('/')) {
+      const [base, stepStr] = field.split('/');
+      const step = parseInt(stepStr, 10);
+      if (!Number.isFinite(step) || step <= 0) return false;
+      let from = 0;
+      let to = Infinity;
+      if (base !== '*' && base !== '') {
+        if (base.includes('-')) {
+          const [a, b] = base.split('-').map(Number);
+          from = a;
+          to = b;
+        } else {
+          from = parseInt(base, 10);
+        }
+      }
+      if (value < from || value > to) return false;
+      return (value - from) % step === 0;
+    }
+    // Range: a-b
+    if (field.includes('-')) {
+      const [from, to] = field.split('-').map(Number);
+      return value >= from && value <= to;
+    }
+    // Wildcard
+    if (field === '*') return true;
+    // Literal
+    return parseInt(field, 10) === value;
+  }
+  return parts => matches(minute, parts.minute) && matches(hour, parts.hour) && matches(dom, parts.dom) && matches(month, parts.month) && matches(dow, parts.dow);
+}
+/**
+ * Extract the cron-relevant wall-clock parts of `now`. When a timezone formatter is given the
+ * parts are computed in that timezone; otherwise the server's local time is used.
+ */
+function cronPartsOf(now, fmt) {
+  var _weekdays$get;
+  if (!fmt) {
+    return {
+      minute: now.getMinutes(),
+      hour: now.getHours(),
+      dom: now.getDate(),
+      month: now.getMonth() + 1,
+      dow: now.getDay()
+    };
+  }
+  const parts = fmt.formatToParts(now);
+  const get = type => {
+    var _parts$find$value, _parts$find;
+    return (_parts$find$value = (_parts$find = parts.find(p => p.type === type)) === null || _parts$find === void 0 ? void 0 : _parts$find.value) !== null && _parts$find$value !== void 0 ? _parts$find$value : '';
+  };
+  const weekdays = {
+    Sun: 0,
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6
+  };
+  let hour = parseInt(get('hour'), 10);
+  if (hour === 24) hour = 0; // some ICU builds render midnight as '24' under hour12:false
+  return {
+    minute: parseInt(get('minute'), 10),
+    hour,
+    dom: parseInt(get('day'), 10),
+    month: parseInt(get('month'), 10),
+    dow: (_weekdays$get = weekdays[get('weekday')]) !== null && _weekdays$get !== void 0 ? _weekdays$get : 0
+  };
+}
+class JobsService {
+  constructor(config) {
+    _defineProperty(this, "jobs", new Map());
+    _defineProperty(this, "cronTimer", null);
+    _defineProperty(this, "cronStarted", false);
+    _defineProperty(this, "lastCronMinute", -1);
+    _defineProperty(this, "closed", false);
+    this.config = config;
+    for (const job of (_config$jobs = config.jobs) !== null && _config$jobs !== void 0 ? _config$jobs : []) {
+      var _config$jobs;
+      this.define(job);
+    }
+  }
+
+  /** Lazily-built (and reused) Intl formatter for the configured cron timezone, if any. */
+  getCronFormatter() {
+    if (!this.config.timezone) return undefined;
+    if (!this.cronFormatter) {
+      this.cronFormatter = new Intl.DateTimeFormat('en-US', {
+        timeZone: this.config.timezone,
+        hour12: false,
+        weekday: 'short',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit'
+      });
+    }
+    return this.cronFormatter;
+  }
+  define(job) {
+    if (this.jobs.has(job.name)) {
+      this.remove(job.name);
+    }
+    const state = {
+      definition: job,
+      info: {
+        name: job.name,
+        status: job.enabled === false ? 'disabled' : 'idle',
+        runs: 0
+      },
+      timer: null,
+      running: false
+    };
+    this.jobs.set(job.name, state);
+    if (job.enabled !== false) {
+      this.schedule(state);
+    }
+    if (job.runImmediately) {
+      void this.runJob(state);
+    }
+  }
+  remove(name) {
+    const state = this.jobs.get(name);
+    if (!state) return;
+    this.clearTimer(state);
+    this.jobs.delete(name);
+  }
+  async trigger(name) {
+    const state = this.jobs.get(name);
+    if (!state) throw new Error(`Job "${name}" is not registered`);
+    await this.runJob(state);
+  }
+  list() {
+    return Array.from(this.jobs.values()).map(s => ({
+      ...s.info
+    }));
+  }
+  get(name) {
+    const state = this.jobs.get(name);
+    return state ? {
+      ...state.info
+    } : undefined;
+  }
+  async close() {
+    var _this$config$shutdown;
+    this.closed = true;
+    if (this.cronTimer) {
+      clearTimeout(this.cronTimer);
+      this.cronTimer = null;
+    }
+    this.cronStarted = false;
+    for (const state of this.jobs.values()) {
+      this.clearTimer(state);
+    }
+    const timeout = (_this$config$shutdown = this.config.shutdownTimeout) !== null && _this$config$shutdown !== void 0 ? _this$config$shutdown : 5000;
+    const deadline = Date.now() + timeout;
+
+    // Wait for running jobs
+    while (Date.now() < deadline) {
+      const anyRunning = Array.from(this.jobs.values()).some(s => s.running);
+      if (!anyRunning) break;
+      await new Promise(r => setTimeout(r, 100));
+    }
+  }
+  schedule(state) {
+    const {
+      definition
+    } = state;
+    const schedule = definition.schedule;
+    if (typeof schedule === 'number') {
+      // Interval in ms
+      state.timer = setInterval(() => void this.runJob(state), schedule);
+    } else {
+      // Cron expression — a single shared per-minute ticker drives all cron jobs.
+      if (!this.cronStarted) {
+        this.startCronTick();
+      }
+    }
+    state.info.nextRun = this.computeNextRun(state);
+  }
+
+  /** Compute the next time a job will run (exact for intervals, next matching minute for cron). */
+  computeNextRun(state) {
+    const schedule = state.definition.schedule;
+    if (typeof schedule === 'number') {
+      return new Date(Date.now() + schedule);
+    }
+    let matcher;
+    try {
+      matcher = parseCron(schedule);
+    } catch {
+      return undefined;
+    }
+    const fmt = this.getCronFormatter();
+    const start = new Date();
+    start.setSeconds(0, 0);
+    // Search minute-by-minute up to ~366 days ahead (covers yearly schedules). The loop exits on
+    // the first match, so frequent schedules are cheap.
+    for (let i = 1; i <= 366 * 24 * 60; i++) {
+      const candidate = new Date(start.getTime() + i * 60000);
+      if (matcher(cronPartsOf(candidate, fmt))) return candidate;
+    }
+    return undefined;
+  }
+  startCronTick() {
+    this.cronStarted = true;
+    const scheduleNext = () => {
+      if (this.closed) return;
+      // Re-arm to the next minute boundary every tick. A fixed `setInterval(…, 60_000)` accumulates
+      // drift and can eventually skip a whole minute, silently losing a cron execution.
+      const ms = 60000 - Date.now() % 60000;
+      this.cronTimer = setTimeout(tick, ms);
+    };
+    const tick = () => {
+      this.cronTimer = null;
+      if (this.closed) return;
+      const now = new Date();
+      const minuteKey = Math.floor(now.getTime() / 60000);
+      // Only evaluate each wall-clock minute once, even if a tick fires slightly late/twice.
+      if (minuteKey !== this.lastCronMinute) {
+        this.lastCronMinute = minuteKey;
+        const parts = cronPartsOf(now, this.getCronFormatter());
+        for (const state of this.jobs.values()) {
+          if (typeof state.definition.schedule !== 'string') continue;
+          if (state.info.status === 'disabled' || state.running) continue;
+          try {
+            const matcher = parseCron(state.definition.schedule);
+            if (matcher(parts)) void this.runJob(state);
+          } catch (err) {
+            console.error(`[nixxie/jobs] Invalid cron for "${state.definition.name}":`, err);
+          }
+        }
+      }
+      scheduleNext();
+    };
+    scheduleNext();
+  }
+  async runJob(state) {
+    if (state.running || this.closed) return;
+    state.running = true;
+    state.info.status = 'running';
+    const start = Date.now();
+    const scheduledAt = new Date();
+    const run = Promise.resolve(state.definition.handler({
+      jobId: state.definition.name,
+      scheduledAt
+    }));
+    try {
+      var _this$config$onComple, _this$config;
+      const timeoutMs = state.definition.timeout;
+      if (timeoutMs) {
+        let timer;
+        try {
+          await Promise.race([run, new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`Job "${state.definition.name}" timed out after ${timeoutMs}ms`)), timeoutMs);
+          })]);
+        } finally {
+          if (timer) clearTimeout(timer);
+        }
+      } else {
+        await run;
+      }
+      state.info.status = 'idle';
+      state.info.lastRun = new Date();
+      state.info.runs++;
+      state.info.lastError = undefined;
+      (_this$config$onComple = (_this$config = this.config).onComplete) === null || _this$config$onComple === void 0 || _this$config$onComple.call(_this$config, state.definition.name, Date.now() - start);
+    } catch (err) {
+      var _this$config$onError, _this$config2;
+      const error = err instanceof Error ? err : new Error(String(err));
+      state.info.status = 'error';
+      state.info.lastRun = new Date();
+      state.info.lastError = error.message;
+      (_this$config$onError = (_this$config2 = this.config).onError) === null || _this$config$onError === void 0 || _this$config$onError.call(_this$config2, state.definition.name, error);
+      console.error(`[nixxie/jobs] Job "${state.definition.name}" failed:`, error);
+    } finally {
+      // Release the overlap lock only once the handler actually settles. On timeout we stopped
+      // *waiting* for it, but it may still be running in the background — releasing synchronously
+      // would let the next tick start a second concurrent run. (Normally `run` is already settled.)
+      void run.catch(() => {}).then(() => {
+        state.running = false;
+        if (!this.closed) state.info.nextRun = this.computeNextRun(state);
+      });
+    }
+  }
+  clearTimer(state) {
+    if (state.timer) {
+      clearInterval(state.timer);
+      state.timer = null;
+    }
+  }
+}
+
+function createJobs(config = {}) {
+  return new JobsService(config);
+}
+
+export { JobsService, createJobs };

package/package.json

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

package/src/JobsService.ts

@@ -0,0 +1,352 @@
+import type { NixxieJobDefinition, NixxieJobInfo, NixxieJobsService } from '@nixxie-cms/core'
+import type { JobsConfig } from './types'
+
+type Timer = ReturnType<typeof setInterval> | ReturnType<typeof setTimeout>
+
+type JobState = {
+  definition: NixxieJobDefinition
+  info: NixxieJobInfo
+  timer: Timer | null
+  running: boolean
+}
+
+function parseCron(expr: string): (parts: CronParts) => boolean {
+  // Minimal cron parser: minute hour dom month dow
+  // Returns true if the given wall-clock parts match the expression
+  const parts = expr.trim().split(/\s+/)
+  if (parts.length !== 5) throw new Error(`Invalid cron expression: "${expr}"`)
+
+  const [minute, hour, dom, month, dow] = parts
+
+  // Supported subset: *, literals, ranges (a-b), step (*/n, a-b/n, a/n) and
+  // comma-separated lists of any of the above. L/W/# are not supported.
+  function matches(field: string, value: number): boolean {
+    // Comma list: any sub-expression matches
+    if (field.includes(',')) {
+      return field.split(',').some(part => matches(part, value))
+    }
+    // Step: base/step, where base is '*', a single number, or a range a-b
+    if (field.includes('/')) {
+      const [base, stepStr] = field.split('/')
+      const step = parseInt(stepStr, 10)
+      if (!Number.isFinite(step) || step <= 0) return false
+
+      let from = 0
+      let to = Infinity
+      if (base !== '*' && base !== '') {
+        if (base.includes('-')) {
+          const [a, b] = base.split('-').map(Number)
+          from = a
+          to = b
+        } else {
+          from = parseInt(base, 10)
+        }
+      }
+      if (value < from || value > to) return false
+      return (value - from) % step === 0
+    }
+    // Range: a-b
+    if (field.includes('-')) {
+      const [from, to] = field.split('-').map(Number)
+      return value >= from && value <= to
+    }
+    // Wildcard
+    if (field === '*') return true
+    // Literal
+    return parseInt(field, 10) === value
+  }
+
+  return (parts: CronParts) =>
+    matches(minute, parts.minute) &&
+    matches(hour, parts.hour) &&
+    matches(dom, parts.dom) &&
+    matches(month, parts.month) &&
+    matches(dow, parts.dow)
+}
+
+type CronParts = { minute: number; hour: number; dom: number; month: number; dow: number }
+
+/**
+ * Extract the cron-relevant wall-clock parts of `now`. When a timezone formatter is given the
+ * parts are computed in that timezone; otherwise the server's local time is used.
+ */
+function cronPartsOf(now: Date, fmt?: Intl.DateTimeFormat): CronParts {
+  if (!fmt) {
+    return {
+      minute: now.getMinutes(),
+      hour: now.getHours(),
+      dom: now.getDate(),
+      month: now.getMonth() + 1,
+      dow: now.getDay(),
+    }
+  }
+  const parts = fmt.formatToParts(now)
+  const get = (type: string) => parts.find(p => p.type === type)?.value ?? ''
+  const weekdays: Record<string, number> = {
+    Sun: 0,
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6,
+  }
+  let hour = parseInt(get('hour'), 10)
+  if (hour === 24) hour = 0 // some ICU builds render midnight as '24' under hour12:false
+  return {
+    minute: parseInt(get('minute'), 10),
+    hour,
+    dom: parseInt(get('day'), 10),
+    month: parseInt(get('month'), 10),
+    dow: weekdays[get('weekday')] ?? 0,
+  }
+}
+
+export class JobsService implements NixxieJobsService {
+  private jobs = new Map<string, JobState>()
+  private config: JobsConfig
+  private cronTimer: ReturnType<typeof setTimeout> | null = null
+  private cronStarted = false
+  private lastCronMinute = -1
+  private cronFormatter?: Intl.DateTimeFormat
+  private closed = false
+
+  constructor(config: JobsConfig) {
+    this.config = config
+
+    for (const job of config.jobs ?? []) {
+      this.define(job)
+    }
+  }
+
+  /** Lazily-built (and reused) Intl formatter for the configured cron timezone, if any. */
+  private getCronFormatter(): Intl.DateTimeFormat | undefined {
+    if (!this.config.timezone) return undefined
+    if (!this.cronFormatter) {
+      this.cronFormatter = new Intl.DateTimeFormat('en-US', {
+        timeZone: this.config.timezone,
+        hour12: false,
+        weekday: 'short',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+      })
+    }
+    return this.cronFormatter
+  }
+
+  define(job: NixxieJobDefinition): void {
+    if (this.jobs.has(job.name)) {
+      this.remove(job.name)
+    }
+
+    const state: JobState = {
+      definition: job,
+      info: {
+        name: job.name,
+        status: job.enabled === false ? 'disabled' : 'idle',
+        runs: 0,
+      },
+      timer: null,
+      running: false,
+    }
+
+    this.jobs.set(job.name, state)
+
+    if (job.enabled !== false) {
+      this.schedule(state)
+    }
+
+    if (job.runImmediately) {
+      void this.runJob(state)
+    }
+  }
+
+  remove(name: string): void {
+    const state = this.jobs.get(name)
+    if (!state) return
+    this.clearTimer(state)
+    this.jobs.delete(name)
+  }
+
+  async trigger(name: string): Promise<void> {
+    const state = this.jobs.get(name)
+    if (!state) throw new Error(`Job "${name}" is not registered`)
+    await this.runJob(state)
+  }
+
+  list(): NixxieJobInfo[] {
+    return Array.from(this.jobs.values()).map(s => ({ ...s.info }))
+  }
+
+  get(name: string): NixxieJobInfo | undefined {
+    const state = this.jobs.get(name)
+    return state ? { ...state.info } : undefined
+  }
+
+  async close(): Promise<void> {
+    this.closed = true
+    if (this.cronTimer) {
+      clearTimeout(this.cronTimer)
+      this.cronTimer = null
+    }
+    this.cronStarted = false
+    for (const state of this.jobs.values()) {
+      this.clearTimer(state)
+    }
+
+    const timeout = this.config.shutdownTimeout ?? 5000
+    const deadline = Date.now() + timeout
+
+    // Wait for running jobs
+    while (Date.now() < deadline) {
+      const anyRunning = Array.from(this.jobs.values()).some(s => s.running)
+      if (!anyRunning) break
+      await new Promise(r => setTimeout(r, 100))
+    }
+  }
+
+  private schedule(state: JobState): void {
+    const { definition } = state
+    const schedule = definition.schedule
+
+    if (typeof schedule === 'number') {
+      // Interval in ms
+      state.timer = setInterval(() => void this.runJob(state), schedule)
+    } else {
+      // Cron expression — a single shared per-minute ticker drives all cron jobs.
+      if (!this.cronStarted) {
+        this.startCronTick()
+      }
+    }
+    state.info.nextRun = this.computeNextRun(state)
+  }
+
+  /** Compute the next time a job will run (exact for intervals, next matching minute for cron). */
+  private computeNextRun(state: JobState): Date | undefined {
+    const schedule = state.definition.schedule
+    if (typeof schedule === 'number') {
+      return new Date(Date.now() + schedule)
+    }
+    let matcher: (parts: CronParts) => boolean
+    try {
+      matcher = parseCron(schedule)
+    } catch {
+      return undefined
+    }
+    const fmt = this.getCronFormatter()
+    const start = new Date()
+    start.setSeconds(0, 0)
+    // Search minute-by-minute up to ~366 days ahead (covers yearly schedules). The loop exits on
+    // the first match, so frequent schedules are cheap.
+    for (let i = 1; i <= 366 * 24 * 60; i++) {
+      const candidate = new Date(start.getTime() + i * 60_000)
+      if (matcher(cronPartsOf(candidate, fmt))) return candidate
+    }
+    return undefined
+  }
+
+  private startCronTick(): void {
+    this.cronStarted = true
+
+    const scheduleNext = () => {
+      if (this.closed) return
+      // Re-arm to the next minute boundary every tick. A fixed `setInterval(…, 60_000)` accumulates
+      // drift and can eventually skip a whole minute, silently losing a cron execution.
+      const ms = 60_000 - (Date.now() % 60_000)
+      this.cronTimer = setTimeout(tick, ms)
+    }
+
+    const tick = () => {
+      this.cronTimer = null
+      if (this.closed) return
+      const now = new Date()
+      const minuteKey = Math.floor(now.getTime() / 60_000)
+      // Only evaluate each wall-clock minute once, even if a tick fires slightly late/twice.
+      if (minuteKey !== this.lastCronMinute) {
+        this.lastCronMinute = minuteKey
+        const parts = cronPartsOf(now, this.getCronFormatter())
+        for (const state of this.jobs.values()) {
+          if (typeof state.definition.schedule !== 'string') continue
+          if (state.info.status === 'disabled' || state.running) continue
+          try {
+            const matcher = parseCron(state.definition.schedule)
+            if (matcher(parts)) void this.runJob(state)
+          } catch (err) {
+            console.error(`[nixxie/jobs] Invalid cron for "${state.definition.name}":`, err)
+          }
+        }
+      }
+      scheduleNext()
+    }
+
+    scheduleNext()
+  }
+
+  private async runJob(state: JobState): Promise<void> {
+    if (state.running || this.closed) return
+
+    state.running = true
+    state.info.status = 'running'
+    const start = Date.now()
+    const scheduledAt = new Date()
+
+    const run = Promise.resolve(state.definition.handler({ jobId: state.definition.name, scheduledAt }))
+
+    try {
+      const timeoutMs = state.definition.timeout
+
+      if (timeoutMs) {
+        let timer: ReturnType<typeof setTimeout> | undefined
+        try {
+          await Promise.race([
+            run,
+            new Promise<never>((_, reject) => {
+              timer = setTimeout(
+                () => reject(new Error(`Job "${state.definition.name}" timed out after ${timeoutMs}ms`)),
+                timeoutMs
+              )
+            }),
+          ])
+        } finally {
+          if (timer) clearTimeout(timer)
+        }
+      } else {
+        await run
+      }
+
+      state.info.status = 'idle'
+      state.info.lastRun = new Date()
+      state.info.runs++
+      state.info.lastError = undefined
+
+      this.config.onComplete?.(state.definition.name, Date.now() - start)
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err))
+      state.info.status = 'error'
+      state.info.lastRun = new Date()
+      state.info.lastError = error.message
+
+      this.config.onError?.(state.definition.name, error)
+      console.error(`[nixxie/jobs] Job "${state.definition.name}" failed:`, error)
+    } finally {
+      // Release the overlap lock only once the handler actually settles. On timeout we stopped
+      // *waiting* for it, but it may still be running in the background — releasing synchronously
+      // would let the next tick start a second concurrent run. (Normally `run` is already settled.)
+      void run
+        .catch(() => {})
+        .then(() => {
+          state.running = false
+          if (!this.closed) state.info.nextRun = this.computeNextRun(state)
+        })
+    }
+  }
+
+  private clearTimer(state: JobState): void {
+    if (state.timer) {
+      clearInterval(state.timer as ReturnType<typeof setInterval>)
+      state.timer = null
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+import type { JobsConfig } from './types'
+import { JobsService } from './JobsService'
+
+export function createJobs(config: JobsConfig = {}): JobsService {
+  return new JobsService(config)
+}
+
+export { JobsService }
+export type { JobsConfig } from './types'
+export type { NixxieJobDefinition, NixxieJobInfo, NixxieJobsService } from '@nixxie-cms/core'

package/src/types.ts

@@ -0,0 +1,33 @@
+import type { NixxieJobDefinition, NixxieJobInfo, NixxieJobsService } from '@nixxie-cms/core'
+
+export type { NixxieJobDefinition, NixxieJobInfo, NixxieJobsService }
+
+export type JobsConfig = {
+  /**
+   * Job definitions to register on start.
+   * Can also be registered later via `service.define()`.
+   */
+  jobs?: NixxieJobDefinition[]
+
+  /**
+   * Timezone to use for cron expression evaluation.
+   * Defaults to the system timezone.
+   */
+  timezone?: string
+
+  /**
+   * How long (ms) to wait for in-flight jobs to finish on close().
+   * @default 5000
+   */
+  shutdownTimeout?: number
+
+  /**
+   * Called when a job throws an error.
+   */
+  onError?: (name: string, error: Error) => void
+
+  /**
+   * Called after each successful job execution.
+   */
+  onComplete?: (name: string, duration: number) => void
+}