@rangka/core 0.0.1

package/src/jobs/enqueue.ts

@@ -0,0 +1,93 @@
+import type { Kysely } from 'kysely';
+import { sql } from 'kysely';
+import type { EnqueueOptions, BackoffStrategy } from './types.js';
+
+export interface EnqueueParams {
+  name: string;
+  data?: unknown;
+  options?: EnqueueOptions;
+}
+
+/**
+ * Insert a job row into rangka_jobs and return its ID.
+ * If `unique` is set, deduplicates against active/created jobs with the same key.
+ */
+export async function enqueue(
+  db: Kysely<unknown>,
+  name: string,
+  data: unknown = null,
+  options: EnqueueOptions = {},
+): Promise<string> {
+  const maxRetries = options.retries ?? 0;
+  const backoff: BackoffStrategy = options.backoff ?? 'exponential';
+  const startAfter = options.delay ? new Date(Date.now() + options.delay) : null;
+  const uniqueKey = options.unique ? (options.uniqueKey ?? name) : null;
+
+  if (uniqueKey) {
+    return insertUniqueJob(db, name, data, maxRetries, backoff, startAfter, uniqueKey);
+  }
+
+  return insertJob(db, name, data, maxRetries, backoff, startAfter);
+}
+
+/** Insert a job with a unique_key constraint — returns the existing job ID if a duplicate exists. */
+async function insertUniqueJob(
+  db: Kysely<unknown>,
+  name: string,
+  data: unknown,
+  maxRetries: number,
+  backoff: BackoffStrategy,
+  startAfter: Date | null,
+  uniqueKey: string,
+): Promise<string> {
+  const result = await sql<{ id: string }>`
+    INSERT INTO rangka_jobs (name, data, state, max_retries, backoff, start_after, unique_key)
+    VALUES (
+      ${name},
+      ${JSON.stringify(data)}::jsonb,
+      'created',
+      ${maxRetries},
+      ${backoff},
+      ${startAfter},
+      ${uniqueKey}
+    )
+    ON CONFLICT (unique_key) WHERE state IN ('created', 'active')
+    DO NOTHING
+    RETURNING id
+  `.execute(db);
+
+  // If insert was skipped due to conflict, look up the existing job's ID
+  if (result.rows.length === 0) {
+    const existing = await sql<{ id: string }>`
+      SELECT id FROM rangka_jobs WHERE unique_key = ${uniqueKey} AND state IN ('created', 'active') LIMIT 1
+    `.execute(db);
+    return existing.rows[0]?.id ?? '';
+  }
+
+  return result.rows[0].id;
+}
+
+/** Insert a standard (non-unique) job row. */
+async function insertJob(
+  db: Kysely<unknown>,
+  name: string,
+  data: unknown,
+  maxRetries: number,
+  backoff: BackoffStrategy,
+  startAfter: Date | null,
+): Promise<string> {
+  const result = await sql<{ id: string }>`
+    INSERT INTO rangka_jobs (name, data, state, max_retries, backoff, start_after)
+    VALUES (
+      ${name},
+      ${JSON.stringify(data)}::jsonb,
+      'created',
+      ${maxRetries},
+      ${backoff},
+      ${startAfter}
+    )
+    RETURNING id
+  `.execute(db);
+
+  return result.rows[0].id;
+}

package/src/jobs/index.ts

@@ -0,0 +1,14 @@
+export type {
+  JobRecord,
+  DeadLetterRecord,
+  ScheduledJobRecord,
+  JobState,
+  BackoffStrategy,
+  JobWorkerConfig,
+  RegisteredJob,
+  EnqueueOptions,
+} from './types.js';
+export { JobRegistry } from './registry.js';
+export { enqueue } from './enqueue.js';
+export { JobWorker } from './worker.js';
+export { ScheduleManager } from './scheduler.js';

package/src/jobs/registry.ts

@@ -0,0 +1,92 @@
+import type { JobConfig } from '@rangka/shared';
+import type { RegisteredJob } from './types.js';
+
+/**
+ * Stores and validates background job definitions.
+ * Jobs can be one-off or scheduled via cron expressions.
+ */
+export class JobRegistry {
+  private readonly jobs: Map<string, RegisteredJob> = new Map();
+
+  /** Register a new job after validating its configuration. */
+  register(name: string, config: JobConfig): void {
+    if (this.jobs.has(name)) {
+      throw new Error(`Job "${name}" is already registered`);
+    }
+
+    const validationErrors = this.validate(name, config);
+    if (validationErrors.length > 0) {
+      throw new Error(`Invalid job config for "${name}": ${validationErrors.join('; ')}`);
+    }
+
+    this.jobs.set(name, { name, config });
+  }
+
+  get(name: string): RegisteredJob | undefined {
+    return this.jobs.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.jobs.has(name);
+  }
+
+  getAll(): RegisteredJob[] {
+    return Array.from(this.jobs.values());
+  }
+
+  /** Return only jobs that have a cron schedule defined. */
+  getScheduled(): RegisteredJob[] {
+    return this.getAll().filter((job) => !!job.config.schedule);
+  }
+
+  /** Validate job name and config, returning a list of human-readable errors. */
+  private validate(name: string, config: JobConfig): string[] {
+    const errors: string[] = [];
+
+    if (!name || name.trim().length === 0) {
+      errors.push('Job name must not be empty');
+    }
+
+    if (typeof config.handler !== 'function') {
+      errors.push('Job handler must be a function');
+    }
+
+    this.validateConcurrency(config, errors);
+    this.validateRetries(config, errors);
+    this.validateBackoff(config, errors);
+    this.validateSchedule(config, errors);
+
+    return errors;
+  }
+
+  private validateConcurrency(config: JobConfig, errors: string[]): void {
+    if (
+      config.concurrency !== undefined &&
+      (config.concurrency < 1 || !Number.isInteger(config.concurrency))
+    ) {
+      errors.push('Concurrency must be a positive integer');
+    }
+  }
+
+  private validateRetries(config: JobConfig, errors: string[]): void {
+    if (config.retries !== undefined && (config.retries < 0 || !Number.isInteger(config.retries))) {
+      errors.push('Retries must be a non-negative integer');
+    }
+  }
+
+  private validateBackoff(config: JobConfig, errors: string[]): void {
+    const allowedStrategies = ['exponential', 'linear', 'fixed'];
+    if (config.backoff !== undefined && !allowedStrategies.includes(config.backoff)) {
+      errors.push('Backoff must be one of: exponential, linear, fixed');
+    }
+  }
+
+  private validateSchedule(config: JobConfig, errors: string[]): void {
+    if (config.schedule !== undefined) {
+      const cronFields = config.schedule.trim().split(/\s+/);
+      if (cronFields.length !== 5) {
+        errors.push('Schedule must be a valid 5-field cron expression');
+      }
+    }
+  }
+}

package/src/jobs/scheduler.ts

@@ -0,0 +1,205 @@
+import type { Kysely } from 'kysely';
+import { sql } from 'kysely';
+import type { JobRegistry } from './registry.js';
+import { toCount } from '../helpers/coerce.js';
+
+/**
+ * ScheduleManager polls the database for cron-scheduled jobs that are due,
+ * enqueues them, and advances their next_run_at timestamps.
+ */
+export class ScheduleManager {
+  private running = false;
+  private pollTimer: ReturnType<typeof setTimeout> | null = null;
+  private readonly pollInterval: number;
+  private readonly db: Kysely<unknown>;
+  private readonly registry: JobRegistry;
+
+  constructor(db: Kysely<unknown>, registry: JobRegistry, pollInterval = 60000) {
+    this.db = db;
+    this.registry = registry;
+    this.pollInterval = pollInterval;
+  }
+
+  // ─── Public API ────────────────────────────────────────────────────────────
+
+  /** Upserts all registered scheduled jobs into the database. */
+  async syncSchedules(): Promise<void> {
+    const scheduledJobs = this.registry.getScheduled();
+
+    for (const job of scheduledJobs) {
+      const cronExpr = job.config.schedule!;
+      const nextRun = this.computeNextRun(cronExpr);
+
+      await sql`
+        INSERT INTO rangka_scheduled_jobs (name, cron, data, next_run_at)
+        VALUES (${job.name}, ${cronExpr}, NULL, ${nextRun})
+        ON CONFLICT (name) DO UPDATE SET cron = ${cronExpr}, next_run_at = COALESCE(rangka_scheduled_jobs.next_run_at, ${nextRun})
+      `.execute(this.db);
+    }
+  }
+
+  /** Starts the polling loop. */
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+    this.schedulePoll();
+  }
+
+  /** Stops the polling loop. */
+  async stop(): Promise<void> {
+    this.running = false;
+    if (this.pollTimer) {
+      clearTimeout(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  /**
+   * Parses a 5-field cron expression and returns the next matching minute
+   * after `from`. Scans up to ~1 year of minutes before giving up.
+   */
+  computeNextRun(cronExpr: string, from: Date = new Date()): Date {
+    const fields = cronExpr.trim().split(/\s+/);
+    if (fields.length !== 5) {
+      throw new Error(`Invalid cron expression: "${cronExpr}"`);
+    }
+
+    const [minuteExpr, hourExpr, dayOfMonthExpr, monthExpr, dayOfWeekExpr] = fields;
+
+    // Start scanning from the next whole minute after `from`
+    const candidate = new Date(from.getTime());
+    candidate.setSeconds(0, 0);
+    candidate.setMinutes(candidate.getMinutes() + 1);
+
+    const ONE_YEAR_IN_MINUTES = 525_960;
+
+    for (let i = 0; i < ONE_YEAR_IN_MINUTES; i++) {
+      const matchesAllFields =
+        this.matchesCronField(minuteExpr, candidate.getMinutes(), 0, 59) &&
+        this.matchesCronField(hourExpr, candidate.getHours(), 0, 23) &&
+        this.matchesCronField(dayOfMonthExpr, candidate.getDate(), 1, 31) &&
+        this.matchesCronField(monthExpr, candidate.getMonth() + 1, 1, 12) &&
+        this.matchesCronField(dayOfWeekExpr, candidate.getDay(), 0, 6);
+
+      if (matchesAllFields) {
+        return candidate;
+      }
+
+      candidate.setMinutes(candidate.getMinutes() + 1);
+    }
+
+    throw new Error(`Could not compute next run for cron: "${cronExpr}"`);
+  }
+
+  // ─── Private helpers ───────────────────────────────────────────────────────
+
+  /** Arms the next poll timer. */
+  private schedulePoll(): void {
+    this.pollTimer = setTimeout(() => this.poll(), this.pollInterval);
+  }
+
+  /** Runs one poll cycle, then re-arms the timer if still running. */
+  private poll(): void {
+    if (!this.running) return;
+
+    this.checkSchedules().finally(() => {
+      if (this.running) {
+        this.schedulePoll();
+      }
+    });
+  }
+
+  /**
+   * Finds all schedules that are due and processes each one:
+   * - Skips enqueuing if the job already has a pending/active instance.
+   * - Otherwise enqueues a new job instance.
+   * In both cases, advances the schedule's next_run_at.
+   */
+  private async checkSchedules(): Promise<void> {
+    const dueSchedules = await sql<{ id: string; name: string; cron: string; data: unknown }>`
+      SELECT id, name, cron, data FROM rangka_scheduled_jobs
+      WHERE next_run_at <= NOW()
+      FOR UPDATE SKIP LOCKED
+    `.execute(this.db);
+
+    for (const schedule of dueSchedules.rows) {
+      const alreadyPending = await this.hasPendingJob(schedule.name);
+
+      if (!alreadyPending) {
+        await this.enqueueJob(schedule.name, schedule.data);
+      }
+
+      await this.advanceSchedule(schedule.id, schedule.cron);
+    }
+  }
+
+  /** Inserts a new job instance into the jobs table. */
+  private async enqueueJob(name: string, data: unknown): Promise<void> {
+    await sql`
+      INSERT INTO rangka_jobs (name, data, state, max_retries, backoff)
+      VALUES (${name}, ${JSON.stringify(data)}::jsonb, 'created', 0, 'exponential')
+    `.execute(this.db);
+  }
+
+  /** Updates a schedule's next_run_at and records last_run_at. */
+  private async advanceSchedule(scheduleId: string, cronExpr: string): Promise<void> {
+    const nextRun = this.computeNextRun(cronExpr);
+    await sql`
+      UPDATE rangka_scheduled_jobs
+      SET next_run_at = ${nextRun}, last_run_at = NOW()
+      WHERE id = ${scheduleId}
+    `.execute(this.db);
+  }
+
+  /** Returns true if a job with the given name is already created or active. */
+  private async hasPendingJob(name: string): Promise<boolean> {
+    const result = await sql<{ count: string }>`
+      SELECT COUNT(*) as count FROM rangka_jobs
+      WHERE name = ${name} AND state IN ('created', 'active')
+    `.execute(this.db);
+    return toCount(result.rows[0]) > 0;
+  }
+
+  /**
+   * Checks whether a single cron field expression matches the given value.
+   * Supports: wildcard (*), lists (1,5,10), ranges (1-5), and steps (star/5, 1-10/2).
+   */
+  private matchesCronField(expr: string, value: number, min: number, _max: number): boolean {
+    if (expr === '*') return true;
+
+    // A field can be a comma-separated list of segments
+    for (const segment of expr.split(',')) {
+      if (this.segmentMatches(segment, value, min)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /** Evaluates a single segment of a cron field (step, range, or literal). */
+  private segmentMatches(segment: string, value: number, fieldMin: number): boolean {
+    if (segment.includes('/')) {
+      // Step expression, e.g. "*/5" or "10-30/5"
+      const [rangeExpr, stepStr] = segment.split('/');
+      const step = parseInt(stepStr, 10);
+      const start = rangeExpr === '*' ? fieldMin : parseInt(rangeExpr, 10);
+      return value >= start && (value - start) % step === 0;
+    }
+
+    if (segment.includes('-')) {
+      // Range expression, e.g. "1-5"
+      const [startStr, endStr] = segment.split('-');
+      const rangeStart = parseInt(startStr, 10);
+      const rangeEnd = parseInt(endStr, 10);
+      return value >= rangeStart && value <= rangeEnd;
+    }
+
+    // Exact value, e.g. "30"
+    return parseInt(segment, 10) === value;
+  }
+}

package/src/jobs/tables.ts

@@ -0,0 +1,132 @@
+import type { TableDefinition } from '../db/types.js';
+
+export function getJobTables(): TableDefinition[] {
+  return [buildJobsTable(), buildDeadLettersTable(), buildScheduledJobsTable()];
+}
+
+function buildJobsTable(): TableDefinition {
+  return {
+    name: 'rangka_jobs',
+    columns: [
+      {
+        name: 'id',
+        type: 'UUID',
+        nullable: false,
+        primaryKey: true,
+        defaultValue: 'gen_random_uuid()',
+      },
+      { name: 'name', type: 'TEXT', nullable: false },
+      { name: 'data', type: 'JSONB', nullable: true },
+      { name: 'state', type: 'TEXT', nullable: false, defaultValue: "'created'" },
+      { name: 'retry_count', type: 'INTEGER', nullable: false, defaultValue: '0' },
+      { name: 'max_retries', type: 'INTEGER', nullable: false, defaultValue: '0' },
+      { name: 'backoff', type: 'TEXT', nullable: false, defaultValue: "'exponential'" },
+      { name: 'start_after', type: 'TIMESTAMPTZ', nullable: true },
+      { name: 'started_at', type: 'TIMESTAMPTZ', nullable: true },
+      { name: 'completed_at', type: 'TIMESTAMPTZ', nullable: true },
+      { name: 'failed_at', type: 'TIMESTAMPTZ', nullable: true },
+      { name: 'error', type: 'TEXT', nullable: true },
+      { name: 'unique_key', type: 'TEXT', nullable: true },
+      { name: 'created_at', type: 'TIMESTAMPTZ', nullable: false, defaultValue: 'NOW()' },
+      { name: 'expire_in', type: 'INTERVAL', nullable: false, defaultValue: "'15 minutes'" },
+    ],
+    foreignKeys: [],
+    checkConstraints: [
+      {
+        name: 'chk_rangka_jobs_state',
+        column: 'state',
+        expression: "state IN ('created', 'active', 'completed', 'failed')",
+      },
+    ],
+    indexes: [
+      {
+        name: 'idx_rangka_jobs_state_start_after',
+        table: 'rangka_jobs',
+        columns: ['state', 'start_after'],
+        unique: false,
+      },
+      {
+        name: 'idx_rangka_jobs_name_state',
+        table: 'rangka_jobs',
+        columns: ['name', 'state'],
+        unique: false,
+      },
+      {
+        name: 'idx_rangka_jobs_unique_key_active',
+        table: 'rangka_jobs',
+        columns: ['unique_key'],
+        unique: true,
+        where: "state IN ('created', 'active')",
+      },
+    ],
+  };
+}
+
+function buildDeadLettersTable(): TableDefinition {
+  return {
+    name: 'rangka_dead_letters',
+    columns: [
+      {
+        name: 'id',
+        type: 'UUID',
+        nullable: false,
+        primaryKey: true,
+        defaultValue: 'gen_random_uuid()',
+      },
+      { name: 'job_id', type: 'UUID', nullable: false },
+      { name: 'name', type: 'TEXT', nullable: false },
+      { name: 'data', type: 'JSONB', nullable: true },
+      { name: 'error', type: 'TEXT', nullable: true },
+      { name: 'retry_count', type: 'INTEGER', nullable: false, defaultValue: '0' },
+      { name: 'failed_at', type: 'TIMESTAMPTZ', nullable: false, defaultValue: 'NOW()' },
+      { name: 'created_at', type: 'TIMESTAMPTZ', nullable: false, defaultValue: 'NOW()' },
+    ],
+    foreignKeys: [],
+    checkConstraints: [],
+    indexes: [
+      {
+        name: 'idx_rangka_dead_letters_name',
+        table: 'rangka_dead_letters',
+        columns: ['name'],
+        unique: false,
+      },
+    ],
+  };
+}
+
+function buildScheduledJobsTable(): TableDefinition {
+  return {
+    name: 'rangka_scheduled_jobs',
+    columns: [
+      {
+        name: 'id',
+        type: 'UUID',
+        nullable: false,
+        primaryKey: true,
+        defaultValue: 'gen_random_uuid()',
+      },
+      { name: 'name', type: 'TEXT', nullable: false },
+      { name: 'cron', type: 'TEXT', nullable: false },
+      { name: 'data', type: 'JSONB', nullable: true },
+      { name: 'last_run_at', type: 'TIMESTAMPTZ', nullable: true },
+      { name: 'next_run_at', type: 'TIMESTAMPTZ', nullable: true },
+      { name: 'created_at', type: 'TIMESTAMPTZ', nullable: false, defaultValue: 'NOW()' },
+    ],
+    foreignKeys: [],
+    checkConstraints: [],
+    indexes: [
+      {
+        name: 'uidx_rangka_scheduled_jobs_name',
+        table: 'rangka_scheduled_jobs',
+        columns: ['name'],
+        unique: true,
+      },
+      {
+        name: 'idx_rangka_scheduled_jobs_next_run',
+        table: 'rangka_scheduled_jobs',
+        columns: ['next_run_at'],
+        unique: false,
+      },
+    ],
+  };
+}

package/src/jobs/types.ts

@@ -0,0 +1,62 @@
+import type { JobConfig } from '@rangka/shared';
+
+export type JobState = 'created' | 'active' | 'completed' | 'failed';
+
+export type BackoffStrategy = 'exponential' | 'linear' | 'fixed';
+
+export interface JobRecord {
+  id: string;
+  name: string;
+  data: unknown;
+  state: JobState;
+  retry_count: number;
+  max_retries: number;
+  backoff: BackoffStrategy;
+  start_after: Date | null;
+  started_at: Date | null;
+  completed_at: Date | null;
+  failed_at: Date | null;
+  error: string | null;
+  unique_key: string | null;
+  created_at: Date;
+  expire_in: string;
+}
+
+export interface DeadLetterRecord {
+  id: string;
+  job_id: string;
+  name: string;
+  data: unknown;
+  error: string | null;
+  retry_count: number;
+  failed_at: Date;
+  created_at: Date;
+}
+
+export interface ScheduledJobRecord {
+  id: string;
+  name: string;
+  cron: string;
+  data: unknown;
+  last_run_at: Date | null;
+  next_run_at: Date | null;
+  created_at: Date;
+}
+
+export interface JobWorkerConfig {
+  pollInterval?: number;
+  enabled?: boolean;
+}
+
+export interface RegisteredJob {
+  name: string;
+  config: JobConfig;
+}
+
+export interface EnqueueOptions {
+  delay?: number;
+  unique?: boolean;
+  uniqueKey?: string;
+  retries?: number;
+  backoff?: BackoffStrategy;
+}