@nwire/cron 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+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,66 @@
+# @nwire/cron
+
+> Scheduled-trigger interface — fires actions on a cron expression.
+
+## What it does
+
+A small wire that ticks named cron expressions and dispatches Nwire actions against the right app. Each tick seeds a fresh envelope; correlation/causation propagate through any chained dispatches. Built on [`croner`](https://github.com/Hexagon/croner). For multi-process deployments run cron in ONE process (typically the worker wire) — replicating it fires each job N times.
+
+## Install
+
+```bash
+pnpm add @nwire/cron
+```
+
+## Quick start
+
+```ts
+import { createCronWire } from "@nwire/cron";
+import { apps } from "@amit/learnflow";
+
+createCronWire({
+  apps,
+  schedule: {
+    "0 2 * * *": "submissions.reprocess-stale",
+    "*/15 * * * *": { action: "mastery.recompute" },
+    "0 9 * * 1": { action: "reports.weekly", input: { audience: "admins" } },
+  },
+}).start();
+```
+
+## API surface
+
+- `createCronWire({ apps, schedule, logger? })` — boot the cron wire.
+- `CronScheduleEntry` — `string` shortcut (action name) or `{ action, input? }`.
+
+## When to use
+
+Whenever you need time-based triggers — nightly aggregations, weekly reports, periodic syncs. Fits L3 and up.
+
+## Standalone use
+
+For developers using `@nwire/cron` **without the rest of Nwire** — pair it with any TypeScript project, any container, any HTTP framework.
+
+```ts
+// See the package's main entry (src/) for the standalone surface.
+// The exports below work without @nwire/app or @nwire/forge.
+import {} from /* ...standalone exports... */ "@nwire/cron";
+```
+
+## Within nwire-app
+
+For developers using this package as part of the Nwire stack — register it via `app.use(...)` or it auto-wires when you compose `createApp({ modules })`.
+
+```ts
+import { createApp } from "@nwire/forge";
+
+const app = createApp({
+  /* ...config... */
+});
+// Adapter/plugin wiring happens here when applicable.
+```
+
+## See also
+
+- [Architecture sketch §05 — Adapters tier](../../architecture-sketch.html#packages)
+- Sibling packages: [@nwire/queue](../nwire-queue), [@nwire/forge](../nwire-forge)

package/dist/cron.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `@nwire/cron` — scheduled-trigger interface for Nwire apps.
+ *
+ * Ticks a cron expression and dispatches the named action against the
+ * owning app. Fresh envelope per tick; correlation/causation propagate
+ * through chained dispatches. Built on `croner`. For multi-process
+ * deployments run cron in ONE process.
+ *
+ * See: architecture-sketch.html §05 (Adapters tier).
+ */
+import { Cron } from "croner";
+import type { AppDefinition, App } from "@nwire/forge";
+export type CronScheduleEntry = string | {
+    readonly action: string;
+    readonly input?: unknown;
+    readonly tenant?: string;
+};
+export interface CronWireOptions {
+    /** Apps to host. Cron locates which app owns each action by name. */
+    readonly apps: readonly AppDefinition[];
+    /** Pre-instantiated `App`s (for tests where stores are injected). */
+    readonly appInstances?: readonly App[];
+    /**
+     * Schedule: keys are cron expressions, values are action names or full specs.
+     * Examples: `0 2 * * *` (daily 02:00), `@hourly` (Croner shortcuts supported).
+     */
+    readonly schedule: Readonly<Record<string, CronScheduleEntry>>;
+    /** Timezone (IANA) for evaluating cron expressions. Default: process default. */
+    readonly timezone?: string;
+}
+export interface CronWire {
+    readonly apps: readonly App[];
+    /** Active Cron handles (for inspection / testing). */
+    readonly schedules: readonly Cron[];
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare function createCronWire(options: CronWireOptions): CronWire;
+//# sourceMappingURL=cron.d.ts.map

package/dist/cron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.d.ts","sourceRoot":"","sources":["../src/cron.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGvD,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN;IACE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;IACxC,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,GAAG,EAAE,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC/D,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,EAAE,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,SAAS,IAAI,EAAE,CAAC;IACpC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CAiCjE"}

package/dist/cron.js

@@ -0,0 +1,61 @@
+/**
+ * `@nwire/cron` — scheduled-trigger interface for Nwire apps.
+ *
+ * Ticks a cron expression and dispatches the named action against the
+ * owning app. Fresh envelope per tick; correlation/causation propagate
+ * through chained dispatches. Built on `croner`. For multi-process
+ * deployments run cron in ONE process.
+ *
+ * See: architecture-sketch.html §05 (Adapters tier).
+ */
+import { Cron } from "croner";
+import { seedEnvelope } from "@nwire/envelope";
+export function createCronWire(options) {
+    const instances = options.appInstances?.slice() ?? options.apps.map((def) => def.create());
+    const schedules = [];
+    return {
+        apps: instances,
+        schedules,
+        async start() {
+            await Promise.all(instances.map((a) => a.start()));
+            for (const [expr, entry] of Object.entries(options.schedule)) {
+                const spec = typeof entry === "string" ? { action: entry, input: {} } : entry;
+                const owner = instances.find((a) => actionNames(a).includes(spec.action));
+                if (!owner) {
+                    throw new Error(`@nwire/cron: action "${spec.action}" not found in any registered app`);
+                }
+                const action = findAction(owner, spec.action);
+                if (!action)
+                    continue;
+                const cron = new Cron(expr, { timezone: options.timezone, protect: true }, async () => {
+                    const envelope = seedEnvelope({ tenant: spec.tenant });
+                    await owner.runtime.dispatch(action, spec.input ?? {}, envelope);
+                });
+                schedules.push(cron);
+            }
+        },
+        async stop() {
+            for (const c of schedules)
+                c.stop();
+            schedules.length = 0;
+        },
+    };
+}
+function actionNames(app) {
+    const names = [];
+    for (const m of app.modules) {
+        for (const a of m.manifest.actions ?? [])
+            names.push(a.name);
+    }
+    return names;
+}
+function findAction(app, name) {
+    for (const m of app.modules) {
+        for (const a of m.manifest.actions ?? []) {
+            if (a.name === name)
+                return a;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=cron.js.map

package/dist/cron.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.js","sourceRoot":"","sources":["../src/cron.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@nwire/cron",
+  "version": "0.7.0",
+  "description": "Nwire — cron interface factory. Dispatch actions on a schedule (croner-backed).",
+  "keywords": [
+    "cron",
+    "interface",
+    "nwire",
+    "scheduler",
+    "wire"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/cron.js",
+  "types": "./dist/cron.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/cron.js",
+      "types": "./dist/cron.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "croner": "^9.1.0",
+    "@nwire/forge": "0.7.0",
+    "@nwire/envelope": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}