workerstack 0.1.0-beta.0

package/dist/internal-tables.d.ts.map

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

package/dist/internal-tables.js

@@ -0,0 +1,114 @@
+import { getTableName, isTable } from 'drizzle-orm';
+import { index, integer, primaryKey, sqliteTable, text, uniqueIndex, } from 'drizzle-orm/sqlite-core';
+export const workerstackFiles = sqliteTable('bunderstack_file_meta', {
+    fileId: text('file_id').primaryKey(),
+    bucket: text('bucket').notNull(),
+    ownerId: text('owner_id'),
+    scopeJson: text('scope_json'),
+    status: text('status').notNull(),
+    filename: text('filename'),
+    contentType: text('content_type'),
+    size: integer('size'),
+    createdAt: integer('created_at').notNull(),
+    confirmedAt: integer('confirmed_at'),
+}, (t) => [
+    index('bfm_owner').on(t.ownerId),
+    index('bfm_scope').on(t.bucket, t.scopeJson),
+    index('bfm_sweep').on(t.status, t.createdAt),
+]);
+export const workerstackIdempotency = sqliteTable('_bunderstack_idempotency', {
+    key: text('key').notNull(),
+    tableName: text('table_name').notNull(),
+    bodyHash: text('body_hash').notNull(),
+    status: integer('status').notNull(),
+    response: text('response').notNull(),
+    expiresAt: integer('expires_at').notNull(),
+}, (t) => [primaryKey({ columns: [t.key, t.tableName] })]);
+export const workerstackJobs = sqliteTable('_bunderstack_jobs', {
+    id: text('id').primaryKey(),
+    type: text('type').notNull(),
+    payloadJson: text('payload_json').notNull(),
+    status: text('status').notNull(), // pending | running | succeeded | failed
+    attempts: integer('attempts').notNull().default(0),
+    runAt: integer('run_at').notNull(),
+    lockedUntil: integer('locked_until'),
+    dedupeKey: text('dedupe_key'),
+    lastError: text('last_error'),
+    createdAt: integer('created_at').notNull(),
+    finishedAt: integer('finished_at'),
+}, (t) => [
+    index('bjq_claim').on(t.status, t.runAt),
+    index('bjq_type_status').on(t.type, t.status),
+    index('bjq_type_run_at').on(t.type, t.runAt),
+    // NULL dedupe keys are distinct in both dialects, so keyless jobs never collide.
+    uniqueIndex('bjq_dedupe').on(t.type, t.dedupeKey),
+]);
+export const workerstackMessages = sqliteTable('_bunderstack_messages', {
+    id: text('id').primaryKey(),
+    channel: text('channel').notNull(),
+    kind: text('kind').notNull(),
+    provider: text('provider').notNull(),
+    credentialSource: text('credential_source').notNull(),
+    providerId: text('provider_id'),
+    status: text('status').notNull(),
+    recipientsJson: text('recipients_json').notNull(),
+    contentJson: text('content_json').notNull(),
+    error: text('error'),
+    createdAt: integer('created_at').notNull(),
+    updatedAt: integer('updated_at').notNull(),
+}, (t) => [
+    index('bmsg_created').on(t.createdAt),
+    index('bmsg_channel_status').on(t.channel, t.status, t.createdAt),
+    uniqueIndex('bmsg_provider_id').on(t.provider, t.providerId),
+]);
+export const workerstackMessageEvents = sqliteTable('_bunderstack_message_events', {
+    id: text('id').primaryKey(),
+    messageId: text('message_id')
+        .notNull()
+        .references(() => workerstackMessages.id, { onDelete: 'cascade' }),
+    externalId: text('external_id').notNull(),
+    type: text('type').notNull(),
+    detailJson: text('detail_json'),
+    occurredAt: integer('occurred_at').notNull(),
+    createdAt: integer('created_at').notNull(),
+}, (t) => [
+    uniqueIndex('bmev_external').on(t.externalId),
+    index('bmev_message_time').on(t.messageId, t.occurredAt),
+]);
+export const INTERNAL_TABLES = {
+    workerstackFiles,
+    workerstackIdempotency,
+    workerstackJobs,
+    workerstackMessages,
+    workerstackMessageEvents,
+};
+export const INTERNAL_TABLE_NAMES = new Set([
+    'bunderstack_file_meta',
+    '_bunderstack_idempotency',
+    '_bunderstack_jobs',
+    '_bunderstack_messages',
+    '_bunderstack_message_events',
+]);
+export function withInternalTables(schema) {
+    const merged = { ...schema };
+    for (const value of Object.values(schema)) {
+        if (!isTable(value))
+            continue;
+        const name = getTableName(value);
+        if (!INTERNAL_TABLE_NAMES.has(name))
+            continue;
+        if (Object.values(INTERNAL_TABLES).includes(value)) {
+            // Re-exported from workerstack/schema — already in user schema.
+            continue;
+        }
+        throw new Error(`[workerstack] table name "${name}" is reserved by workerstack`);
+    }
+    for (const [key, table] of Object.entries(INTERNAL_TABLES)) {
+        if (!(key in merged)) {
+            ;
+            merged[key] = table;
+        }
+    }
+    return merged;
+}
+//# sourceMappingURL=internal-tables.js.map

package/dist/internal-tables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-tables.js","sourceRoot":"","sources":["../src/internal-tables.ts"],"names":[],"mappings":"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","sourcesContent":["import { getTableName, isTable } from 'drizzle-orm'\nimport {\n  index,\n  integer,\n  primaryKey,\n  sqliteTable,\n  text,\n  uniqueIndex,\n} from 'drizzle-orm/sqlite-core'\n\nexport const workerstackFiles = sqliteTable(\n  'bunderstack_file_meta',\n  {\n    fileId: text('file_id').primaryKey(),\n    bucket: text('bucket').notNull(),\n    ownerId: text('owner_id'),\n    scopeJson: text('scope_json'),\n    status: text('status').notNull(),\n    filename: text('filename'),\n    contentType: text('content_type'),\n    size: integer('size'),\n    createdAt: integer('created_at').notNull(),\n    confirmedAt: integer('confirmed_at'),\n  },\n  (t) => [\n    index('bfm_owner').on(t.ownerId),\n    index('bfm_scope').on(t.bucket, t.scopeJson),\n    index('bfm_sweep').on(t.status, t.createdAt),\n  ],\n)\n\nexport const workerstackIdempotency = sqliteTable(\n  '_bunderstack_idempotency',\n  {\n    key: text('key').notNull(),\n    tableName: text('table_name').notNull(),\n    bodyHash: text('body_hash').notNull(),\n    status: integer('status').notNull(),\n    response: text('response').notNull(),\n    expiresAt: integer('expires_at').notNull(),\n  },\n  (t) => [primaryKey({ columns: [t.key, t.tableName] })],\n)\n\nexport const workerstackJobs = sqliteTable(\n  '_bunderstack_jobs',\n  {\n    id: text('id').primaryKey(),\n    type: text('type').notNull(),\n    payloadJson: text('payload_json').notNull(),\n    status: text('status').notNull(), // pending | running | succeeded | failed\n    attempts: integer('attempts').notNull().default(0),\n    runAt: integer('run_at').notNull(),\n    lockedUntil: integer('locked_until'),\n    dedupeKey: text('dedupe_key'),\n    lastError: text('last_error'),\n    createdAt: integer('created_at').notNull(),\n    finishedAt: integer('finished_at'),\n  },\n  (t) => [\n    index('bjq_claim').on(t.status, t.runAt),\n    index('bjq_type_status').on(t.type, t.status),\n    index('bjq_type_run_at').on(t.type, t.runAt),\n    // NULL dedupe keys are distinct in both dialects, so keyless jobs never collide.\n    uniqueIndex('bjq_dedupe').on(t.type, t.dedupeKey),\n  ],\n)\n\nexport const workerstackMessages = sqliteTable(\n  '_bunderstack_messages',\n  {\n    id: text('id').primaryKey(),\n    channel: text('channel').notNull(),\n    kind: text('kind').notNull(),\n    provider: text('provider').notNull(),\n    credentialSource: text('credential_source').notNull(),\n    providerId: text('provider_id'),\n    status: text('status').notNull(),\n    recipientsJson: text('recipients_json').notNull(),\n    contentJson: text('content_json').notNull(),\n    error: text('error'),\n    createdAt: integer('created_at').notNull(),\n    updatedAt: integer('updated_at').notNull(),\n  },\n  (t) => [\n    index('bmsg_created').on(t.createdAt),\n    index('bmsg_channel_status').on(t.channel, t.status, t.createdAt),\n    uniqueIndex('bmsg_provider_id').on(t.provider, t.providerId),\n  ],\n)\n\nexport const workerstackMessageEvents = sqliteTable(\n  '_bunderstack_message_events',\n  {\n    id: text('id').primaryKey(),\n    messageId: text('message_id')\n      .notNull()\n      .references(() => workerstackMessages.id, { onDelete: 'cascade' }),\n    externalId: text('external_id').notNull(),\n    type: text('type').notNull(),\n    detailJson: text('detail_json'),\n    occurredAt: integer('occurred_at').notNull(),\n    createdAt: integer('created_at').notNull(),\n  },\n  (t) => [\n    uniqueIndex('bmev_external').on(t.externalId),\n    index('bmev_message_time').on(t.messageId, t.occurredAt),\n  ],\n)\n\nexport const INTERNAL_TABLES = {\n  workerstackFiles,\n  workerstackIdempotency,\n  workerstackJobs,\n  workerstackMessages,\n  workerstackMessageEvents,\n} as const\n\nexport const INTERNAL_TABLE_NAMES: ReadonlySet<string> = new Set([\n  'bunderstack_file_meta',\n  '_bunderstack_idempotency',\n  '_bunderstack_jobs',\n  '_bunderstack_messages',\n  '_bunderstack_message_events',\n])\n\nexport function withInternalTables<TSchema extends Record<string, unknown>>(\n  schema: TSchema,\n): TSchema & typeof INTERNAL_TABLES {\n  const merged = { ...schema } as TSchema & typeof INTERNAL_TABLES\n\n  for (const value of Object.values(schema)) {\n    if (!isTable(value)) continue\n    const name = getTableName(value)\n    if (!INTERNAL_TABLE_NAMES.has(name)) continue\n\n    if (Object.values(INTERNAL_TABLES).includes(value as never)) {\n      // Re-exported from workerstack/schema — already in user schema.\n      continue\n    }\n\n    throw new Error(\n      `[workerstack] table name \"${name}\" is reserved by workerstack`,\n    )\n  }\n\n  for (const [key, table] of Object.entries(INTERNAL_TABLES)) {\n    if (!(key in merged)) {\n      ;(merged as Record<string, unknown>)[key] = table\n    }\n  }\n\n  return merged\n}\n"]}

package/dist/jobs/cron.d.ts

@@ -0,0 +1,15 @@
+export type CronField = {
+    any: boolean;
+    values: ReadonlySet<number>;
+};
+export type ParsedCron = {
+    minute: CronField;
+    hour: CronField;
+    dayOfMonth: CronField;
+    month: CronField;
+    dayOfWeek: CronField;
+};
+export declare function parseCron(expr: string): ParsedCron;
+/** Whether the minute containing `epochMs` matches, evaluated in UTC. */
+export declare function cronMatches(cron: ParsedCron, epochMs: number): boolean;
+//# sourceMappingURL=cron.d.ts.map

package/dist/jobs/cron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.d.ts","sourceRoot":"","sources":["../../src/jobs/cron.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,SAAS,GAAG;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAAE,CAAA;AAErE,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,SAAS,CAAA;IACjB,IAAI,EAAE,SAAS,CAAA;IACf,UAAU,EAAE,SAAS,CAAA;IACrB,KAAK,EAAE,SAAS,CAAA;IAChB,SAAS,EAAE,SAAS,CAAA;CACrB,CAAA;AAsCD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAkBlD;AAMD,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAWtE"}

package/dist/jobs/cron.js

@@ -0,0 +1,74 @@
+// src/jobs/cron.ts — minimal 5-field cron parser, UTC, minute granularity.
+// Supports: * , lists (a,b) , ranges (a-b) , steps (*/n, a-b/n, a/n). No
+// month/day names, no seconds field, no @-shortcuts — YAGNI for v1.
+const PART_RE = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/;
+function parseField(spec, min, max, expr) {
+    if (spec === '*')
+        return { any: true, values: new Set() };
+    const values = new Set();
+    for (const part of spec.split(',')) {
+        const m = PART_RE.exec(part);
+        if (!m)
+            throw new Error(`[workerstack] invalid cron "${expr}": "${part}"`);
+        const step = m[2] !== undefined ? Number(m[2]) : 1;
+        let lo;
+        let hi;
+        if (m[1] === '*') {
+            lo = min;
+            hi = max;
+        }
+        else if (m[1].includes('-')) {
+            const [a, b] = m[1].split('-');
+            lo = Number(a);
+            hi = Number(b);
+        }
+        else {
+            lo = Number(m[1]);
+            // "5/15" means "starting at 5, every 15" per cron convention.
+            hi = step > 1 ? max : lo;
+        }
+        if (step < 1 || lo < min || hi > max || lo > hi) {
+            throw new Error(`[workerstack] invalid cron "${expr}": "${part}"`);
+        }
+        for (let v = lo; v <= hi; v += step)
+            values.add(v);
+    }
+    return { any: false, values };
+}
+export function parseCron(expr) {
+    const parts = expr.trim().split(/\s+/);
+    if (parts.length !== 5) {
+        throw new Error(`[workerstack] invalid cron "${expr}": expected 5 fields (minute hour day-of-month month day-of-week)`);
+    }
+    const dow = parseField(parts[4], 0, 7, expr);
+    return {
+        minute: parseField(parts[0], 0, 59, expr),
+        hour: parseField(parts[1], 0, 23, expr),
+        dayOfMonth: parseField(parts[2], 1, 31, expr),
+        month: parseField(parts[3], 1, 12, expr),
+        // 7 is an alias for Sunday (0).
+        dayOfWeek: dow.any
+            ? dow
+            : { any: false, values: new Set([...dow.values].map((v) => v % 7)) },
+    };
+}
+function inField(field, value) {
+    return field.any || field.values.has(value);
+}
+/** Whether the minute containing `epochMs` matches, evaluated in UTC. */
+export function cronMatches(cron, epochMs) {
+    const d = new Date(epochMs);
+    if (!inField(cron.minute, d.getUTCMinutes()))
+        return false;
+    if (!inField(cron.hour, d.getUTCHours()))
+        return false;
+    if (!inField(cron.month, d.getUTCMonth() + 1))
+        return false;
+    const domOk = inField(cron.dayOfMonth, d.getUTCDate());
+    const dowOk = inField(cron.dayOfWeek, d.getUTCDay());
+    // Standard cron rule: when BOTH day fields are restricted, either may match.
+    return !cron.dayOfMonth.any && !cron.dayOfWeek.any
+        ? domOk || dowOk
+        : domOk && dowOk;
+}
+//# sourceMappingURL=cron.js.map

package/dist/jobs/cron.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.js","sourceRoot":"","sources":["../../src/jobs/cron.ts"],"names":[],"mappings":"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","sourcesContent":["// src/jobs/cron.ts — minimal 5-field cron parser, UTC, minute granularity.\n// Supports: * , lists (a,b) , ranges (a-b) , steps (*/n, a-b/n, a/n). No\n// month/day names, no seconds field, no @-shortcuts — YAGNI for v1.\n\nexport type CronField = { any: boolean; values: ReadonlySet<number> }\n\nexport type ParsedCron = {\n  minute: CronField\n  hour: CronField\n  dayOfMonth: CronField\n  month: CronField\n  dayOfWeek: CronField\n}\n\nconst PART_RE = /^(\\*|\\d+(?:-\\d+)?)(?:\\/(\\d+))?$/\n\nfunction parseField(\n  spec: string,\n  min: number,\n  max: number,\n  expr: string,\n): CronField {\n  if (spec === '*') return { any: true, values: new Set() }\n  const values = new Set<number>()\n  for (const part of spec.split(',')) {\n    const m = PART_RE.exec(part)\n    if (!m) throw new Error(`[workerstack] invalid cron \"${expr}\": \"${part}\"`)\n    const step = m[2] !== undefined ? Number(m[2]) : 1\n    let lo: number\n    let hi: number\n    if (m[1] === '*') {\n      lo = min\n      hi = max\n    } else if (m[1]!.includes('-')) {\n      const [a, b] = m[1]!.split('-')\n      lo = Number(a)\n      hi = Number(b)\n    } else {\n      lo = Number(m[1])\n      // \"5/15\" means \"starting at 5, every 15\" per cron convention.\n      hi = step > 1 ? max : lo\n    }\n    if (step < 1 || lo < min || hi > max || lo > hi) {\n      throw new Error(`[workerstack] invalid cron \"${expr}\": \"${part}\"`)\n    }\n    for (let v = lo; v <= hi; v += step) values.add(v)\n  }\n  return { any: false, values }\n}\n\nexport function parseCron(expr: string): ParsedCron {\n  const parts = expr.trim().split(/\\s+/)\n  if (parts.length !== 5) {\n    throw new Error(\n      `[workerstack] invalid cron \"${expr}\": expected 5 fields (minute hour day-of-month month day-of-week)`,\n    )\n  }\n  const dow = parseField(parts[4]!, 0, 7, expr)\n  return {\n    minute: parseField(parts[0]!, 0, 59, expr),\n    hour: parseField(parts[1]!, 0, 23, expr),\n    dayOfMonth: parseField(parts[2]!, 1, 31, expr),\n    month: parseField(parts[3]!, 1, 12, expr),\n    // 7 is an alias for Sunday (0).\n    dayOfWeek: dow.any\n      ? dow\n      : { any: false, values: new Set([...dow.values].map((v) => v % 7)) },\n  }\n}\n\nfunction inField(field: CronField, value: number): boolean {\n  return field.any || field.values.has(value)\n}\n\n/** Whether the minute containing `epochMs` matches, evaluated in UTC. */\nexport function cronMatches(cron: ParsedCron, epochMs: number): boolean {\n  const d = new Date(epochMs)\n  if (!inField(cron.minute, d.getUTCMinutes())) return false\n  if (!inField(cron.hour, d.getUTCHours())) return false\n  if (!inField(cron.month, d.getUTCMonth() + 1)) return false\n  const domOk = inField(cron.dayOfMonth, d.getUTCDate())\n  const dowOk = inField(cron.dayOfWeek, d.getUTCDay())\n  // Standard cron rule: when BOTH day fields are restricted, either may match.\n  return !cron.dayOfMonth.any && !cron.dayOfWeek.any\n    ? domOk || dowOk\n    : domOk && dowOk\n}\n"]}

package/dist/jobs/define.d.ts

@@ -0,0 +1,186 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { WorkerstackTx, DbFor } from '../db.js';
+import type { AnyDb } from '../dialect.js';
+import type { MessagingConfig, MessagingFacadesFor } from '../messaging/index.js';
+import type { StorageFacade } from '../runtime.js';
+import { type CatchUp } from './slots.js';
+export declare const DEFAULT_RETRIES = 3;
+export declare const DEFAULT_LEASE_DURATION_MS = 60000;
+/** @deprecated Use DEFAULT_LEASE_DURATION_MS. */
+export declare const DEFAULT_TIMEOUT_MS = 60000;
+export type BackgroundTiming = {
+    /** Lease duration in ms; an expired lease sends the job back to pending. */
+    leaseDuration?: number;
+    /** Optional cooperative execution deadline in ms. */
+    maxRuntime?: number;
+    /** @deprecated Use leaseDuration. */
+    timeout?: number;
+};
+export declare function leaseDurationFor<T extends BackgroundTiming>(def: T): number;
+/**
+ * Structural view of a Drizzle database or transaction handle that `enqueue`
+ * can insert through. The loose runtime facade accepts any handle of the app's
+ * dialect; `app.jobs` narrows it to the app's `WorkerstackTx`.
+ */
+export type EnqueueTransaction = AnyDb;
+export type EnqueueOptions = {
+    /**
+     * Collapse duplicate enqueues while the queue row holds its key: until a
+     * terminal state by default, or until it is claimed with
+     * `dedupeUntil: 'start'`.
+     */
+    dedupeKey?: string;
+    /** Milliseconds from now until the job becomes claimable. */
+    delay?: number;
+    /** Absolute time the job becomes claimable; wins over `delay`. */
+    runAt?: Date | number;
+    /**
+     * Insert the job row through this transaction. The job becomes visible to
+     * workers only when the transaction commits; a rollback removes it. Must be
+     * a transaction on the app's own database.
+     */
+    tx?: EnqueueTransaction;
+};
+/** `EnqueueOptions` with `tx` narrowed to the app schema's transaction type. */
+export type TypedEnqueueOptions<TSchema extends Record<string, unknown>> = Omit<EnqueueOptions, 'tx'> & {
+    /**
+     * Insert the job row through this transaction. The job becomes visible to
+     * workers only when the transaction commits; a rollback removes it.
+     */
+    tx?: WorkerstackTx<TSchema>;
+};
+/**
+ * How long a queue job's `dedupeKey` collapses new enqueues.
+ * - `'finish'` (default): until the job reaches a terminal state.
+ * - `'start'`: until a worker claims the job; later enqueues create a new row
+ *   that runs after it and reads the newer state.
+ */
+export type DedupeUntil = 'start' | 'finish';
+export type TickResult = {
+    /** Rows moved from pending to running this tick. */
+    claimed: number;
+    /** Handlers that completed successfully. */
+    ran: number;
+    /** Handlers that threw, whether or not they will be retried. */
+    failed: number;
+};
+/**
+ * The untyped runtime facade. Job handlers and API context expose this shape;
+ * `app.jobs` narrows `enqueue` to the declared job names/payloads.
+ */
+export type JobsRuntimeFacade = {
+    enqueue(name: string, input?: unknown, opts?: EnqueueOptions): Promise<{
+        id: string;
+    }>;
+    /** Run one poll cycle deterministically (tests). `now` defaults to Date.now(). */
+    tick(now?: number): Promise<TickResult>;
+    /**
+     * When the next background work is due, for a host scheduler. Never earlier
+     * than `now`; null when nothing is due before `until` (default: 24 h later).
+     */
+    nextDueAt(now?: number, until?: number): Promise<number | null>;
+};
+import type { RealtimeFacade } from '../realtime/facade.js';
+export type JobContext<TSchema extends Record<string, unknown> = Record<string, unknown>, TEnvResult = Record<string, unknown>, TMessaging extends MessagingConfig | undefined = MessagingConfig> = {
+    db: DbFor<TSchema>;
+    env: TEnvResult;
+    messaging: MessagingFacadesFor<TMessaging>;
+    storage: StorageFacade;
+    jobs: JobsRuntimeFacade;
+    realtime: RealtimeFacade<TSchema>;
+    /** Aborted when execution reaches its deadline or the job loses its lease. */
+    signal: AbortSignal;
+};
+export type WorkerstackJobContext<TSchema extends Record<string, unknown> = Record<string, unknown>, TEnvResult = Record<string, unknown>, TMessaging extends MessagingConfig | undefined = MessagingConfig> = JobContext<TSchema, TEnvResult, TMessaging>;
+export type QueueJobDefinition<TInput, TSchema extends Record<string, unknown> = Record<string, unknown>, TEnvResult = Record<string, unknown>, TMessaging extends MessagingConfig | undefined = MessagingConfig> = BackgroundTiming & {
+    kind: 'job';
+    /** Standard Schema payload; parsed at enqueue AND before the handler runs. */
+    input?: StandardSchemaV1<unknown, TInput>;
+    /** Attempts after the first failure. Default 3 (so 4 total attempts). */
+    retries?: number;
+    /** Delay before retry N (1-based). Default exponential: 1s, 2s, 4s, … */
+    backoff?: ((attempt: number) => number) | {
+        baseMs?: number;
+        factor?: number;
+    };
+    /** Max simultaneous `running` rows of this type, enforced per worker. */
+    concurrency?: number;
+    /**
+     * When a `dedupeKey` stops collapsing new enqueues. Default `'finish'`:
+     * held until a terminal state. `'start'`: released when a worker claims the
+     * job, so an enqueue during the run schedules one more run.
+     */
+    dedupeUntil?: DedupeUntil;
+    handler: (input: TInput, ctx: JobContext<TSchema, TEnvResult, TMessaging>) => Promise<void> | void;
+    /** Fires once, after the final attempt fails. Errors here are logged, never retried. */
+    onFailed?: (input: TInput, error: Error, ctx: JobContext<TSchema, TEnvResult, TMessaging>) => Promise<void> | void;
+};
+export type CronInvocation = {
+    scheduledFor: Date;
+};
+export type CronDefinition<TSchema extends Record<string, unknown> = Record<string, unknown>, TEnvResult = Record<string, unknown>, TSchedule extends string = string, TMessaging extends MessagingConfig | undefined = MessagingConfig> = BackgroundTiming & {
+    kind: 'cron';
+    schedule: TSchedule;
+    /** Attempts after the first failure. Default 3 (so 4 total attempts). */
+    retries?: number;
+    /** Delay before retry N (1-based). Default exponential: 1s, 2s, 4s, … */
+    backoff?: ((attempt: number) => number) | {
+        baseMs?: number;
+        factor?: number;
+    };
+    /** How missed slots are handled on wake. Default 'latest'. */
+    catchUp?: CatchUp;
+    /** How far back catch-up looks, in ms. Default 1 hour. */
+    catchUpWindow?: number;
+    handler: (invocation: CronInvocation, ctx: JobContext<TSchema, TEnvResult, TMessaging>) => Promise<void> | void;
+    /** Fires once, after the final attempt fails. Errors here are logged, never retried. */
+    onFailed?: (invocation: CronInvocation, error: Error, ctx: JobContext<TSchema, TEnvResult, TMessaging>) => Promise<void> | void;
+};
+export type BackgroundDefinition = QueueJobDefinition<any, any, any, any> | CronDefinition<any, any, any, any>;
+export type BackgroundDefs = Record<string, BackgroundDefinition>;
+/** @deprecated Use QueueJobDefinition. */
+export type JobDefinition<TInput, TSchema extends Record<string, unknown> = Record<string, unknown>, TEnvResult = Record<string, unknown>, TMessaging extends MessagingConfig | undefined = MessagingConfig> = QueueJobDefinition<TInput, TSchema, TEnvResult, TMessaging>;
+export type AnyJobDefinition = QueueJobDefinition<any, any, any, any>;
+export type AnyBackgroundDefinition = QueueJobDefinition<any, any, any, any> | CronDefinition<any, any, any, any>;
+export type JobsDefs = BackgroundDefs;
+export type QueueJobKeys<TDefs extends BackgroundDefs> = {
+    [K in keyof TDefs & string]: TDefs[K] extends QueueJobDefinition<any, any, any, any> ? K : never;
+}[keyof TDefs & string];
+/** Throws when a definition is unusable. Safe to call more than once. */
+export declare function validateBackgroundDefs(defs: BackgroundDefs): void;
+/** @deprecated Use validateBackgroundDefs. */
+export declare const validateJobsDefs: typeof validateBackgroundDefs;
+/**
+ * Delay in ms before retry `attempt` (1-based = the attempt that just failed).
+ * Jittered by ±20% so a shared outage does not retry every job in lockstep.
+ * A caller-supplied backoff function is returned verbatim — the caller owns it.
+ */
+export declare function backoffMs(def: AnyBackgroundDefinition, attempt: number): number;
+/**
+ * Build the `j` instance workerstack hands to the config's `jobs` builder
+ * callback (and exports for multi-file job setups).
+ */
+export declare function createJobsBuilder<TSchema extends Record<string, unknown>, TEnvResult = Record<string, unknown>, TMessaging extends MessagingConfig | undefined = MessagingConfig>(): {
+    /** Identity with inference: pins TInput from the schema output. */
+    job<TInput = undefined>(def: Omit<QueueJobDefinition<TInput, TSchema, TEnvResult, TMessaging>, "kind">): QueueJobDefinition<TInput, TSchema, TEnvResult, TMessaging>;
+    cron<const TSchedule extends string>(def: Omit<CronDefinition<TSchema, TEnvResult, TSchedule, TMessaging>, "kind">): CronDefinition<TSchema, TEnvResult, TSchedule, TMessaging>;
+    /** Identity with validation: returns the defs map, typed. */
+    define<TDefs extends BackgroundDefs>(defs: TDefs): TDefs;
+};
+/** Type of the `j` instance — for builder callbacks declared in separate files. */
+export type WorkerstackJobsBuilder<TSchema extends Record<string, unknown>, TEnvResult = Record<string, unknown>, TMessaging extends MessagingConfig | undefined = MessagingConfig> = ReturnType<typeof createJobsBuilder<TSchema, TEnvResult, TMessaging>>;
+type JobInputOf<TDef> = TDef extends QueueJobDefinition<infer TInput, any, any, any> ? TInput : undefined;
+/**
+ * `app.jobs`: `enqueue` narrowed to declared names + payloads. `Omit`s the
+ * runtime facade's loose `enqueue` first — intersecting two same-named
+ * methods instead would make TS treat them as overloaded, so the loose
+ * `(name: string, ...)` signature would still accept any name.
+ */
+export type JobsFacade<TDefs extends JobsDefs, TSchema extends Record<string, unknown> | undefined = undefined> = Omit<JobsRuntimeFacade, 'enqueue'> & {
+    enqueue<K extends QueueJobKeys<TDefs>>(name: K, ...rest: JobInputOf<TDefs[K]> extends undefined ? [input?: undefined, opts?: JobsFacadeEnqueueOptions<TSchema>] : [input: JobInputOf<TDefs[K]>, opts?: JobsFacadeEnqueueOptions<TSchema>]): Promise<{
+        id: string;
+    }>;
+};
+type JobsFacadeEnqueueOptions<TSchema extends Record<string, unknown> | undefined> = [TSchema] extends [Record<string, unknown>] ? TypedEnqueueOptions<TSchema> : EnqueueOptions;
+export {};
+//# sourceMappingURL=define.d.ts.map

package/dist/jobs/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/jobs/define.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAE7D,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,OAAO,CAAA;AACjD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG/C,OAAO,EAAe,KAAK,OAAO,EAAE,MAAM,SAAS,CAAA;AAEnD,eAAO,MAAM,eAAe,IAAI,CAAA;AAChC,eAAO,MAAM,yBAAyB,QAAS,CAAA;AAC/C,iDAAiD;AACjD,eAAO,MAAM,kBAAkB,QAA4B,CAAA;AAE3D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,gBAAgB,EAAE,GAAG,EAAE,CAAC,GAAG,MAAM,CAE3E;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,KAAK,CAAA;AAEtC,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kEAAkE;IAClE,KAAK,CAAC,EAAE,IAAI,GAAG,MAAM,CAAA;IACrB;;;;OAIG;IACH,EAAE,CAAC,EAAE,kBAAkB,CAAA;CACxB,CAAA;AAED,gFAAgF;AAChF,MAAM,MAAM,mBAAmB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,IAAI,CAC7E,cAAc,EACd,IAAI,CACL,GAAG;IACF;;;OAGG;IACH,EAAE,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;CAC5B,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE5C,MAAM,MAAM,UAAU,GAAG;IACvB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAA;IACf,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAA;IACX,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,CACL,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,OAAO,EACf,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC1B,kFAAkF;IAClF,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IACvC;;;OAGG;IACH,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CAChE,CAAA;AAED,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAExD,MAAM,MAAM,UAAU,CACpB,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,UAAU,SAAS,eAAe,GAAG,SAAS,GAAG,eAAe,IAC9D;IACF,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAClB,GAAG,EAAE,UAAU,CAAA;IACf,SAAS,EAAE,mBAAmB,CAAC,UAAU,CAAC,CAAA;IAC1C,OAAO,EAAE,aAAa,CAAA;IACtB,IAAI,EAAE,iBAAiB,CAAA;IACvB,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,CAAA;IACjC,8EAA8E;IAC9E,MAAM,EAAE,WAAW,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,qBAAqB,CAC/B,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,UAAU,SAAS,eAAe,GAAG,SAAS,GAAG,eAAe,IAC9D,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,CAAA;AAE/C,MAAM,MAAM,kBAAkB,CAC5B,MAAM,EACN,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,UAAU,SAAS,eAAe,GAAG,SAAS,GAAG,eAAe,IAC9D,gBAAgB,GAAG;IACrB,IAAI,EAAE,KAAK,CAAA;IACX,8EAA8E;IAC9E,KAAK,CAAC,EAAE,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IACzC,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yEAAyE;IACzE,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9E,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,OAAO,EAAE,CACP,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,KAC7C,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACzB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,CACT,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,KAC7C,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,CAAA;AAEnD,MAAM,MAAM,cAAc,CACxB,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,SAAS,SAAS,MAAM,GAAG,MAAM,EACjC,UAAU,SAAS,eAAe,GAAG,SAAS,GAAG,eAAe,IAC9D,gBAAgB,GAAG;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,SAAS,CAAA;IACnB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yEAAyE;IACzE,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9E,8DAA8D;IAC9D,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,EAAE,CACP,UAAU,EAAE,cAAc,EAC1B,GAAG,EAAE,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,KAC7C,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACzB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,CACT,UAAU,EAAE,cAAc,EAC1B,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,KAC7C,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,oBAAoB,GAC5B,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GACtC,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AACtC,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAA;AAEjE,0CAA0C;AAC1C,MAAM,MAAM,aAAa,CACvB,MAAM,EACN,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,UAAU,SAAS,eAAe,GAAG,SAAS,GAAG,eAAe,IAC9D,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,CAAA;AAG/D,MAAM,MAAM,gBAAgB,GAAG,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AAErE,MAAM,MAAM,uBAAuB,GAC/B,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GACtC,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AACtC,MAAM,MAAM,QAAQ,GAAG,cAAc,CAAA;AAErC,MAAM,MAAM,YAAY,CAAC,KAAK,SAAS,cAAc,IAAI;KACtD,CAAC,IAAI,MAAM,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,SAAS,kBAAkB,CAC9D,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,CACJ,GACG,CAAC,GACD,KAAK;CACV,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAA;AAEvB,yEAAyE;AACzE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAmEjE;AAWD,8CAA8C;AAC9C,eAAO,MAAM,gBAAgB,+BAAyB,CAAA;AAEtD;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,uBAAuB,EAC5B,OAAO,EAAE,MAAM,GACd,MAAM,CAOR;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,UAAU,SAAS,eAAe,GAAG,SAAS,GAAG,eAAe;IAG9D,mEAAmE;QAC/D,MAAM,mBACH,IAAI,CACP,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,EAC3D,MAAM,CACP,GACA,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC;eAGnD,SAAS,SAAS,MAAM,OAC5B,IAAI,CACP,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,CAAC,EAC1D,MAAM,CACP,GACA,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,CAAC;IAK7D,6DAA6D;WACtD,KAAK,SAAS,cAAc,QAAQ,KAAK,GAAG,KAAK;EAK3D;AAED,mFAAmF;AACnF,MAAM,MAAM,sBAAsB,CAChC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,UAAU,SAAS,eAAe,GAAG,SAAS,GAAG,eAAe,IAC9D,UAAU,CAAC,OAAO,iBAAiB,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAA;AAMzE,KAAK,UAAU,CAAC,IAAI,IAClB,IAAI,SAAS,kBAAkB,CAAC,MAAM,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GACxD,MAAM,GACN,SAAS,CAAA;AAEf;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CACpB,KAAK,SAAS,QAAQ,EACtB,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,SAAS,IAC7D,IAAI,CAAC,iBAAiB,EAAE,SAAS,CAAC,GAAG;IACvC,OAAO,CAAC,CAAC,SAAS,YAAY,CAAC,KAAK,CAAC,EACnC,IAAI,EAAE,CAAC,EACP,GAAG,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,SAAS,GAC3C,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,wBAAwB,CAAC,OAAO,CAAC,CAAC,GAC7D,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,wBAAwB,CAAC,OAAO,CAAC,CAAC,GAC1E,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC3B,CAAA;AAED,KAAK,wBAAwB,CAC3B,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,IACjD,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC3C,mBAAmB,CAAC,OAAO,CAAC,GAC5B,cAAc,CAAA"}

package/dist/jobs/define.js

@@ -0,0 +1,99 @@
+import { parseCron } from './cron.js';
+import { CRON_PREFIX } from './slots.js';
+export const DEFAULT_RETRIES = 3;
+export const DEFAULT_LEASE_DURATION_MS = 60_000;
+/** @deprecated Use DEFAULT_LEASE_DURATION_MS. */
+export const DEFAULT_TIMEOUT_MS = DEFAULT_LEASE_DURATION_MS;
+export function leaseDurationFor(def) {
+    return def.leaseDuration ?? def.timeout ?? DEFAULT_LEASE_DURATION_MS;
+}
+/** Throws when a definition is unusable. Safe to call more than once. */
+export function validateBackgroundDefs(defs) {
+    for (const [name, def] of Object.entries(defs)) {
+        if (typeof def.handler !== 'function') {
+            throw new Error(`[workerstack] background task "${name}" has no handler`);
+        }
+        if (def.kind === 'job' && name.startsWith(CRON_PREFIX)) {
+            throw new Error(`[workerstack] job "${name}": the "${CRON_PREFIX}" prefix is reserved for cron tasks`);
+        }
+        if (def.retries !== undefined &&
+            (def.retries < 0 || !Number.isInteger(def.retries))) {
+            throw new Error(`[workerstack] background task "${name}": retries must be a non-negative integer`);
+        }
+        if (def.timeout !== undefined && def.leaseDuration !== undefined) {
+            throw new Error(`[workerstack] background task "${name}": timeout and leaseDuration cannot both be declared`);
+        }
+        for (const field of ['timeout', 'leaseDuration', 'maxRuntime']) {
+            const value = def[field];
+            if (value !== undefined &&
+                (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0)) {
+                throw new Error(`[workerstack] background task "${name}": ${field} must be a positive finite integer`);
+            }
+        }
+        if (def.kind === 'cron') {
+            parseCron(def.schedule);
+            assertCronHasNoDedupeUntil(def, `cron "${name}"`);
+            if (def.concurrency !== undefined) {
+                throw new Error(`[workerstack] cron "${name}": concurrency is not supported for cron tasks — slots are already unique`);
+            }
+            if (def.catchUpWindow !== undefined && def.catchUpWindow <= 0) {
+                throw new Error(`[workerstack] cron "${name}": catchUpWindow must be positive`);
+            }
+            continue;
+        }
+        if (def.concurrency !== undefined &&
+            (def.concurrency < 1 || !Number.isInteger(def.concurrency))) {
+            throw new Error(`[workerstack] job "${name}": concurrency must be a positive integer`);
+        }
+        if (def.dedupeUntil !== undefined &&
+            def.dedupeUntil !== 'start' &&
+            def.dedupeUntil !== 'finish') {
+            throw new Error(`[workerstack] job "${name}": dedupeUntil must be 'start' or 'finish'`);
+        }
+    }
+}
+/** Cron slot ownership depends on the retained dedupe key. */
+function assertCronHasNoDedupeUntil(def, label) {
+    if (def.dedupeUntil !== undefined) {
+        throw new Error(`[workerstack] ${label}: dedupeUntil is not supported for cron tasks — cron tasks retain their slot key`);
+    }
+}
+/** @deprecated Use validateBackgroundDefs. */
+export const validateJobsDefs = validateBackgroundDefs;
+/**
+ * Delay in ms before retry `attempt` (1-based = the attempt that just failed).
+ * Jittered by ±20% so a shared outage does not retry every job in lockstep.
+ * A caller-supplied backoff function is returned verbatim — the caller owns it.
+ */
+export function backoffMs(def, attempt) {
+    const b = def.backoff;
+    if (typeof b === 'function')
+        return b(attempt);
+    const baseMs = b?.baseMs ?? 1000;
+    const factor = b?.factor ?? 2;
+    const flat = baseMs * factor ** (attempt - 1);
+    return Math.round(flat * (0.8 + Math.random() * 0.4));
+}
+/**
+ * Build the `j` instance workerstack hands to the config's `jobs` builder
+ * callback (and exports for multi-file job setups).
+ */
+export function createJobsBuilder() {
+    return {
+        /** Identity with inference: pins TInput from the schema output. */
+        job(def) {
+            return { kind: 'job', ...def };
+        },
+        cron(def) {
+            parseCron(def.schedule);
+            assertCronHasNoDedupeUntil(def, 'cron');
+            return { kind: 'cron', ...def };
+        },
+        /** Identity with validation: returns the defs map, typed. */
+        define(defs) {
+            validateBackgroundDefs(defs);
+            return defs;
+        },
+    };
+}
+//# sourceMappingURL=define.js.map

package/dist/jobs/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../src/jobs/define.ts"],"names":[],"mappings":"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","sourcesContent":["// src/jobs/define.ts — job definition types and the typed builder.\n// `createJobsBuilder` exists purely to carry\n// TSchema/TEnvResult typing into inline callbacks and extracted files.\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\n\nimport type { WorkerstackTx, DbFor } from '../db'\nimport type { AnyDb } from '../dialect'\nimport type { MessagingConfig, MessagingFacadesFor } from '../messaging'\nimport type { StorageFacade } from '../runtime'\n\nimport { parseCron } from './cron'\nimport { CRON_PREFIX, type CatchUp } from './slots'\n\nexport const DEFAULT_RETRIES = 3\nexport const DEFAULT_LEASE_DURATION_MS = 60_000\n/** @deprecated Use DEFAULT_LEASE_DURATION_MS. */\nexport const DEFAULT_TIMEOUT_MS = DEFAULT_LEASE_DURATION_MS\n\nexport type BackgroundTiming = {\n  /** Lease duration in ms; an expired lease sends the job back to pending. */\n  leaseDuration?: number\n  /** Optional cooperative execution deadline in ms. */\n  maxRuntime?: number\n  /** @deprecated Use leaseDuration. */\n  timeout?: number\n}\n\nexport function leaseDurationFor<T extends BackgroundTiming>(def: T): number {\n  return def.leaseDuration ?? def.timeout ?? DEFAULT_LEASE_DURATION_MS\n}\n\n/**\n * Structural view of a Drizzle database or transaction handle that `enqueue`\n * can insert through. The loose runtime facade accepts any handle of the app's\n * dialect; `app.jobs` narrows it to the app's `WorkerstackTx`.\n */\nexport type EnqueueTransaction = AnyDb\n\nexport type EnqueueOptions = {\n  /**\n   * Collapse duplicate enqueues while the queue row holds its key: until a\n   * terminal state by default, or until it is claimed with\n   * `dedupeUntil: 'start'`.\n   */\n  dedupeKey?: string\n  /** Milliseconds from now until the job becomes claimable. */\n  delay?: number\n  /** Absolute time the job becomes claimable; wins over `delay`. */\n  runAt?: Date | number\n  /**\n   * Insert the job row through this transaction. The job becomes visible to\n   * workers only when the transaction commits; a rollback removes it. Must be\n   * a transaction on the app's own database.\n   */\n  tx?: EnqueueTransaction\n}\n\n/** `EnqueueOptions` with `tx` narrowed to the app schema's transaction type. */\nexport type TypedEnqueueOptions<TSchema extends Record<string, unknown>> = Omit<\n  EnqueueOptions,\n  'tx'\n> & {\n  /**\n   * Insert the job row through this transaction. The job becomes visible to\n   * workers only when the transaction commits; a rollback removes it.\n   */\n  tx?: WorkerstackTx<TSchema>\n}\n\n/**\n * How long a queue job's `dedupeKey` collapses new enqueues.\n * - `'finish'` (default): until the job reaches a terminal state.\n * - `'start'`: until a worker claims the job; later enqueues create a new row\n *   that runs after it and reads the newer state.\n */\nexport type DedupeUntil = 'start' | 'finish'\n\nexport type TickResult = {\n  /** Rows moved from pending to running this tick. */\n  claimed: number\n  /** Handlers that completed successfully. */\n  ran: number\n  /** Handlers that threw, whether or not they will be retried. */\n  failed: number\n}\n\n/**\n * The untyped runtime facade. Job handlers and API context expose this shape;\n * `app.jobs` narrows `enqueue` to the declared job names/payloads.\n */\nexport type JobsRuntimeFacade = {\n  enqueue(\n    name: string,\n    input?: unknown,\n    opts?: EnqueueOptions,\n  ): Promise<{ id: string }>\n  /** Run one poll cycle deterministically (tests). `now` defaults to Date.now(). */\n  tick(now?: number): Promise<TickResult>\n  /**\n   * When the next background work is due, for a host scheduler. Never earlier\n   * than `now`; null when nothing is due before `until` (default: 24 h later).\n   */\n  nextDueAt(now?: number, until?: number): Promise<number | null>\n}\n\nimport type { RealtimeFacade } from '../realtime/facade'\n\nexport type JobContext<\n  TSchema extends Record<string, unknown> = Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n  TMessaging extends MessagingConfig | undefined = MessagingConfig,\n> = {\n  db: DbFor<TSchema>\n  env: TEnvResult\n  messaging: MessagingFacadesFor<TMessaging>\n  storage: StorageFacade\n  jobs: JobsRuntimeFacade\n  realtime: RealtimeFacade<TSchema>\n  /** Aborted when execution reaches its deadline or the job loses its lease. */\n  signal: AbortSignal\n}\n\nexport type WorkerstackJobContext<\n  TSchema extends Record<string, unknown> = Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n  TMessaging extends MessagingConfig | undefined = MessagingConfig,\n> = JobContext<TSchema, TEnvResult, TMessaging>\n\nexport type QueueJobDefinition<\n  TInput,\n  TSchema extends Record<string, unknown> = Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n  TMessaging extends MessagingConfig | undefined = MessagingConfig,\n> = BackgroundTiming & {\n  kind: 'job'\n  /** Standard Schema payload; parsed at enqueue AND before the handler runs. */\n  input?: StandardSchemaV1<unknown, TInput>\n  /** Attempts after the first failure. Default 3 (so 4 total attempts). */\n  retries?: number\n  /** Delay before retry N (1-based). Default exponential: 1s, 2s, 4s, … */\n  backoff?: ((attempt: number) => number) | { baseMs?: number; factor?: number }\n  /** Max simultaneous `running` rows of this type, enforced per worker. */\n  concurrency?: number\n  /**\n   * When a `dedupeKey` stops collapsing new enqueues. Default `'finish'`:\n   * held until a terminal state. `'start'`: released when a worker claims the\n   * job, so an enqueue during the run schedules one more run.\n   */\n  dedupeUntil?: DedupeUntil\n  handler: (\n    input: TInput,\n    ctx: JobContext<TSchema, TEnvResult, TMessaging>,\n  ) => Promise<void> | void\n  /** Fires once, after the final attempt fails. Errors here are logged, never retried. */\n  onFailed?: (\n    input: TInput,\n    error: Error,\n    ctx: JobContext<TSchema, TEnvResult, TMessaging>,\n  ) => Promise<void> | void\n}\n\nexport type CronInvocation = { scheduledFor: Date }\n\nexport type CronDefinition<\n  TSchema extends Record<string, unknown> = Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n  TSchedule extends string = string,\n  TMessaging extends MessagingConfig | undefined = MessagingConfig,\n> = BackgroundTiming & {\n  kind: 'cron'\n  schedule: TSchedule\n  /** Attempts after the first failure. Default 3 (so 4 total attempts). */\n  retries?: number\n  /** Delay before retry N (1-based). Default exponential: 1s, 2s, 4s, … */\n  backoff?: ((attempt: number) => number) | { baseMs?: number; factor?: number }\n  /** How missed slots are handled on wake. Default 'latest'. */\n  catchUp?: CatchUp\n  /** How far back catch-up looks, in ms. Default 1 hour. */\n  catchUpWindow?: number\n  handler: (\n    invocation: CronInvocation,\n    ctx: JobContext<TSchema, TEnvResult, TMessaging>,\n  ) => Promise<void> | void\n  /** Fires once, after the final attempt fails. Errors here are logged, never retried. */\n  onFailed?: (\n    invocation: CronInvocation,\n    error: Error,\n    ctx: JobContext<TSchema, TEnvResult, TMessaging>,\n  ) => Promise<void> | void\n}\n\nexport type BackgroundDefinition =\n  | QueueJobDefinition<any, any, any, any>\n  | CronDefinition<any, any, any, any>\nexport type BackgroundDefs = Record<string, BackgroundDefinition>\n\n/** @deprecated Use QueueJobDefinition. */\nexport type JobDefinition<\n  TInput,\n  TSchema extends Record<string, unknown> = Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n  TMessaging extends MessagingConfig | undefined = MessagingConfig,\n> = QueueJobDefinition<TInput, TSchema, TEnvResult, TMessaging>\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type AnyJobDefinition = QueueJobDefinition<any, any, any, any>\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type AnyBackgroundDefinition =\n  | QueueJobDefinition<any, any, any, any>\n  | CronDefinition<any, any, any, any>\nexport type JobsDefs = BackgroundDefs\n\nexport type QueueJobKeys<TDefs extends BackgroundDefs> = {\n  [K in keyof TDefs & string]: TDefs[K] extends QueueJobDefinition<\n    any,\n    any,\n    any,\n    any\n  >\n    ? K\n    : never\n}[keyof TDefs & string]\n\n/** Throws when a definition is unusable. Safe to call more than once. */\nexport function validateBackgroundDefs(defs: BackgroundDefs): void {\n  for (const [name, def] of Object.entries(defs)) {\n    if (typeof def.handler !== 'function') {\n      throw new Error(`[workerstack] background task \"${name}\" has no handler`)\n    }\n    if (def.kind === 'job' && name.startsWith(CRON_PREFIX)) {\n      throw new Error(\n        `[workerstack] job \"${name}\": the \"${CRON_PREFIX}\" prefix is reserved for cron tasks`,\n      )\n    }\n    if (\n      def.retries !== undefined &&\n      (def.retries < 0 || !Number.isInteger(def.retries))\n    ) {\n      throw new Error(\n        `[workerstack] background task \"${name}\": retries must be a non-negative integer`,\n      )\n    }\n    if (def.timeout !== undefined && def.leaseDuration !== undefined) {\n      throw new Error(\n        `[workerstack] background task \"${name}\": timeout and leaseDuration cannot both be declared`,\n      )\n    }\n    for (const field of ['timeout', 'leaseDuration', 'maxRuntime'] as const) {\n      const value = def[field]\n      if (\n        value !== undefined &&\n        (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0)\n      ) {\n        throw new Error(\n          `[workerstack] background task \"${name}\": ${field} must be a positive finite integer`,\n        )\n      }\n    }\n    if (def.kind === 'cron') {\n      parseCron(def.schedule)\n      assertCronHasNoDedupeUntil(def, `cron \"${name}\"`)\n      if ((def as { concurrency?: number }).concurrency !== undefined) {\n        throw new Error(\n          `[workerstack] cron \"${name}\": concurrency is not supported for cron tasks — slots are already unique`,\n        )\n      }\n      if (def.catchUpWindow !== undefined && def.catchUpWindow <= 0) {\n        throw new Error(\n          `[workerstack] cron \"${name}\": catchUpWindow must be positive`,\n        )\n      }\n      continue\n    }\n    if (\n      def.concurrency !== undefined &&\n      (def.concurrency < 1 || !Number.isInteger(def.concurrency))\n    ) {\n      throw new Error(\n        `[workerstack] job \"${name}\": concurrency must be a positive integer`,\n      )\n    }\n    if (\n      def.dedupeUntil !== undefined &&\n      def.dedupeUntil !== 'start' &&\n      def.dedupeUntil !== 'finish'\n    ) {\n      throw new Error(\n        `[workerstack] job \"${name}\": dedupeUntil must be 'start' or 'finish'`,\n      )\n    }\n  }\n}\n\n/** Cron slot ownership depends on the retained dedupe key. */\nfunction assertCronHasNoDedupeUntil(def: object, label: string): void {\n  if ((def as { dedupeUntil?: unknown }).dedupeUntil !== undefined) {\n    throw new Error(\n      `[workerstack] ${label}: dedupeUntil is not supported for cron tasks — cron tasks retain their slot key`,\n    )\n  }\n}\n\n/** @deprecated Use validateBackgroundDefs. */\nexport const validateJobsDefs = validateBackgroundDefs\n\n/**\n * Delay in ms before retry `attempt` (1-based = the attempt that just failed).\n * Jittered by ±20% so a shared outage does not retry every job in lockstep.\n * A caller-supplied backoff function is returned verbatim — the caller owns it.\n */\nexport function backoffMs(\n  def: AnyBackgroundDefinition,\n  attempt: number,\n): number {\n  const b = def.backoff\n  if (typeof b === 'function') return b(attempt)\n  const baseMs = b?.baseMs ?? 1000\n  const factor = b?.factor ?? 2\n  const flat = baseMs * factor ** (attempt - 1)\n  return Math.round(flat * (0.8 + Math.random() * 0.4))\n}\n\n/**\n * Build the `j` instance workerstack hands to the config's `jobs` builder\n * callback (and exports for multi-file job setups).\n */\nexport function createJobsBuilder<\n  TSchema extends Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n  TMessaging extends MessagingConfig | undefined = MessagingConfig,\n>() {\n  return {\n    /** Identity with inference: pins TInput from the schema output. */\n    job<TInput = undefined>(\n      def: Omit<\n        QueueJobDefinition<TInput, TSchema, TEnvResult, TMessaging>,\n        'kind'\n      >,\n    ): QueueJobDefinition<TInput, TSchema, TEnvResult, TMessaging> {\n      return { kind: 'job', ...def }\n    },\n    cron<const TSchedule extends string>(\n      def: Omit<\n        CronDefinition<TSchema, TEnvResult, TSchedule, TMessaging>,\n        'kind'\n      >,\n    ): CronDefinition<TSchema, TEnvResult, TSchedule, TMessaging> {\n      parseCron(def.schedule)\n      assertCronHasNoDedupeUntil(def, 'cron')\n      return { kind: 'cron', ...def }\n    },\n    /** Identity with validation: returns the defs map, typed. */\n    define<TDefs extends BackgroundDefs>(defs: TDefs): TDefs {\n      validateBackgroundDefs(defs)\n      return defs\n    },\n  }\n}\n\n/** Type of the `j` instance — for builder callbacks declared in separate files. */\nexport type WorkerstackJobsBuilder<\n  TSchema extends Record<string, unknown>,\n  TEnvResult = Record<string, unknown>,\n  TMessaging extends MessagingConfig | undefined = MessagingConfig,\n> = ReturnType<typeof createJobsBuilder<TSchema, TEnvResult, TMessaging>>\n\n// Infers TInput from the JobDefinition's own type argument rather than\n// pattern-matching the (optional, so union-with-undefined) `input` property —\n// A required-property pattern fails structurally because `input` is optional,\n// so infer from the definition's own type argument instead.\ntype JobInputOf<TDef> =\n  TDef extends QueueJobDefinition<infer TInput, any, any, any>\n    ? TInput\n    : undefined\n\n/**\n * `app.jobs`: `enqueue` narrowed to declared names + payloads. `Omit`s the\n * runtime facade's loose `enqueue` first — intersecting two same-named\n * methods instead would make TS treat them as overloaded, so the loose\n * `(name: string, ...)` signature would still accept any name.\n */\nexport type JobsFacade<\n  TDefs extends JobsDefs,\n  TSchema extends Record<string, unknown> | undefined = undefined,\n> = Omit<JobsRuntimeFacade, 'enqueue'> & {\n  enqueue<K extends QueueJobKeys<TDefs>>(\n    name: K,\n    ...rest: JobInputOf<TDefs[K]> extends undefined\n      ? [input?: undefined, opts?: JobsFacadeEnqueueOptions<TSchema>]\n      : [input: JobInputOf<TDefs[K]>, opts?: JobsFacadeEnqueueOptions<TSchema>]\n  ): Promise<{ id: string }>\n}\n\ntype JobsFacadeEnqueueOptions<\n  TSchema extends Record<string, unknown> | undefined,\n> = [TSchema] extends [Record<string, unknown>]\n  ? TypedEnqueueOptions<TSchema>\n  : EnqueueOptions\n"]}

package/dist/jobs/index.d.ts

@@ -0,0 +1,9 @@
+export { createJobsBuilder, validateBackgroundDefs, validateJobsDefs, DEFAULT_RETRIES, DEFAULT_LEASE_DURATION_MS, DEFAULT_TIMEOUT_MS, leaseDurationFor, } from './define.js';
+export type { AnyJobDefinition, BackgroundTiming, BackgroundDefinition, BackgroundDefs, WorkerstackJobContext, WorkerstackJobsBuilder, DedupeUntil, EnqueueOptions, EnqueueTransaction, JobContext, JobDefinition, QueueJobDefinition, CronDefinition, CronInvocation, QueueJobKeys, TypedEnqueueOptions, JobsDefs, JobsFacade, JobsRuntimeFacade, } from './define.js';
+export { enqueueJob, enqueueTarget, resolveRunAt } from './queue.js';
+export { createJobRunner } from './worker.js';
+export { parseCron, cronMatches } from './cron.js';
+export { slotsDue, floorSlot, nextCronSlot, CRON_PREFIX, SLOT_MS, } from './slots.js';
+export type { CatchUp } from './slots.js';
+export type { TickResult } from './define.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/jobs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,yBAAyB,EACzB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,UAAU,CAAA;AACjB,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACtB,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,QAAQ,EACR,UAAU,EACV,iBAAiB,GAClB,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,EACL,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,WAAW,EACX,OAAO,GACR,MAAM,SAAS,CAAA;AAChB,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA"}

package/dist/jobs/index.js

@@ -0,0 +1,7 @@
+// src/jobs/index.ts — module surface consumed by workerstack.
+export { createJobsBuilder, validateBackgroundDefs, validateJobsDefs, DEFAULT_RETRIES, DEFAULT_LEASE_DURATION_MS, DEFAULT_TIMEOUT_MS, leaseDurationFor, } from './define.js';
+export { enqueueJob, enqueueTarget, resolveRunAt } from './queue.js';
+export { createJobRunner } from './worker.js';
+export { parseCron, cronMatches } from './cron.js';
+export { slotsDue, floorSlot, nextCronSlot, CRON_PREFIX, SLOT_MS, } from './slots.js';
+//# sourceMappingURL=index.js.map