@rangka/core 0.1.0 → 0.1.2

package/src/jobs/enqueue.ts

@@ -1,93 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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

@@ -1,92 +0,0 @@
-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

@@ -1,205 +0,0 @@
-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

@@ -1,132 +0,0 @@
-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

@@ -1,62 +0,0 @@
-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;
-}