@contractspec/lib.jobs 0.0.0-canary-20260113162409

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+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,126 @@
+# @contractspec/lib.jobs
+
+Website: https://contractspec.io/
+
+
+Background jobs and scheduler module for ContractSpec applications.
+
+## Purpose
+
+Provides a generic system for asynchronous and scheduled work. Supports multiple queue backends (memory, Redis, GCP Cloud Tasks) and cron-like scheduling for recurring jobs.
+
+## Features
+
+- **Job Queue**: Async job processing with retry policies
+- **Scheduler**: Cron-like scheduling for recurring jobs
+- **Multiple Backends**: Memory, Redis, GCP Cloud Tasks, GCP Pub/Sub
+- **Type Safety**: Typed job definitions with Zod schemas
+- **Dead Letter Queue**: Automatic handling of failed jobs
+- **Entity Specs**: Prisma schema generation for job persistence
+
+## Installation
+
+```bash
+bun add @contractspec/lib.jobs
+```
+
+## Usage
+
+### Define a Job Type
+
+```typescript
+import { defineJobType } from '@contractspec/lib.jobs';
+import * as z from "zod";
+
+const SendEmailJob = defineJobType({
+  type: 'email.send',
+  version: '1.0.0',
+  payload: z.object({
+    to: z.string().email(),
+    subject: z.string(),
+    body: z.string(),
+  }),
+  options: {
+    maxRetries: 3,
+    backoffMs: 5000,
+    timeoutMs: 30000,
+  },
+});
+```
+
+### Create a Queue
+
+```typescript
+import { MemoryJobQueue, RedisJobQueue } from '@contractspec/lib.jobs/queue';
+
+// In-memory for development
+const queue = new MemoryJobQueue();
+
+// Redis for production
+const queue = new RedisJobQueue({
+  redis: redisClient,
+  prefix: 'jobs:',
+});
+```
+
+### Enqueue and Process Jobs
+
+```typescript
+// Enqueue
+await queue.enqueue('email.send', {
+  to: 'user@example.com',
+  subject: 'Welcome!',
+  body: 'Thanks for signing up.',
+});
+
+// Register handler
+queue.register('email.send', async (job) => {
+  await sendEmail(job.payload);
+});
+
+// Start processing
+queue.start();
+```
+
+### Schedule Recurring Jobs
+
+```typescript
+import { JobScheduler } from '@contractspec/lib.jobs/scheduler';
+
+const scheduler = new JobScheduler(queue);
+
+// Run daily at midnight
+scheduler.schedule('daily-cleanup', '0 0 * * *', async () => {
+  await cleanupOldRecords();
+});
+
+// Run every 5 minutes
+scheduler.schedule('sync-data', '*/5 * * * *', async () => {
+  await syncExternalData();
+});
+
+scheduler.start();
+```
+
+## Entity Specs (for schema generation)
+
+```typescript
+import { jobsSchemaContribution } from '@contractspec/lib.jobs/entities';
+
+// Use in schema composition
+const config = {
+  modules: [jobsSchemaContribution],
+};
+```
+
+## Events
+
+| Event | Trigger |
+|-------|---------|
+| job.enqueued | Job added to queue |
+| job.started | Job processing started |
+| job.completed | Job finished successfully |
+| job.failed | Job failed after retries |
+| job.retrying | Job is being retried |
+| scheduler.tick | Scheduler checked for due jobs |
+

package/dist/_virtual/rolldown_runtime.js

@@ -0,0 +1,36 @@
+//#region rolldown:runtime
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __exportAll = (all, symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+
+//#endregion
+export { __exportAll, __reExport };