@spfn/core 0.1.0-alpha.88 → 0.2.0-beta.10

package/dist/job/index.d.ts

@@ -0,0 +1,218 @@
+import { a as JobOptions, C as CompensateHandler, b as JobHandler, c as JobDef, d as JobRouterEntry, J as JobRouter } from '../boss-DI1r4kTS.js';
+export { k as BossConfig, B as BossOptions, I as InferJobInput, f as InferJobOutput, e as JobSendOptions, g as getBoss, i as initBoss, h as isBossRunning, j as shouldClearOnStart, s as stopBoss } from '../boss-DI1r4kTS.js';
+import * as _sinclair_typebox from '@sinclair/typebox';
+import { Static } from '@sinclair/typebox';
+import { EventDef, InferEventPayload } from '@spfn/core/event';
+import 'pg-boss';
+
+/**
+ * Job builder class with fluent API
+ */
+declare class JobBuilder<TInput = void, TOutput = void> {
+    private readonly _name;
+    private _inputSchema?;
+    private _outputSchema?;
+    private _cronExpression?;
+    private _runOnce?;
+    private _subscribedEvent?;
+    private _subscribedEventDef?;
+    private _options?;
+    private _handler?;
+    private _compensate?;
+    constructor(name: string);
+    /**
+     * Define input schema with TypeBox
+     */
+    input<TSchema extends _sinclair_typebox.TSchema>(schema: TSchema): JobBuilder<Static<TSchema>, TOutput>;
+    /**
+     * Define output schema with TypeBox (for workflow integration)
+     */
+    output<TSchema extends _sinclair_typebox.TSchema>(schema: TSchema): JobBuilder<TInput, Static<TSchema>>;
+    /**
+     * Subscribe to an event (decoupled triggering)
+     *
+     * @example
+     * ```typescript
+     * const userCreated = defineEvent('user.created', Type.Object({
+     *     userId: Type.String(),
+     * }));
+     *
+     * const sendWelcomeEmail = job('send-welcome-email')
+     *     .on(userCreated)
+     *     .handler(async (payload) => {
+     *         // payload is typed as { userId: string }
+     *     });
+     * ```
+     */
+    on<TEvent extends EventDef<any>>(event: TEvent): JobBuilder<InferEventPayload<TEvent>, TOutput>;
+    /**
+     * Set cron expression for scheduled execution
+     */
+    cron(expression: string): this;
+    /**
+     * Mark job to run once on server start
+     */
+    runOnce(): this;
+    /**
+     * Set job options (retry, expiration, etc.)
+     */
+    options(options: JobOptions): this;
+    /**
+     * Set job timeout in milliseconds
+     * (Converts to expireInSeconds for pg-boss)
+     */
+    timeout(ms: number): this;
+    /**
+     * Define compensate handler for rollback (workflow integration)
+     */
+    compensate(fn: CompensateHandler<TInput, TOutput>): this;
+    /**
+     * Define the job handler and finalize the job definition
+     */
+    handler(fn: JobHandler<TInput, TOutput>): JobDef<TInput, TOutput>;
+}
+/**
+ * Create a new job definition
+ *
+ * @example
+ * ```typescript
+ * // Simple job without input
+ * export const cleanupJob = job('cleanup')
+ *     .handler(async () => {
+ *         await db.cleanup();
+ *     });
+ *
+ * // Job with typed input
+ * export const sendEmailJob = job('send-email')
+ *     .input(Type.Object({
+ *         to: Type.String(),
+ *         subject: Type.String(),
+ *         body: Type.String(),
+ *     }))
+ *     .handler(async (input) => {
+ *         await emailService.send(input.to, input.subject, input.body);
+ *     });
+ *
+ * // Cron job
+ * export const dailyReportJob = job('daily-report')
+ *     .cron('0 9 * * *')
+ *     .handler(async () => {
+ *         await reportService.generateDaily();
+ *     });
+ *
+ * // Run once on server start
+ * export const initCacheJob = job('init-cache')
+ *     .runOnce()
+ *     .handler(async () => {
+ *         await cache.warmup();
+ *     });
+ *
+ * // With options
+ * export const importantJob = job('important-task')
+ *     .input(Type.Object({ id: Type.String() }))
+ *     .options({
+ *         retryLimit: 5,
+ *         retryDelay: 5000,
+ *         priority: 10,
+ *     })
+ *     .handler(async (input) => {
+ *         await processImportant(input.id);
+ *     });
+ * ```
+ */
+declare function job(name: string): JobBuilder<void>;
+
+/**
+ * Job Router
+ *
+ * Groups job definitions for registration with the server
+ */
+
+/**
+ * Type guard to check if value is a JobDef
+ */
+declare function isJobDef(value: unknown): value is JobDef<any>;
+/**
+ * Type guard to check if value is a JobRouter
+ */
+declare function isJobRouter(value: unknown): value is JobRouter<any>;
+/**
+ * Define a job router to group jobs together
+ *
+ * @example
+ * ```typescript
+ * // Flat structure
+ * export const jobRouter = defineJobRouter({
+ *     sendWelcomeEmail,
+ *     dailyReport,
+ *     initCache,
+ * });
+ *
+ * // Nested structure
+ * export const jobRouter = defineJobRouter({
+ *     email: defineJobRouter({
+ *         sendWelcome: sendWelcomeEmailJob,
+ *         sendReset: sendResetPasswordJob,
+ *     }),
+ *     reports: defineJobRouter({
+ *         daily: dailyReportJob,
+ *         weekly: weeklyReportJob,
+ *     }),
+ * });
+ *
+ * // Mixed
+ * export const jobRouter = defineJobRouter({
+ *     initCache,  // flat
+ *     email: defineJobRouter({ ... }),  // nested
+ * });
+ * ```
+ */
+declare function defineJobRouter<TJobs extends Record<string, JobRouterEntry>>(jobs: TJobs): JobRouter<TJobs>;
+/**
+ * Collect all JobDefs from a JobRouter (including nested)
+ */
+declare function collectJobs(router: JobRouter<any>, prefix?: string): JobDef<any>[];
+
+/**
+ * Job Registration
+ *
+ * Registers jobs with pg-boss
+ */
+
+/**
+ * Register all jobs from a JobRouter with pg-boss
+ *
+ * This function:
+ * 1. Collects all jobs from the router (including nested routers)
+ * 2. Optionally clears existing jobs (if clearOnStart is enabled)
+ * 3. Registers each job's worker handler with pg-boss
+ * 4. Sets up cron schedules for scheduled jobs
+ * 5. Queues runOnce jobs
+ * 6. Connects event subscriptions to job queues
+ *
+ * @param router - JobRouter containing job definitions
+ *
+ * @example
+ * ```typescript
+ * // Define jobs
+ * const sendEmail = job('send-email')
+ *     .input(Type.Object({ to: Type.String() }))
+ *     .handler(async (input) => { ... });
+ *
+ * const dailyReport = job('daily-report')
+ *     .cron('0 9 * * *')
+ *     .handler(async () => { ... });
+ *
+ * // Create router
+ * const jobRouter = defineJobRouter({ sendEmail, dailyReport });
+ *
+ * // Initialize pg-boss first
+ * await initBoss({ connectionString: process.env.DATABASE_URL! });
+ *
+ * // Register jobs
+ * await registerJobs(jobRouter);
+ * ```
+ */
+declare function registerJobs(router: JobRouter<any>): Promise<void>;
+
+export { CompensateHandler, JobDef, JobHandler, JobOptions, JobRouter, JobRouterEntry, collectJobs, defineJobRouter, isJobDef, isJobRouter, job, registerJobs };

package/dist/job/index.js

@@ -0,0 +1,410 @@
+import PgBoss from 'pg-boss';
+import { logger } from '@spfn/core/logger';
+
+// src/job/boss.ts
+var jobLogger = logger.child("@spfn/core:job");
+var bossInstance = null;
+var bossConfig = null;
+async function initBoss(options) {
+  if (bossInstance) {
+    jobLogger.warn("pg-boss already initialized, returning existing instance");
+    return bossInstance;
+  }
+  jobLogger.info("Initializing pg-boss...");
+  bossConfig = options;
+  const pgBossOptions = {
+    connectionString: options.connectionString,
+    schema: options.schema ?? "spfn_queue",
+    maintenanceIntervalSeconds: options.maintenanceIntervalSeconds ?? 120
+  };
+  if (options.monitorIntervalSeconds !== void 0 && options.monitorIntervalSeconds >= 1) {
+    pgBossOptions.monitorIntervalSeconds = options.monitorIntervalSeconds;
+  }
+  bossInstance = new PgBoss(pgBossOptions);
+  bossInstance.on("error", (error) => {
+    jobLogger.error("pg-boss error:", error);
+  });
+  await bossInstance.start();
+  jobLogger.info("pg-boss started successfully");
+  return bossInstance;
+}
+function getBoss() {
+  return bossInstance;
+}
+async function stopBoss() {
+  if (!bossInstance) {
+    return;
+  }
+  jobLogger.info("Stopping pg-boss...");
+  try {
+    await bossInstance.stop({ graceful: true, timeout: 3e4 });
+    jobLogger.info("pg-boss stopped gracefully");
+  } catch (error) {
+    jobLogger.error("Error stopping pg-boss:", error);
+    throw error;
+  } finally {
+    bossInstance = null;
+    bossConfig = null;
+  }
+}
+function isBossRunning() {
+  return bossInstance !== null;
+}
+function shouldClearOnStart() {
+  return bossConfig?.clearOnStart ?? false;
+}
+
+// src/job/job-builder.ts
+function buildPgBossOptions(defaults, sendOptions) {
+  const options = {};
+  if (sendOptions?.startAfter) {
+    options.startAfter = sendOptions.startAfter;
+  }
+  if (sendOptions?.singletonKey) {
+    options.singletonKey = sendOptions.singletonKey;
+  }
+  if (sendOptions?.priority !== void 0) {
+    options.priority = sendOptions.priority;
+  }
+  if (defaults?.retryLimit !== void 0) {
+    options.retryLimit = defaults.retryLimit;
+  }
+  if (defaults?.retryDelay !== void 0) {
+    options.retryDelay = defaults.retryDelay;
+  }
+  if (defaults?.expireInSeconds !== void 0) {
+    options.expireInSeconds = defaults.expireInSeconds;
+  }
+  if (defaults?.priority !== void 0 && sendOptions?.priority === void 0) {
+    options.priority = defaults.priority;
+  }
+  if (defaults?.singletonKey && !sendOptions?.singletonKey) {
+    options.singletonKey = defaults.singletonKey;
+  }
+  if (defaults?.retentionSeconds !== void 0) {
+    options.retentionSeconds = defaults.retentionSeconds;
+  }
+  return options;
+}
+var JobBuilder = class _JobBuilder {
+  _name;
+  _inputSchema;
+  _outputSchema;
+  _cronExpression;
+  _runOnce;
+  _subscribedEvent;
+  _subscribedEventDef;
+  _options;
+  _handler;
+  _compensate;
+  constructor(name) {
+    this._name = name;
+  }
+  /**
+   * Define input schema with TypeBox
+   */
+  input(schema) {
+    const builder = new _JobBuilder(this._name);
+    builder._inputSchema = schema;
+    builder._outputSchema = this._outputSchema;
+    builder._cronExpression = this._cronExpression;
+    builder._runOnce = this._runOnce;
+    builder._subscribedEvent = this._subscribedEvent;
+    builder._options = this._options;
+    return builder;
+  }
+  /**
+   * Define output schema with TypeBox (for workflow integration)
+   */
+  output(schema) {
+    const builder = new _JobBuilder(this._name);
+    builder._inputSchema = this._inputSchema;
+    builder._outputSchema = schema;
+    builder._cronExpression = this._cronExpression;
+    builder._runOnce = this._runOnce;
+    builder._subscribedEvent = this._subscribedEvent;
+    builder._options = this._options;
+    return builder;
+  }
+  /**
+   * Subscribe to an event (decoupled triggering)
+   *
+   * @example
+   * ```typescript
+   * const userCreated = defineEvent('user.created', Type.Object({
+   *     userId: Type.String(),
+   * }));
+   *
+   * const sendWelcomeEmail = job('send-welcome-email')
+   *     .on(userCreated)
+   *     .handler(async (payload) => {
+   *         // payload is typed as { userId: string }
+   *     });
+   * ```
+   */
+  on(event) {
+    const builder = new _JobBuilder(this._name);
+    builder._inputSchema = event.schema;
+    builder._outputSchema = this._outputSchema;
+    builder._subscribedEvent = event.name;
+    builder._subscribedEventDef = event;
+    builder._cronExpression = this._cronExpression;
+    builder._runOnce = this._runOnce;
+    builder._options = this._options;
+    return builder;
+  }
+  /**
+   * Set cron expression for scheduled execution
+   */
+  cron(expression) {
+    this._cronExpression = expression;
+    return this;
+  }
+  /**
+   * Mark job to run once on server start
+   */
+  runOnce() {
+    this._runOnce = true;
+    return this;
+  }
+  /**
+   * Set job options (retry, expiration, etc.)
+   */
+  options(options) {
+    this._options = options;
+    return this;
+  }
+  /**
+   * Set job timeout in milliseconds
+   * (Converts to expireInSeconds for pg-boss)
+   */
+  timeout(ms) {
+    this._options = {
+      ...this._options,
+      expireInSeconds: Math.ceil(ms / 1e3)
+    };
+    return this;
+  }
+  /**
+   * Define compensate handler for rollback (workflow integration)
+   */
+  compensate(fn) {
+    this._compensate = fn;
+    return this;
+  }
+  /**
+   * Define the job handler and finalize the job definition
+   */
+  handler(fn) {
+    this._handler = fn;
+    const name = this._name;
+    const inputSchema = this._inputSchema;
+    const outputSchema = this._outputSchema;
+    const cronExpression = this._cronExpression;
+    const runOnce = this._runOnce;
+    const subscribedEvent = this._subscribedEvent;
+    const subscribedEventDef = this._subscribedEventDef;
+    const options = this._options;
+    const handler = this._handler;
+    const compensate = this._compensate;
+    const send = async (inputOrOptions, maybeOptions) => {
+      const boss = getBoss();
+      if (!boss) {
+        throw new Error(
+          `[Job:${name}] pg-boss not initialized. Ensure jobs are registered with defineServerConfig().jobs()`
+        );
+      }
+      const [input, sendOptions] = inputSchema ? [inputOrOptions, maybeOptions] : [void 0, inputOrOptions];
+      return await boss.send(
+        name,
+        input ?? {},
+        buildPgBossOptions(options, sendOptions)
+      );
+    };
+    const run = async (input) => {
+      if (inputSchema) {
+        return await handler(input);
+      } else {
+        return await handler();
+      }
+    };
+    return {
+      name,
+      inputSchema,
+      outputSchema,
+      cronExpression,
+      runOnce,
+      subscribedEvent,
+      _subscribedEventDef: subscribedEventDef,
+      options,
+      handler,
+      compensate,
+      send,
+      run,
+      _input: void 0,
+      _output: void 0
+    };
+  }
+};
+function job(name) {
+  return new JobBuilder(name);
+}
+
+// src/job/job-router.ts
+function isJobDef(value) {
+  return value !== null && typeof value === "object" && "name" in value && "handler" in value && "send" in value && "run" in value;
+}
+function isJobRouter(value) {
+  return value !== null && typeof value === "object" && "jobs" in value && "_jobs" in value;
+}
+function defineJobRouter(jobs) {
+  return {
+    jobs,
+    _jobs: jobs
+  };
+}
+function collectJobs(router, prefix = "") {
+  const jobs = [];
+  for (const [key, value] of Object.entries(router.jobs)) {
+    const name = prefix ? `${prefix}.${key}` : key;
+    if (isJobRouter(value)) {
+      jobs.push(...collectJobs(value, name));
+    } else if (isJobDef(value)) {
+      jobs.push(value);
+    }
+  }
+  return jobs;
+}
+var jobLogger2 = logger.child("@spfn/core:job");
+function getEventQueueName(eventName) {
+  return `event:${eventName}`;
+}
+function getDefaultJobOptions(options) {
+  return {
+    retryLimit: options?.retryLimit ?? 3,
+    retryDelay: options?.retryDelay ?? 1e3,
+    expireInSeconds: options?.expireInSeconds ?? 300
+  };
+}
+async function registerJobs(router) {
+  const boss = getBoss();
+  if (!boss) {
+    throw new Error(
+      "pg-boss not initialized. Call initBoss() before registerJobs()"
+    );
+  }
+  const jobs = collectJobs(router);
+  const clearOnStart = shouldClearOnStart();
+  jobLogger2.info(`Registering ${jobs.length} job(s)...`);
+  if (clearOnStart) {
+    jobLogger2.info("Clearing existing jobs before registration...");
+    for (const job2 of jobs) {
+      await boss.deleteAllJobs(job2.name);
+      if (job2.subscribedEvent) {
+        const eventQueue = getEventQueueName(job2.subscribedEvent);
+        await boss.deleteAllJobs(eventQueue);
+      }
+    }
+    jobLogger2.info("Existing jobs cleared");
+  }
+  for (const job2 of jobs) {
+    await registerJob(job2);
+  }
+  jobLogger2.info("All jobs registered successfully");
+}
+async function ensureQueue(boss, queueName) {
+  await boss.createQueue(queueName);
+}
+async function registerWorker(boss, job2, queueName) {
+  await ensureQueue(boss, queueName);
+  await boss.work(
+    queueName,
+    { batchSize: 1 },
+    async (jobs) => {
+      for (const pgBossJob of jobs) {
+        jobLogger2.debug(`[Job:${job2.name}] Executing...`, { jobId: pgBossJob.id });
+        const startTime = Date.now();
+        try {
+          if (job2.inputSchema) {
+            await job2.handler(pgBossJob.data);
+          } else {
+            await job2.handler();
+          }
+          const duration = Date.now() - startTime;
+          jobLogger2.info(`[Job:${job2.name}] Completed in ${duration}ms`, {
+            jobId: pgBossJob.id,
+            duration
+          });
+        } catch (error) {
+          const duration = Date.now() - startTime;
+          jobLogger2.error(`[Job:${job2.name}] Failed after ${duration}ms`, {
+            jobId: pgBossJob.id,
+            duration,
+            error: error instanceof Error ? error.message : String(error)
+          });
+          throw error;
+        }
+      }
+    }
+  );
+}
+function connectEventToQueue(boss, job2, queueName) {
+  if (!job2._subscribedEventDef) {
+    return;
+  }
+  const eventDef = job2._subscribedEventDef;
+  eventDef._registerJobQueue(queueName, async (queue, payload) => {
+    await boss.send(queue, payload, getDefaultJobOptions(job2.options));
+  });
+  jobLogger2.debug(`[Job:${job2.name}] Connected to event: ${job2.subscribedEvent}`);
+}
+async function registerCronSchedule(boss, job2) {
+  if (!job2.cronExpression) {
+    return;
+  }
+  jobLogger2.debug(`[Job:${job2.name}] Scheduling cron: ${job2.cronExpression}`);
+  await ensureQueue(boss, job2.name);
+  await boss.schedule(
+    job2.name,
+    job2.cronExpression,
+    {},
+    getDefaultJobOptions(job2.options)
+  );
+  jobLogger2.info(`[Job:${job2.name}] Cron scheduled: ${job2.cronExpression}`);
+}
+async function queueRunOnceJob(boss, job2) {
+  if (!job2.runOnce) {
+    return;
+  }
+  jobLogger2.debug(`[Job:${job2.name}] Queuing runOnce job`);
+  await ensureQueue(boss, job2.name);
+  await boss.send(
+    job2.name,
+    {},
+    {
+      ...getDefaultJobOptions(job2.options),
+      singletonKey: `runOnce:${job2.name}`
+    }
+  );
+  jobLogger2.info(`[Job:${job2.name}] runOnce job queued`);
+}
+async function registerJob(job2) {
+  const boss = getBoss();
+  if (!boss) {
+    throw new Error("pg-boss not initialized");
+  }
+  const queueName = job2.subscribedEvent ? getEventQueueName(job2.subscribedEvent) : job2.name;
+  jobLogger2.debug(`Registering job: ${job2.name}`, {
+    queueName,
+    subscribedEvent: job2.subscribedEvent
+  });
+  await registerWorker(boss, job2, queueName);
+  connectEventToQueue(boss, job2, queueName);
+  await registerCronSchedule(boss, job2);
+  await queueRunOnceJob(boss, job2);
+  jobLogger2.debug(`Job registered: ${job2.name}`);
+}
+
+export { collectJobs, defineJobRouter, getBoss, initBoss, isBossRunning, isJobDef, isJobRouter, job, registerJobs, shouldClearOnStart, stopBoss };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map