bree-plugin-one-time 1.0.0

package/README.md

@@ -0,0 +1,77 @@
+# bree-plugin-one-time
+
+Persistent one-time job scheduling for [Bree](https://github.com/breejs/bree). Jobs added with a `date` property are automatically saved to a JSON queue file and restored on scheduler restart — so they survive process restarts.
+
+## The problem
+
+Bree natively supports one-time jobs via the `date` property, but they only live in memory. If your scheduler process restarts before the job fires, the job is silently lost.
+
+## The solution
+
+This plugin wraps `Bree.prototype.add` to detect date-based jobs and persist them to a local JSON file. On `init`, it reads the file and re-registers any jobs that haven't fired yet. On job completion, the entry is removed from the file automatically.
+
+## Install
+
+```sh
+npm install bree-plugin-one-time
+```
+
+## Usage
+
+```js
+const Bree = require('bree');
+const oneTime = require('bree-plugin-one-time');
+
+Bree.extend(oneTime, {
+  queueFile: './jobs/one-time-queue.json', // optional, default: cwd/.bree-one-time-queue.json
+  verbose: true,                            // optional, default: false
+});
+
+const bree = new Bree({ jobs: [] });
+await bree.init();
+await bree.start();
+
+// Schedule a one-time job — automatically persisted
+bree.add({
+  name: 'send-flight-reminder',
+  path: './jobs/discord-ping.cjs',
+  date: new Date('2026-04-12T13:17:00-04:00'),
+  env: {
+    DISCORD_CHANNEL_ID: '1234567890',
+    DISCORD_USER_ID: '279033205628207104',
+    MESSAGE: 'Check in to AA 5838 SAV → PHL — confirmation KJEVBS',
+  },
+});
+```
+
+If the scheduler restarts before `2026-04-12T13:17:00`, the job is restored from the queue file and will still fire on time.
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `queueFile` | `string` | `cwd/.bree-one-time-queue.json` | Path to the JSON queue file |
+| `verbose` | `boolean` | `false` | Log queue operations to console |
+
+## How it works
+
+1. **`add`** — wraps `Bree.prototype.add`. Any job with a `date` property is written to the queue file before being passed to Bree.
+2. **`init`** — wraps `Bree.prototype.init`. After initialization, reads the queue file, skips expired jobs, re-registers future jobs with Bree.
+3. **`start`** — wraps `Bree.prototype.start`. Attaches a `worker deleted` listener to remove completed jobs from the queue file.
+
+## Queue file format
+
+```json
+[
+  {
+    "name": "send-flight-reminder",
+    "path": "./jobs/discord-ping.cjs",
+    "date": "2026-04-12T17:17:00.000Z",
+    "worker": null,
+    "env": {
+      "DISCORD_CHANNEL_ID": "1234567890",
+      "MESSAGE": "Check in to your flight!"
+    }
+  }
+]
+```

package/index.d.ts

@@ -0,0 +1,12 @@
+import Bree from 'bree';
+
+export interface OneTimePluginOptions {
+  /** Path to the JSON queue file. Default: cwd/.bree-one-time-queue.json */
+  queueFile?: string;
+  /** Log queue operations to console. Default: false */
+  verbose?: boolean;
+}
+
+declare function oneTimePlugin(options: OneTimePluginOptions, Bree: typeof Bree): void;
+
+export = oneTimePlugin;

package/index.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * bree-plugin-one-time
+ *
+ * Persistent one-time job scheduling for Bree. Jobs added with a `date`
+ * property are automatically saved to a JSON queue file and restored on
+ * scheduler restart, so they survive process restarts.
+ *
+ * Usage:
+ *   const Bree = require('bree');
+ *   const oneTime = require('bree-plugin-one-time');
+ *   Bree.extend(oneTime, { queueFile: './one-time-queue.json' });
+ *
+ * Then add jobs as normal — any job with a `date` property is auto-persisted:
+ *   bree.add({ name: 'my-job', path: './jobs/my-job.cjs', date: new Date('2026-04-12T13:17:00-04:00') });
+ *
+ * Options:
+ *   Bree.extend(oneTime, {
+ *     queueFile: './one-time-queue.json',  // Path to queue file (default: cwd/.bree-one-time-queue.json)
+ *     verbose: false,                      // Log queue operations (default: false)
+ *   });
+ */
+
+module.exports = function oneTimePlugin(options, Bree) {
+  const opts = {
+    queueFile: path.join(process.cwd(), '.bree-one-time-queue.json'),
+    verbose: false,
+    ...options
+  };
+
+  // ── Queue persistence helpers ──────────────────────────────────────────────
+
+  function loadQueue() {
+    try {
+      const raw = fs.readFileSync(opts.queueFile, 'utf8');
+      return JSON.parse(raw);
+    } catch {
+      return [];
+    }
+  }
+
+  function saveQueue(queue) {
+    fs.writeFileSync(opts.queueFile, JSON.stringify(queue, null, 2));
+  }
+
+  function addToQueue(job) {
+    const queue = loadQueue().filter(j => j.name !== job.name);
+    queue.push({
+      name: job.name,
+      path: job.path || null,
+      date: job.date instanceof Date ? job.date.toISOString() : job.date,
+      worker: job.worker || null,
+      env: job.env || null,
+    });
+    saveQueue(queue);
+    if (opts.verbose) console.log(`[bree-plugin-one-time] queued: ${job.name} at ${job.date}`);
+  }
+
+  function removeFromQueue(name) {
+    const queue = loadQueue().filter(j => j.name !== name);
+    saveQueue(queue);
+    if (opts.verbose) console.log(`[bree-plugin-one-time] dequeued: ${name}`);
+  }
+
+  // ── Wrap Bree.prototype.add ────────────────────────────────────────────────
+  // Intercept jobs with a `date` property and persist them before adding to Bree.
+
+  const originalAdd = Bree.prototype.add;
+
+  Bree.prototype.add = function (jobs) {
+    const jobsArr = Array.isArray(jobs) ? jobs : [jobs];
+
+    for (const job of jobsArr) {
+      if (job && typeof job === 'object' && job.date) {
+        addToQueue(job);
+      }
+    }
+
+    return originalAdd.call(this, jobs);
+  };
+
+  // ── Wrap Bree.prototype.init ───────────────────────────────────────────────
+  // On startup, restore any persisted jobs that haven't fired yet.
+
+  const originalInit = Bree.prototype.init;
+
+  Bree.prototype.init = async function () {
+    const result = await originalInit.call(this);
+
+    const queue = loadQueue();
+    const now = Date.now();
+    const stillValid = [];
+
+    for (const job of queue) {
+      const fireAt = new Date(job.date).getTime();
+
+      if (isNaN(fireAt)) {
+        if (opts.verbose) console.log(`[bree-plugin-one-time] invalid date, skipping: ${job.name}`);
+        continue;
+      }
+
+      if (fireAt <= now) {
+        if (opts.verbose) console.log(`[bree-plugin-one-time] already past, skipping: ${job.name} (was ${job.date})`);
+        continue;
+      }
+
+      // Re-register with Bree using native date-based scheduling
+      const restored = {
+        name: job.name,
+        date: new Date(job.date),
+        ...(job.path && { path: job.path }),
+        ...(job.worker && { worker: job.worker }),
+        ...(job.env && { env: job.env }),
+      };
+
+      try {
+        await originalAdd.call(this, restored);
+        stillValid.push(job);
+        if (opts.verbose) console.log(`[bree-plugin-one-time] restored: ${job.name} fires at ${job.date}`);
+      } catch (err) {
+        console.error(`[bree-plugin-one-time] failed to restore ${job.name}:`, err.message);
+      }
+    }
+
+    // Rewrite queue with only still-valid jobs
+    saveQueue(stillValid);
+
+    return result;
+  };
+
+  // ── Wrap Bree.prototype.start ──────────────────────────────────────────────
+  // After start, listen for job completion to clean up the queue file.
+
+  const originalStart = Bree.prototype.start;
+
+  Bree.prototype.start = async function () {
+    // `worker deleted` fires when a worker thread finishes (success or error)
+    this.on('worker deleted', (name) => {
+      const queue = loadQueue();
+      const wasOneTime = queue.some(j => j.name === name);
+      if (wasOneTime) {
+        removeFromQueue(name);
+      }
+    });
+
+    return originalStart.call(this);
+  };
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "bree-plugin-one-time",
+  "version": "1.0.0",
+  "description": "Persistent one-time job scheduling for Bree — jobs with a date property survive scheduler restarts",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "scripts": {
+    "test": "node test/index.js"
+  },
+  "keywords": [
+    "bree",
+    "bree-plugin",
+    "scheduler",
+    "one-time",
+    "cron",
+    "job-queue",
+    "persistent"
+  ],
+  "author": "Alex Hillman <alex@indyhall.org>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexknowshtml/bree-plugin-one-time.git"
+  },
+  "peerDependencies": {
+    "bree": ">=9.0.0"
+  }
+}