@kitr/jobs 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Platon Podkopov
+
+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

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @kitr/jobs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Jobs.** Run work in the background or on a schedule, with retries when it fails.
+
+```sh
+pnpm kitr add jobs
+```
+
+`kitr add` installs the package and wires it into your app: the provider in `kitrrc.ts`, its config file and its `AGENTS.md` section. Import it from `@kitr/jobs`.
+
+Read the guide at https://kitr.dev/packages/jobs.
+
+Part of [kitr](https://kitr.dev), the TypeScript framework where everything is an add-on. MIT licensed.

package/dist/commands-Bo7c-TIC.d.ts

@@ -0,0 +1,89 @@
+declare namespace commands_d_exports {
+  export { _default as default, list, loadApp, work };
+}
+declare const list: {
+  meta: {
+    name: string;
+    description: string;
+  };
+  args: {
+    json: {
+      type: string;
+      description: string;
+      default: boolean;
+    };
+  };
+  run({ args }: {
+    args: {
+      json: boolean;
+    };
+  }): Promise<void>;
+};
+interface BootableApp {
+  boot(): Promise<unknown>;
+  container: {
+    use(name: string): unknown;
+  };
+}
+/**
+ * The app behind a server entry. The generated server/main.ts exports `server`, whose `app` is
+ * the one to boot; an entry may also export `app` itself.
+ */
+declare function loadApp(root: string, entry: string): Promise<BootableApp>;
+declare const work: {
+  meta: {
+    name: string;
+    description: string;
+  };
+  args: {
+    entry: {
+      type: string;
+      description: string;
+      default: string;
+    };
+  };
+  run({ args }: {
+    args: {
+      entry: string;
+    };
+  }): Promise<void>;
+};
+declare const _default: {
+  'jobs:list': {
+    meta: {
+      name: string;
+      description: string;
+    };
+    args: {
+      json: {
+        type: string;
+        description: string;
+        default: boolean;
+      };
+    };
+    run({ args }: {
+      args: {
+        json: boolean;
+      };
+    }): Promise<void>;
+  };
+  'jobs:work': {
+    meta: {
+      name: string;
+      description: string;
+    };
+    args: {
+      entry: {
+        type: string;
+        description: string;
+        default: string;
+      };
+    };
+    run({ args }: {
+      args: {
+        entry: string;
+      };
+    }): Promise<void>;
+  };
+};
+export { work as a, loadApp as i, commands_d_exports as n, list as r, _default as t };

package/dist/commands.d.ts

@@ -0,0 +1,2 @@
+import { a as work, i as loadApp, r as list, t as _default } from "./commands-Bo7c-TIC.js";
+export { _default as default, list, loadApp, work };

package/dist/commands.js

@@ -0,0 +1,103 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+// src/commands.ts
+/**
+* `kitr jobs:list` and `kitr jobs:work`. Plain command objects (citty's shape) so this module
+* needs no CLI dependency; the kitr CLI mounts them when `@kitr/jobs` is in kitrrc.ts.
+*/
+async function loadJobsConfig(root) {
+	const file = [
+		"config/jobs.ts",
+		"config/jobs.js",
+		"config/jobs.mts"
+	].map((f) => resolve(root, f)).find(existsSync);
+	if (!file) throw new Error("No config/jobs.ts in this project. Run `kitr add jobs`.");
+	const { createJiti } = await import("jiti");
+	const mod = await createJiti(file, {
+		interopDefault: true,
+		alias: aliases(root)
+	}).import(file);
+	return {
+		file,
+		jobs: (mod.default ?? mod).jobs ?? []
+	};
+}
+function aliases(root) {
+	const out = {};
+	try {
+		const ts = JSON.parse(readFileSync(resolve(root, "tsconfig.json"), "utf8"));
+		for (const [k, v] of Object.entries(ts.compilerOptions?.paths ?? {})) out[k.replace("/*", "")] = resolve(root, v[0].replace("/*", ""));
+	} catch {}
+	return out;
+}
+const list = {
+	meta: {
+		name: "jobs:list",
+		description: "List the jobs in config/jobs.ts with their retries and schedules."
+	},
+	args: { json: {
+		type: "boolean",
+		description: "Print as JSON",
+		default: false
+	} },
+	async run({ args }) {
+		const { jobs } = await loadJobsConfig(process.cwd());
+		const rows = jobs.map((j) => ({
+			name: j.name,
+			retries: j.retries ?? 3,
+			timeout: j.timeout ?? 6e4,
+			schedule: typeof j.schedule === "string" ? j.schedule : j.schedule ? `every ${j.schedule.every}` : ""
+		}));
+		if (args.json) return console.log(JSON.stringify(rows, null, 2));
+		if (!rows.length) return console.log("No jobs in config/jobs.ts. `kitr make:job <name>` writes one.");
+		const w = Math.max(...rows.map((r) => r.name.length), 4);
+		console.log(`${"name".padEnd(w)}  retries  timeout  schedule`);
+		for (const r of rows) console.log(`${r.name.padEnd(w)}  ${String(r.retries).padEnd(7)}  ${String(r.timeout).padEnd(7)}  ${r.schedule}`);
+	}
+};
+/**
+* The app behind a server entry. The generated server/main.ts exports `server`, whose `app` is
+* the one to boot; an entry may also export `app` itself.
+*/
+async function loadApp(root, entry) {
+	const file = resolve(root, entry);
+	if (!existsSync(file)) throw new Error(`${entry} not found`);
+	const { createJiti } = await import("jiti");
+	const mod = await createJiti(file, {
+		interopDefault: false,
+		alias: aliases(root)
+	}).import(file);
+	const app = mod.app ?? mod.server?.app ?? mod.default?.app;
+	if (!app) throw new Error(`${entry} exports neither \`server\` nor \`app\``);
+	return app;
+}
+const work = {
+	meta: {
+		name: "jobs:work",
+		description: "Run the job worker in this process (for `worker: false` setups). Boots the app from server/main.ts and drains the queue until stopped."
+	},
+	args: { entry: {
+		type: "string",
+		description: "The server entry that exports `server` (or `app`). Default server/main.ts",
+		default: "server/main.ts"
+	} },
+	async run({ args }) {
+		const app = await loadApp(process.cwd(), args.entry);
+		await app.boot();
+		const jobs = app.container.use("jobs");
+		jobs.start();
+		console.log("jobs worker running (ctrl-c to stop)");
+		await new Promise((done) => {
+			const stop = () => {
+				jobs.stop().then(done, done);
+			};
+			process.once("SIGINT", stop);
+			process.once("SIGTERM", stop);
+		});
+	}
+};
+var commands_default = {
+	"jobs:list": list,
+	"jobs:work": work
+};
+export { commands_default as default, list, loadApp, work };

package/dist/index.d.ts

@@ -0,0 +1,187 @@
+import { KitrApp, StandardSchemaV1 } from "@kitr/core";
+/** The second argument of a job's `run`: the app, the attempt number, the job id and an abort signal. */
+export interface JobContext {
+  /** The app, for the container and services such as `useMailer(app)`. */
+  app: KitrApp;
+  /** 1 on the first run, then one more per retry. */
+  attempt: number;
+  /** The id `dispatch()` returned; the same across retries. */
+  jobId: string;
+  /** Aborts when the attempt passes its `timeout`; pass it to fetch and database calls. */
+  signal: AbortSignal;
+}
+/** What `defineJob` takes: the work, plus its schema, retries, backoff, timeout and schedule. */
+export interface JobOptions<Payload> {
+  /** Validates the payload when dispatched and when a queue driver hands it back. */
+  schema?: StandardSchemaV1<unknown, Payload>;
+  /** Retries after a failure. Default 3. */
+  retries?: number;
+  /** Milliseconds before the first retry, doubled each time. Default 1000. */
+  backoff?: number;
+  /** Milliseconds a run may take before it is aborted. Default 60 000. */
+  timeout?: number;
+  /** Run on a schedule: a 5-field cron expression or an `every` interval such as `'5m'`, `'1h'`. */
+  schedule?: string | {
+    every: string;
+  };
+  /** The work. Throw to fail the attempt; the return value is what `jobs.run()` resolves with. */
+  run(payload: Payload, ctx: JobContext): Promise<unknown> | unknown;
+}
+/** A job made by `defineJob`: its options plus the name the queue refers to it by. */
+export interface Job<Payload = unknown> extends JobOptions<Payload> {
+  /** Identifies the job in the queue; keep it stable across deploys. */
+  name: string;
+  /** The payload type, for inference only. */
+  readonly __payload?: Payload;
+}
+/** Declare a background job. List it in `config/jobs.ts`, then queue it with `useJobs(app).dispatch(job, payload)`. */
+export declare function defineJob<Payload = void>(name: string, options: JobOptions<Payload>): Job<Payload>;
+/** A job waiting in the queue, as drivers store it and `onFailed` receives it. */
+export interface QueuedJob {
+  /** The id `dispatch()` returned. */
+  id: string;
+  /** The job's name. */
+  name: string;
+  /** The payload as validated at dispatch; must survive JSON for shared drivers. */
+  payload: unknown;
+  /** 1 for the first run, one more per retry. */
+  attempt: number;
+  /** ms epoch when it may run. */
+  runAt: number;
+}
+/** Where queued work waits. The memory driver is the default; Redis or a table are a few methods. */
+export interface JobsDriver {
+  /** Identifies the driver, such as `memory` or `redis`. */
+  name: string;
+  /** Store a job; called by `dispatch()` and for each retry. */
+  push(job: QueuedJob): Promise<void>;
+  /**
+   * Jobs whose `runAt` has passed. A driver that implements `ack` should only reserve them here
+   * (hide them from other workers) and delete them in `ack`, so a worker that dies mid-job leaves
+   * the job to be picked up again. Without `ack`, pulled jobs are gone from the queue.
+   */
+  pull(now: number, limit: number): Promise<QueuedJob[]>;
+  /** Called once a pulled job is done with: it ran, it failed for good, or its retry was queued. */
+  ack?(job: QueuedJob): Promise<void>;
+  /** How many jobs are waiting or running: queued plus reserved (pulled, not yet acked). */
+  size(): Promise<number>;
+  /** Remove every waiting job. */
+  clear(): Promise<void>;
+  /**
+   * Take a lock named `key` for `ttlMs`, resolving true for the one caller that got it. Workers
+   * call it before queuing a scheduled job, so with several workers each cron minute and each
+   * `every` interval queues the job once. Without it, every worker queues its own copy: right
+   * for one process, a duplicate per extra worker otherwise.
+   */
+  claim?(key: string, ttlMs: number): Promise<boolean>;
+}
+/** The options in `config/jobs.ts`. */
+export interface JobsConfig {
+  /** Jobs the worker knows about (`server/jobs/*.ts`). Dispatching by object registers on the fly. */
+  jobs?: Job<any>[];
+  /** Where queued jobs wait. Default: the in-memory driver, lost on restart. */
+  driver?: JobsDriver;
+  /** Jobs run at once per process. Default 5. */
+  concurrency?: number;
+  /** Milliseconds between queue polls. Default 500. */
+  pollInterval?: number;
+  /** Start the worker when the server starts. Default true; set false for a separate worker process. */
+  worker?: boolean;
+  /** Called when a job has used up its retries. */
+  onFailed?: (job: QueuedJob, error: unknown) => void;
+}
+/** The third argument of `dispatch()`: when the job may run. */
+export interface DispatchOptions {
+  /** Milliseconds from now. */
+  delay?: number;
+  /** A fixed time instead. */
+  at?: Date;
+}
+/** The service the provider binds as `jobs`: queue, run and schedule jobs, and control the worker. */
+export interface Jobs {
+  /** Add jobs after creation, checking their schedules. Returns the service for chaining. */
+  register(...jobs: Job<any>[]): Jobs;
+  /** Validate the payload and queue the job; resolves with its id. */
+  dispatch<P>(job: Job<P>, payload: P, options?: DispatchOptions): Promise<string>;
+  /** Run a job now, in this process, with retries; what the worker does. */
+  run<P>(job: Job<P>, payload: P, attempt?: number): Promise<unknown>;
+  /** Start polling the queue and dispatching scheduled jobs. Idempotent. */
+  start(): void;
+  /** Stop polling and wait for running jobs to settle. */
+  stop(): Promise<void>;
+  /** Whether the worker is polling. */
+  readonly running: boolean;
+  /** The queue driver. */
+  readonly driver: JobsDriver;
+  /** Known jobs by name. */
+  readonly jobs: ReadonlyMap<string, Job<any>>;
+}
+declare module '@kitr/core' {
+  interface ConfigRegistry {
+    jobs: JobsConfig;
+  }
+  interface ContainerBindings {
+    jobs: Jobs;
+  }
+}
+/** Types `config/jobs.ts`. Returns its argument unchanged. */
+export declare const defineConfig: <const C extends JobsConfig>(config: C) => C;
+/** Options for `createMemoryJobsDriver`. */
+export interface MemoryJobsDriverOptions {
+  /**
+   * Milliseconds a pulled job stays reserved. A job the worker never acks (its run is stuck, or
+   * the worker loop died and was restarted in this process) goes back to the queue after this.
+   * Keep it above your longest job `timeout`, or a slow job runs twice. Default 30 000.
+   */
+  visibilityTimeout?: number;
+}
+/**
+ * The default driver: an in-process queue sorted by `runAt`. Lost on restart and not shared between
+ * processes; use `createRedisJobsDriver` for that. A pulled job is reserved, not removed: it
+ * counts in `size()` until the worker acks it, and returns to the queue if that takes longer than
+ * `visibilityTimeout`.
+ */
+export declare function createMemoryJobsDriver(options?: MemoryJobsDriverOptions): JobsDriver;
+/**
+ * The part of an [ioredis](https://github.com/redis/ioredis) client the Redis jobs driver uses.
+ * An ioredis `Redis` fits as it is.
+ */
+export interface RedisJobsClient {
+  hset(key: string, field: string, value: string): Promise<number>;
+  hget(key: string, field: string): Promise<string | null>;
+  hdel(key: string, ...fields: string[]): Promise<number>;
+  zadd(key: string, score: number, member: string): Promise<number | string>;
+  zrem(key: string, ...members: string[]): Promise<number>;
+  zrangebyscore(key: string, min: number | string, max: number | string, limit: 'LIMIT', offset: number, count: number): Promise<string[]>;
+  zcard(key: string): Promise<number>;
+  del(...keys: string[]): Promise<number>;
+  set(key: string, value: string, px: 'PX', ms: number, nx: 'NX'): Promise<string | null>;
+}
+/** Options for `createRedisJobsDriver`. */
+export interface RedisJobsDriverOptions {
+  /** Prepended to the driver's keys, so apps sharing a Redis keep separate queues. Default `kitr:jobs:`. */
+  prefix?: string;
+  /**
+   * Milliseconds a pulled job stays hidden from other workers. A worker that dies mid-job leaves
+   * it to be picked up again after this. Keep it above your longest job `timeout`, or a slow
+   * job runs twice. Default 300 000 (5 minutes).
+   */
+  visibilityTimeout?: number;
+}
+/**
+ * A durable queue over Redis, shared by every worker. Each due job goes to exactly one worker:
+ * pulling moves it from the queue to a reserved set, and only the worker whose `ZREM` succeeds
+ * runs it. A job whose worker dies returns to the queue after `visibilityTimeout`. Scheduled
+ * jobs queue once per run however many workers poll, through `claim`.
+ *
+ *   driver: createRedisJobsDriver(new Redis(process.env.REDIS_URL))
+ */
+export declare function createRedisJobsDriver(redis: RedisJobsClient, options?: RedisJobsDriverOptions): JobsDriver;
+/** Parse an interval such as `'30s'`, `'5m'` or `'1.5h'` into milliseconds (`'5m'` → 300000). Throws on anything else. */
+export declare function parseInterval(text: string): number;
+/** Does a 5-field cron expression (minute hour day month weekday) match this minute? */
+export declare function cronMatches(expression: string, date: Date): boolean;
+/** Create the jobs service without the provider, for scripts and tests. Takes the same options as `config/jobs.ts`. */
+export declare function createJobs(app: KitrApp, config?: JobsConfig): Jobs;
+/** The jobs service the provider bound in this app's container. Throws in the browser, where nothing is bound. */
+export declare function useJobs(app: KitrApp): Jobs;