@rangka/core 0.1.0 → 0.1.2

package/src/jobs/__tests__/enqueue.test.ts

@@ -1,77 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { enqueue } from '../enqueue.js';
-
-describe('enqueue', () => {
-  it('inserts a job with default options', async () => {
-    const rows = [{ id: 'job-1' }];
-
-    const mockExecute = vi.fn().mockResolvedValue({ rows });
-    vi.mock('kysely', async (importOriginal) => {
-      const actual = (await importOriginal()) as any;
-      return {
-        ...actual,
-        sql: new Proxy(actual.sql, {
-          apply: (target: any, thisArg: any, args: any[]) => {
-            const result = target.apply(thisArg, args);
-            result.execute = mockExecute;
-            return result;
-          },
-          get: (target: any, prop: string) => {
-            if (prop === '__esModule') return true;
-            return target[prop];
-          },
-        }),
-      };
-    });
-
-    // Since mocking kysely's sql tag is complex, we test the function signature and logic
-    // by verifying it accepts the correct parameters
-    expect(typeof enqueue).toBe('function');
-    expect(enqueue.length).toBeGreaterThanOrEqual(2);
-  });
-
-  it('computes start_after from delay option', () => {
-    const now = Date.now();
-    const delay = 5000;
-    const expected = new Date(now + delay);
-
-    // Verify the delay math is correct
-    expect(expected.getTime() - now).toBe(delay);
-  });
-
-  it('uses job name as uniqueKey when unique=true but no key specified', () => {
-    const options: { unique: boolean; uniqueKey?: string } = { unique: true };
-    const name = 'my_job';
-    const uniqueKey = options.unique ? (options.uniqueKey ?? name) : null;
-    expect(uniqueKey).toBe('my_job');
-  });
-
-  it('uses custom uniqueKey when provided', () => {
-    const options: { unique: boolean; uniqueKey?: string } = {
-      unique: true,
-      uniqueKey: 'custom:key',
-    };
-    const name = 'my_job';
-    const uniqueKey = options.unique ? (options.uniqueKey ?? name) : null;
-    expect(uniqueKey).toBe('custom:key');
-  });
-
-  it('sets null uniqueKey when unique is false', () => {
-    const options: { unique: boolean; uniqueKey?: string } = {
-      unique: false,
-      uniqueKey: 'ignored',
-    };
-    const uniqueKey = options.unique ? (options.uniqueKey ?? 'name') : null;
-    expect(uniqueKey).toBeNull();
-  });
-
-  it('defaults backoff to exponential', () => {
-    const backoff: string | undefined = undefined;
-    expect(backoff ?? 'exponential').toBe('exponential');
-  });
-
-  it('defaults retries to 0', () => {
-    const retries: number | undefined = undefined;
-    expect(retries ?? 0).toBe(0);
-  });
-});

package/src/jobs/__tests__/integration.test.ts

@@ -1,71 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { createHookContext } from '../../hooks/context.js';
-import { EventBus } from '../../events/bus.js';
-import type { SchemaRegistry } from '../../schema/registry.js';
-import type { RequestContext } from '../../auth/types.js';
-
-function mockSchema(): SchemaRegistry {
-  return { getAllModels: () => [] } as unknown as SchemaRegistry;
-}
-
-function mockAuth(): RequestContext {
-  return {
-    user: { id: '1', email: 'test@test.com' },
-    roles: ['Admin'],
-    scopeFilters: [],
-  } as unknown as RequestContext;
-}
-
-describe('Hook → EventBus integration', () => {
-  it('ctx.events.emit delegates to EventBus in sync mode', async () => {
-    const bus = new EventBus();
-    const handler = vi.fn().mockResolvedValue(undefined);
-    bus.on('invoice.created', handler);
-
-    const ctx = createHookContext({
-      trx: {},
-      schema: mockSchema(),
-      auth: mockAuth(),
-      eventBus: bus,
-    });
-
-    // emitWithTrx with sync falls through to sync handler
-    const mockEmitWithTrx = vi.fn().mockResolvedValue(undefined);
-    (bus as any).emitWithTrx = mockEmitWithTrx;
-
-    await ctx.events.emit('invoice.created', { id: '123' });
-
-    expect(mockEmitWithTrx).toHaveBeenCalledWith(
-      'invoice.created',
-      { id: '123' },
-      expect.anything(),
-    );
-  });
-
-  it('EventBus sync emit runs listener inline', async () => {
-    const bus = new EventBus();
-    const results: string[] = [];
-
-    bus.on('job.done', async (payload: unknown) => {
-      const p = payload as { name: string };
-      results.push(p.name);
-    });
-
-    await bus.emit('job.done', { name: 'test' }, { sync: true });
-    expect(results).toEqual(['test']);
-  });
-
-  it('EventBus registers event handler that JobWorker can call', async () => {
-    const bus = new EventBus();
-    const handler = vi.fn().mockResolvedValue(undefined);
-
-    bus.on('order.shipped', handler);
-
-    const listeners = bus.getListeners('order.shipped');
-    expect(listeners).toHaveLength(1);
-
-    // Simulate what the worker does: call the handler directly
-    await listeners[0].handler({ orderId: '456' });
-    expect(handler).toHaveBeenCalledWith({ orderId: '456' });
-  });
-});

package/src/jobs/__tests__/registry.test.ts

@@ -1,103 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { JobRegistry } from '../registry.js';
-
-describe('JobRegistry', () => {
-  const validHandler = async () => {};
-
-  it('registers a valid job', () => {
-    const registry = new JobRegistry();
-    registry.register('send_email', {
-      handler: validHandler,
-      concurrency: 5,
-      retries: 3,
-      backoff: 'exponential',
-    });
-
-    expect(registry.has('send_email')).toBe(true);
-    const job = registry.get('send_email');
-    expect(job?.name).toBe('send_email');
-    expect(job?.config.concurrency).toBe(5);
-  });
-
-  it('throws on duplicate name', () => {
-    const registry = new JobRegistry();
-    registry.register('job1', { handler: validHandler });
-
-    expect(() => registry.register('job1', { handler: validHandler })).toThrow(
-      'Job "job1" is already registered',
-    );
-  });
-
-  it('throws on invalid concurrency', () => {
-    const registry = new JobRegistry();
-
-    expect(() => registry.register('bad', { handler: validHandler, concurrency: 0 })).toThrow(
-      'Concurrency must be a positive integer',
-    );
-
-    expect(() => registry.register('bad2', { handler: validHandler, concurrency: -1 })).toThrow(
-      'Concurrency must be a positive integer',
-    );
-
-    expect(() => registry.register('bad3', { handler: validHandler, concurrency: 1.5 })).toThrow(
-      'Concurrency must be a positive integer',
-    );
-  });
-
-  it('throws on invalid retries', () => {
-    const registry = new JobRegistry();
-
-    expect(() => registry.register('bad', { handler: validHandler, retries: -1 })).toThrow(
-      'Retries must be a non-negative integer',
-    );
-  });
-
-  it('throws on invalid backoff', () => {
-    const registry = new JobRegistry();
-
-    expect(() =>
-      registry.register('bad', { handler: validHandler, backoff: 'unknown' as any }),
-    ).toThrow('Backoff must be one of');
-  });
-
-  it('throws on invalid cron schedule', () => {
-    const registry = new JobRegistry();
-
-    expect(() => registry.register('bad', { handler: validHandler, schedule: '* * *' })).toThrow(
-      'Schedule must be a valid 5-field cron expression',
-    );
-  });
-
-  it('accepts valid cron schedule', () => {
-    const registry = new JobRegistry();
-    registry.register('daily', { handler: validHandler, schedule: '0 2 * * *' });
-
-    expect(registry.has('daily')).toBe(true);
-  });
-
-  it('throws on missing handler', () => {
-    const registry = new JobRegistry();
-
-    expect(() => registry.register('bad', { handler: null as any })).toThrow(
-      'Job handler must be a function',
-    );
-  });
-
-  it('getAll returns all registered jobs', () => {
-    const registry = new JobRegistry();
-    registry.register('a', { handler: validHandler });
-    registry.register('b', { handler: validHandler });
-
-    expect(registry.getAll()).toHaveLength(2);
-  });
-
-  it('getScheduled returns only jobs with a schedule', () => {
-    const registry = new JobRegistry();
-    registry.register('a', { handler: validHandler });
-    registry.register('b', { handler: validHandler, schedule: '0 * * * *' });
-
-    const scheduled = registry.getScheduled();
-    expect(scheduled).toHaveLength(1);
-    expect(scheduled[0].name).toBe('b');
-  });
-});

package/src/jobs/__tests__/scheduler.test.ts

@@ -1,92 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { ScheduleManager } from '../scheduler.js';
-import { JobRegistry } from '../registry.js';
-
-describe('ScheduleManager', () => {
-  const registry = new JobRegistry();
-  const mockDb = {} as any;
-  const manager = new ScheduleManager(mockDb, registry, 5000);
-
-  describe('computeNextRun', () => {
-    it('parses simple cron: every hour at minute 0', () => {
-      const from = new Date('2026-01-15T10:00:00Z');
-      const next = manager.computeNextRun('0 * * * *', from);
-      expect(next.getMinutes()).toBe(0);
-      expect(next.getTime()).toBeGreaterThan(from.getTime());
-    });
-
-    it('parses cron: daily at 2 AM', () => {
-      const from = new Date('2026-01-15T03:00:00Z');
-      const next = manager.computeNextRun('0 2 * * *', from);
-      expect(next.getHours()).toBe(2);
-      expect(next.getMinutes()).toBe(0);
-      expect(next.getDate()).toBe(16); // next day since 2AM already passed
-    });
-
-    it('parses cron: every 5 minutes', () => {
-      const from = new Date('2026-01-15T10:02:00Z');
-      const next = manager.computeNextRun('*/5 * * * *', from);
-      expect(next.getMinutes() % 5).toBe(0);
-      expect(next.getTime()).toBeGreaterThan(from.getTime());
-    });
-
-    it('parses cron: specific day of week (Monday = 1)', () => {
-      const from = new Date('2026-01-15T00:00:00Z'); // Wednesday
-      const next = manager.computeNextRun('0 9 * * 1', from);
-      expect(next.getDay()).toBe(1); // Monday
-      expect(next.getHours()).toBe(9);
-    });
-
-    it('parses cron: specific day of month', () => {
-      const from = new Date('2026-01-15T00:00:00Z');
-      const next = manager.computeNextRun('30 8 20 * *', from);
-      expect(next.getDate()).toBe(20);
-      expect(next.getHours()).toBe(8);
-      expect(next.getMinutes()).toBe(30);
-    });
-
-    it('parses cron with ranges', () => {
-      const from = new Date('2026-01-15T10:00:00Z');
-      const next = manager.computeNextRun('0 9-17 * * *', from);
-      expect(next.getHours()).toBeGreaterThanOrEqual(9);
-      expect(next.getHours()).toBeLessThanOrEqual(17);
-    });
-
-    it('parses cron with comma-separated values', () => {
-      const from = new Date('2026-01-15T10:00:00Z');
-      const next = manager.computeNextRun('0,30 * * * *', from);
-      expect([0, 30]).toContain(next.getMinutes());
-    });
-
-    it('throws on invalid cron expression', () => {
-      expect(() => manager.computeNextRun('* * *')).toThrow('Invalid cron expression');
-    });
-
-    it('next run is always in the future', () => {
-      const from = new Date('2026-01-15T10:30:00Z');
-      const next = manager.computeNextRun('30 10 * * *', from);
-      expect(next.getTime()).toBeGreaterThan(from.getTime());
-    });
-  });
-
-  describe('lifecycle', () => {
-    it('starts and stops', async () => {
-      const mgr = new ScheduleManager(mockDb, registry, 60000);
-      expect(mgr.isRunning()).toBe(false);
-
-      mgr.start();
-      expect(mgr.isRunning()).toBe(true);
-
-      await mgr.stop();
-      expect(mgr.isRunning()).toBe(false);
-    });
-
-    it('does not double-start', async () => {
-      const mgr = new ScheduleManager(mockDb, registry, 60000);
-      mgr.start();
-      mgr.start();
-      expect(mgr.isRunning()).toBe(true);
-      await mgr.stop();
-    });
-  });
-});

package/src/jobs/__tests__/worker-execution.test.ts

@@ -1,202 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { JobWorker } from '../worker.js';
-import { JobRegistry } from '../registry.js';
-
-describe('JobWorker execution', () => {
-  const mockCtx = {
-    db: {},
-    schema: {},
-    auth: { user: null, roles: [] },
-    scope: null,
-    config: {},
-    models: {},
-    service: () => ({}),
-    enqueue: async () => {},
-    events: { emit: async () => {}, on: () => {} },
-    notify: () => {},
-    email: { send: async () => {} },
-  } as any;
-
-  beforeEach(() => {
-    vi.useFakeTimers();
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  describe('handler invocation', () => {
-    it('calls handler with job data and ctx', async () => {
-      vi.useRealTimers();
-      const registry = new JobRegistry();
-      const handler = vi.fn().mockRejectedValue(new Error('stop'));
-      registry.register('test.job', { handler });
-
-      const mockDb = {} as any;
-      const worker = new JobWorker(mockDb, registry, mockCtx, { pollInterval: 100 });
-
-      const executeJob = (worker as any).executeJob.bind(worker);
-      // Will throw in handleFailure since no real DB, but handler should have been called
-      try {
-        await executeJob({
-          id: 'job-1',
-          name: 'test.job',
-          data: { key: 'value' },
-          state: 'active',
-          retry_count: 0,
-          max_retries: 0,
-          backoff: 'exponential',
-        });
-      } catch {
-        /* expected */
-      }
-
-      expect(handler).toHaveBeenCalledWith({ key: 'value' }, mockCtx);
-    });
-
-    it('does not call handler for unregistered job', async () => {
-      vi.useRealTimers();
-      const registry = new JobRegistry();
-      const mockDb = {} as any;
-      const worker = new JobWorker(mockDb, registry, mockCtx, { pollInterval: 100 });
-
-      const executeJob = (worker as any).executeJob.bind(worker);
-      await executeJob({
-        id: 'job-1',
-        name: 'unknown.job',
-        data: {},
-        state: 'active',
-        retry_count: 0,
-        max_retries: 0,
-        backoff: 'exponential',
-      });
-
-      expect(worker.getInFlightCount()).toBe(0);
-    });
-  });
-
-  describe('backoff computation', () => {
-    it('exponential: doubles with each retry, capped at 600s', () => {
-      const registry = new JobRegistry();
-      const mockDb = {} as any;
-      const worker = new JobWorker(mockDb, registry, mockCtx);
-
-      const compute = (worker as any).computeBackoffDelay.bind(worker);
-      expect(compute('exponential', 1)).toBe(2000);
-      expect(compute('exponential', 2)).toBe(4000);
-      expect(compute('exponential', 3)).toBe(8000);
-      expect(compute('exponential', 10)).toBe(600000); // capped
-      expect(compute('exponential', 20)).toBe(600000); // still capped
-    });
-
-    it('linear: 10s * retryCount', () => {
-      const registry = new JobRegistry();
-      const mockDb = {} as any;
-      const worker = new JobWorker(mockDb, registry, mockCtx);
-
-      const compute = (worker as any).computeBackoffDelay.bind(worker);
-      expect(compute('linear', 1)).toBe(10000);
-      expect(compute('linear', 2)).toBe(20000);
-      expect(compute('linear', 5)).toBe(50000);
-    });
-
-    it('fixed: always 5s', () => {
-      const registry = new JobRegistry();
-      const mockDb = {} as any;
-      const worker = new JobWorker(mockDb, registry, mockCtx);
-
-      const compute = (worker as any).computeBackoffDelay.bind(worker);
-      expect(compute('fixed', 1)).toBe(5000);
-      expect(compute('fixed', 5)).toBe(5000);
-      expect(compute('fixed', 100)).toBe(5000);
-    });
-  });
-
-  describe('concurrency limit check', () => {
-    it('returns false when no limit set (Infinity)', async () => {
-      const registry = new JobRegistry();
-      const mockDb = {} as any;
-      const worker = new JobWorker(mockDb, registry, mockCtx);
-
-      const exceeds = (worker as any).exceedsConcurrencyLimit.bind(worker);
-      const result = await exceeds('test.job', undefined);
-      expect(result).toBe(false);
-    });
-
-    it('returns false when limit is Infinity', async () => {
-      const registry = new JobRegistry();
-      const mockDb = {} as any;
-      const worker = new JobWorker(mockDb, registry, mockCtx);
-
-      const exceeds = (worker as any).exceedsConcurrencyLimit.bind(worker);
-      const result = await exceeds('test.job', Infinity);
-      expect(result).toBe(false);
-    });
-  });
-
-  describe('graceful shutdown', () => {
-    it('stop resolves immediately when no jobs in flight', async () => {
-      const registry = new JobRegistry();
-      const mockDb = {} as any;
-      const worker = new JobWorker(mockDb, registry, mockCtx, { pollInterval: 10000 });
-
-      worker.start();
-      expect(worker.isRunning()).toBe(true);
-
-      await worker.stop();
-      expect(worker.isRunning()).toBe(false);
-      expect(worker.getInFlightCount()).toBe(0);
-    });
-
-    it('tracks in-flight jobs correctly during execution', async () => {
-      vi.useRealTimers();
-
-      const registry = new JobRegistry();
-      let resolveHandler: () => void;
-      const handlerPromise = new Promise<void>((r) => {
-        resolveHandler = r;
-      });
-
-      registry.register('test.slow', {
-        handler: async () => {
-          await handlerPromise;
-        },
-      });
-
-      const mockDb = {} as any;
-      const worker = new JobWorker(mockDb, registry, mockCtx);
-
-      // Simulate adding to in-flight
-      (worker as any).activeJobIds.add('job-1');
-      expect(worker.getInFlightCount()).toBe(1);
-
-      (worker as any).activeJobIds.delete('job-1');
-      expect(worker.getInFlightCount()).toBe(0);
-
-      resolveHandler!();
-    });
-  });
-
-  describe('failure handling decision', () => {
-    it('moves to dead letter when retry_count + 1 > max_retries', () => {
-      // retry_count = 2, max_retries = 2 → attemptNumber = 3 > 2 → dead letter
-      const attemptNumber = 2 + 1;
-      const maxRetries = 2;
-      expect(attemptNumber > maxRetries).toBe(true);
-    });
-
-    it('schedules retry when retry_count + 1 <= max_retries', () => {
-      // retry_count = 0, max_retries = 2 → attemptNumber = 1 <= 2 → retry
-      const attemptNumber = 0 + 1;
-      const maxRetries = 2;
-      expect(attemptNumber > maxRetries).toBe(false);
-    });
-
-    it('zero retries means immediate dead letter on first failure', () => {
-      // retry_count = 0, max_retries = 0 → attemptNumber = 1 > 0 → dead letter
-      const attemptNumber = 0 + 1;
-      const maxRetries = 0;
-      expect(attemptNumber > maxRetries).toBe(true);
-    });
-  });
-});

package/src/jobs/__tests__/worker.test.ts

@@ -1,119 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { JobWorker } from '../worker.js';
-import { JobRegistry } from '../registry.js';
-
-describe('JobWorker', () => {
-  let registry: JobRegistry;
-
-  beforeEach(() => {
-    registry = new JobRegistry();
-    vi.useFakeTimers();
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  const mockCtx = {} as any;
-
-  it('starts and stops cleanly', async () => {
-    const mockDb = {} as any;
-    const worker = new JobWorker(mockDb, registry, mockCtx, { pollInterval: 100 });
-
-    expect(worker.isRunning()).toBe(false);
-    worker.start();
-    expect(worker.isRunning()).toBe(true);
-
-    await worker.stop();
-    expect(worker.isRunning()).toBe(false);
-  });
-
-  it('does not double-start', () => {
-    const mockDb = {} as any;
-    const worker = new JobWorker(mockDb, registry, mockCtx, { pollInterval: 100 });
-
-    worker.start();
-    worker.start();
-    expect(worker.isRunning()).toBe(true);
-  });
-
-  it('stop is a no-op when not running', async () => {
-    const mockDb = {} as any;
-    const worker = new JobWorker(mockDb, registry, mockCtx, { pollInterval: 100 });
-
-    await worker.stop();
-    expect(worker.isRunning()).toBe(false);
-  });
-
-  it('defaults pollInterval to 2000ms', () => {
-    const mockDb = {} as any;
-    const worker = new JobWorker(mockDb, registry, mockCtx);
-    // Access via starting — the timer would fire at 2000ms intervals
-    expect(worker.isRunning()).toBe(false);
-  });
-
-  it('tracks in-flight count', () => {
-    const mockDb = {} as any;
-    const worker = new JobWorker(mockDb, registry, mockCtx, { pollInterval: 100 });
-
-    expect(worker.getInFlightCount()).toBe(0);
-  });
-
-  describe('computeBackoffDelay logic', () => {
-    it('exponential backoff doubles with each retry', () => {
-      // Testing the math: 1000 * 2^retry, capped at 600000
-      expect(1000 * Math.pow(2, 1)).toBe(2000);
-      expect(1000 * Math.pow(2, 2)).toBe(4000);
-      expect(1000 * Math.pow(2, 3)).toBe(8000);
-      expect(Math.min(1000 * Math.pow(2, 20), 600000)).toBe(600000);
-    });
-
-    it('linear backoff increases linearly', () => {
-      expect(10000 * 1).toBe(10000);
-      expect(10000 * 2).toBe(20000);
-      expect(10000 * 3).toBe(30000);
-    });
-
-    it('fixed backoff is constant', () => {
-      expect(5000).toBe(5000);
-    });
-  });
-
-  describe('job execution', () => {
-    it('calls handler with job data on success', async () => {
-      const handler = vi.fn().mockResolvedValue(undefined);
-      registry.register('test_job', { handler });
-
-      // Verify the handler is registered and callable
-      const job = registry.get('test_job');
-      expect(job).toBeDefined();
-      await job!.config.handler({ foo: 'bar' }, {} as any);
-      expect(handler).toHaveBeenCalledWith({ foo: 'bar' }, expect.anything());
-    });
-
-    it('handler failure is catchable', async () => {
-      const handler = vi.fn().mockRejectedValue(new Error('boom'));
-      registry.register('fail_job', { handler, retries: 2, backoff: 'fixed' });
-
-      const job = registry.get('fail_job');
-      await expect(job!.config.handler({}, {} as any)).rejects.toThrow('boom');
-    });
-  });
-
-  describe('dead letter logic', () => {
-    it('moves to dead letter after max retries exceeded', () => {
-      // retry_count + 1 > max_retries means dead letter
-      const retryCount = 3;
-      const maxRetries = 3;
-      const newRetryCount = retryCount + 1;
-      expect(newRetryCount > maxRetries).toBe(true);
-    });
-
-    it('retries when under max', () => {
-      const retryCount = 1;
-      const maxRetries = 3;
-      const newRetryCount = retryCount + 1;
-      expect(newRetryCount > maxRetries).toBe(false);
-    });
-  });
-});