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

package/dist/event/index.d.ts

@@ -0,0 +1,108 @@
+import { TSchema, Static } from '@sinclair/typebox';
+
+/**
+ * Event System Types
+ */
+
+/**
+ * Pub/Sub capable cache interface for multi-instance events
+ */
+interface PubSubCache {
+    /**
+     * Publish a message to a channel
+     */
+    publish(channel: string, message: unknown): Promise<void>;
+    /**
+     * Subscribe to a channel
+     */
+    subscribe(channel: string, handler: (message: unknown) => void | Promise<void>): Promise<void>;
+}
+/**
+ * Event handler function type
+ */
+type EventHandler<TPayload> = (payload: TPayload) => void | Promise<void>;
+/**
+ * Job queue sender function type (used by job module)
+ */
+type JobQueueSender = (queueName: string, payload: unknown) => Promise<void>;
+/**
+ * Event definition interface
+ */
+interface EventDef<TPayload = void> {
+    /**
+     * Unique event name
+     */
+    readonly name: string;
+    /**
+     * TypeBox payload schema (optional)
+     */
+    readonly schema?: TSchema;
+    /**
+     * Subscribe to this event (in-memory handler)
+     */
+    subscribe: (handler: EventHandler<TPayload>) => () => void;
+    /**
+     * Unsubscribe all handlers
+     */
+    unsubscribeAll: () => void;
+    /**
+     * Emit the event (triggers all subscribers and queued jobs)
+     */
+    emit: TPayload extends void ? () => Promise<void> : (payload: TPayload) => Promise<void>;
+    /**
+     * Enable cache-based pub/sub for multi-instance support
+     * Must await before emitting events to ensure subscription is ready
+     */
+    useCache: (cache: PubSubCache) => Promise<EventDef<TPayload>>;
+    /**
+     * Internal: Register a job queue to receive this event
+     * Called by job registration system
+     */
+    _registerJobQueue: (queueName: string, sender: JobQueueSender) => void;
+    /**
+     * Type inference helper
+     */
+    _payload: TPayload;
+}
+/**
+ * Infer payload type from EventDef
+ */
+type InferEventPayload<TEvent> = TEvent extends EventDef<infer TPayload> ? TPayload : never;
+
+/**
+ * Event System
+ *
+ * Decoupled pub/sub event system with optional cache integration for multi-instance support
+ *
+ * @example
+ * ```typescript
+ * // Define event
+ * const userCreated = defineEvent('user.created', Type.Object({
+ *     userId: Type.String(),
+ * }));
+ *
+ * // Subscribe (in-memory)
+ * userCreated.subscribe((payload) => {
+ *     console.log('User created:', payload.userId);
+ * });
+ *
+ * // Emit
+ * await userCreated.emit({ userId: '123' });
+ *
+ * // With cache for multi-instance
+ * const event = defineEvent('user.created', schema);
+ * await event.useCache(cache);  // Must await before emitting
+ * await event.emit({ userId: '123' });  // Broadcast to all instances
+ * ```
+ */
+
+/**
+ * Define an event without payload
+ */
+declare function defineEvent(name: string): EventDef<void>;
+/**
+ * Define an event with typed payload
+ */
+declare function defineEvent<T extends TSchema>(name: string, schema: T): EventDef<Static<T>>;
+
+export { type EventDef, type EventHandler, type InferEventPayload, type JobQueueSender, type PubSubCache, defineEvent };

package/dist/event/index.js

@@ -0,0 +1,122 @@
+import { logger } from '@spfn/core/logger';
+
+// src/event/event.ts
+var eventLogger = logger.child("@spfn/core:event");
+function logHandlerError(eventName, error) {
+  eventLogger.error(`Event handler error: ${eventName}`, {
+    error: error instanceof Error ? error.message : String(error)
+  });
+}
+function logJobQueueError(queueName, error) {
+  eventLogger.error(`Failed to send event to job queue: ${queueName}`, {
+    error: error instanceof Error ? error.message : String(error)
+  });
+}
+function createHandlerManager(name) {
+  const handlers = /* @__PURE__ */ new Set();
+  return {
+    add: (handler) => {
+      handlers.add(handler);
+      eventLogger.debug(`Subscribed to event: ${name}`, { handlerCount: handlers.size });
+      return () => {
+        handlers.delete(handler);
+        eventLogger.debug(`Unsubscribed from event: ${name}`, { handlerCount: handlers.size });
+      };
+    },
+    clear: () => {
+      handlers.clear();
+      eventLogger.debug(`Unsubscribed all from event: ${name}`);
+    },
+    trigger: async (payload) => {
+      const results = await Promise.allSettled(
+        [...handlers].map((handler) => handler(payload))
+      );
+      for (const result of results) {
+        if (result.status === "rejected") {
+          logHandlerError(name, result.reason);
+        }
+      }
+    }
+  };
+}
+function createJobQueueManager(name) {
+  const jobQueues = /* @__PURE__ */ new Map();
+  return {
+    register: (queueName, sender) => {
+      jobQueues.set(queueName, sender);
+      eventLogger.debug(`Registered job queue for event: ${name}`, { queueName });
+    },
+    send: async (payload) => {
+      if (jobQueues.size === 0) {
+        return;
+      }
+      const entries = [...jobQueues.entries()];
+      const results = await Promise.allSettled(
+        entries.map(([queueName, sender]) => sender(queueName, payload))
+      );
+      for (const [i, result] of results.entries()) {
+        if (result.status === "rejected") {
+          logJobQueueError(entries[i][0], result.reason);
+        }
+      }
+    },
+    get size() {
+      return jobQueues.size;
+    }
+  };
+}
+function createEventImpl(name, schema) {
+  const handlerManager = createHandlerManager(name);
+  const jobQueueManager = createJobQueueManager(name);
+  let cache;
+  let cacheSubscribed = false;
+  const emit = async (payload) => {
+    eventLogger.debug(`Emitting event: ${name}`, {
+      payload,
+      hasCache: !!cache,
+      jobQueueCount: jobQueueManager.size
+    });
+    if (cache) {
+      await cache.publish(name, payload);
+    } else {
+      await handlerManager.trigger(payload);
+    }
+    await jobQueueManager.send(payload);
+    eventLogger.debug(`Event emitted: ${name}`);
+  };
+  const useCache = async (newCache) => {
+    if (cacheSubscribed) {
+      eventLogger.warn(`Cache already configured for event: ${name}`);
+      return self;
+    }
+    cache = newCache;
+    cacheSubscribed = true;
+    await newCache.subscribe(name, async (message) => {
+      eventLogger.debug(`Received event from cache: ${name}`);
+      await handlerManager.trigger(message);
+    });
+    eventLogger.debug(`Cache subscription ready for event: ${name}`);
+    return self;
+  };
+  const self = {
+    name,
+    schema,
+    subscribe: handlerManager.add,
+    unsubscribeAll: handlerManager.clear,
+    emit,
+    useCache,
+    _registerJobQueue: jobQueueManager.register,
+    _payload: void 0
+  };
+  return self;
+}
+function defineEvent(name, schema) {
+  if (schema) {
+    return createEventImpl(name, schema);
+  }
+  return createEventImpl(name);
+}
+
+export { defineEvent };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/event/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/event/event.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Event System\n *\n * Decoupled pub/sub event system with optional cache integration for multi-instance support\n *\n * @example\n * ```typescript\n * // Define event\n * const userCreated = defineEvent('user.created', Type.Object({\n *     userId: Type.String(),\n * }));\n *\n * // Subscribe (in-memory)\n * userCreated.subscribe((payload) => {\n *     console.log('User created:', payload.userId);\n * });\n *\n * // Emit\n * await userCreated.emit({ userId: '123' });\n *\n * // With cache for multi-instance\n * const event = defineEvent('user.created', schema);\n * await event.useCache(cache);  // Must await before emitting\n * await event.emit({ userId: '123' });  // Broadcast to all instances\n * ```\n */\n\nimport type { TSchema, Static } from '@sinclair/typebox';\nimport { logger } from '@spfn/core/logger';\nimport type { EventDef, EventHandler, JobQueueSender, PubSubCache } from './types';\n\nconst eventLogger = logger.child('@spfn/core:event');\n\n/**\n * Log handler error with consistent format\n */\nfunction logHandlerError(eventName: string, error: unknown): void\n{\n    eventLogger.error(`Event handler error: ${eventName}`, {\n        error: error instanceof Error ? error.message : String(error),\n    });\n}\n\n/**\n * Log job queue error with consistent format\n */\nfunction logJobQueueError(queueName: string, error: unknown): void\n{\n    eventLogger.error(`Failed to send event to job queue: ${queueName}`, {\n        error: error instanceof Error ? error.message : String(error),\n    });\n}\n\n/**\n * Create handler subscription manager\n */\nfunction createHandlerManager<TPayload>(name: string)\n{\n    const handlers: Set<EventHandler<TPayload>> = new Set();\n\n    return {\n        add: (handler: EventHandler<TPayload>): (() => void) =>\n        {\n            handlers.add(handler);\n            eventLogger.debug(`Subscribed to event: ${name}`, { handlerCount: handlers.size });\n\n            return () =>\n            {\n                handlers.delete(handler);\n                eventLogger.debug(`Unsubscribed from event: ${name}`, { handlerCount: handlers.size });\n            };\n        },\n\n        clear: (): void =>\n        {\n            handlers.clear();\n            eventLogger.debug(`Unsubscribed all from event: ${name}`);\n        },\n\n        trigger: async (payload: TPayload): Promise<void> =>\n        {\n            const results = await Promise.allSettled(\n                [...handlers].map((handler) => handler(payload))\n            );\n\n            for (const result of results)\n            {\n                if (result.status === 'rejected')\n                {\n                    logHandlerError(name, result.reason);\n                }\n            }\n        },\n    };\n}\n\n/**\n * Create job queue manager\n */\nfunction createJobQueueManager(name: string)\n{\n    const jobQueues: Map<string, JobQueueSender> = new Map();\n\n    return {\n        register: (queueName: string, sender: JobQueueSender): void =>\n        {\n            jobQueues.set(queueName, sender);\n            eventLogger.debug(`Registered job queue for event: ${name}`, { queueName });\n        },\n\n        send: async (payload: unknown): Promise<void> =>\n        {\n            if (jobQueues.size === 0)\n            {\n                return;\n            }\n\n            const entries = [...jobQueues.entries()];\n            const results = await Promise.allSettled(\n                entries.map(([queueName, sender]) => sender(queueName, payload))\n            );\n\n            for (const [i, result] of results.entries())\n            {\n                if (result.status === 'rejected')\n                {\n                    logJobQueueError(entries[i][0], result.reason);\n                }\n            }\n        },\n\n        get size(): number\n        {\n            return jobQueues.size;\n        },\n    };\n}\n\n/**\n * Internal: Create event implementation\n */\nfunction createEventImpl<TPayload>(\n    name: string,\n    schema?: TSchema\n): EventDef<TPayload>\n{\n    const handlerManager = createHandlerManager<TPayload>(name);\n    const jobQueueManager = createJobQueueManager(name);\n    let cache: PubSubCache | undefined;\n    let cacheSubscribed = false;\n\n    const emit = async (payload?: TPayload): Promise<void> =>\n    {\n        eventLogger.debug(`Emitting event: ${name}`, {\n            payload,\n            hasCache: !!cache,\n            jobQueueCount: jobQueueManager.size,\n        });\n\n        if (cache)\n        {\n            await cache.publish(name, payload);\n        }\n        else\n        {\n            await handlerManager.trigger(payload as TPayload);\n        }\n\n        await jobQueueManager.send(payload);\n        eventLogger.debug(`Event emitted: ${name}`);\n    };\n\n    const useCache = async (newCache: PubSubCache): Promise<EventDef<TPayload>> =>\n    {\n        if (cacheSubscribed)\n        {\n            eventLogger.warn(`Cache already configured for event: ${name}`);\n            return self;\n        }\n\n        cache = newCache;\n        cacheSubscribed = true;\n\n        await newCache.subscribe(name, async (message: unknown) =>\n        {\n            eventLogger.debug(`Received event from cache: ${name}`);\n            await handlerManager.trigger(message as TPayload);\n        });\n\n        eventLogger.debug(`Cache subscription ready for event: ${name}`);\n        return self;\n    };\n\n    const self: EventDef<TPayload> = {\n        name,\n        schema,\n        subscribe: handlerManager.add,\n        unsubscribeAll: handlerManager.clear,\n        emit: emit as EventDef<TPayload>['emit'],\n        useCache,\n        _registerJobQueue: jobQueueManager.register,\n        _payload: undefined as unknown as TPayload,\n    };\n\n    return self;\n}\n\n/**\n * Define an event without payload\n */\nexport function defineEvent(name: string): EventDef<void>;\n\n/**\n * Define an event with typed payload\n */\nexport function defineEvent<T extends TSchema>(\n    name: string,\n    schema: T\n): EventDef<Static<T>>;\n\n/**\n * Define an event for decoupled pub/sub\n *\n * @example\n * ```typescript\n * // Define event with payload\n * export const userCreated = defineEvent('user.created', Type.Object({\n *     userId: Type.String(),\n * }));\n *\n * // Subscribe to event (in-memory)\n * const unsubscribe = userCreated.subscribe((payload) => {\n *     console.log('User created:', payload.userId);\n * });\n *\n * // Emit event\n * await userCreated.emit({ userId: '123' });\n *\n * // Unsubscribe when done\n * unsubscribe();\n *\n * // Multi-instance with cache\n * await userCreated.useCache(cache);\n * await userCreated.emit({ userId: '123' });  // Broadcast to all instances\n * ```\n */\nexport function defineEvent<T extends TSchema>(\n    name: string,\n    schema?: T\n): EventDef<Static<T>> | EventDef\n{\n    if (schema)\n    {\n        return createEventImpl<Static<T>>(name, schema);\n    }\n\n    return createEventImpl<void>(name);\n}\n"]}

package/dist/job/index.d.ts

@@ -0,0 +1,172 @@
+import { a as JobOptions, b as JobHandler, c as JobDef, d as JobRouterEntry, J as JobRouter } from '../boss-D-fGtVgM.js';
+export { B as BossConfig, I as InferJobInput, e as JobSendOptions, g as getBoss, i as initBoss, f as isBossRunning, h as shouldClearOnStart, s as stopBoss } from '../boss-D-fGtVgM.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> {
+    private _name;
+    private _inputSchema?;
+    private _cronExpression?;
+    private _runOnce?;
+    private _subscribedEvent?;
+    private _subscribedEventDef?;
+    private _options?;
+    private _handler?;
+    constructor(name: string);
+    /**
+     * Define input schema with TypeBox
+     */
+    input<TSchema extends _sinclair_typebox.TSchema>(schema: TSchema): JobBuilder<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>>;
+    /**
+     * 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;
+    /**
+     * Define the job handler and finalize the job definition
+     */
+    handler(fn: JobHandler<TInput>): JobDef<TInput>;
+}
+/**
+ * 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
+ */
+declare function registerJobs(router: JobRouter<any>): Promise<void>;
+
+export { JobBuilder, JobDef, JobHandler, JobOptions, JobRouter, JobRouterEntry, collectJobs, defineJobRouter, isJobDef, isJobRouter, job, registerJobs };