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

package/dist/boss-DI1r4kTS.d.ts

@@ -0,0 +1,244 @@
+import { TSchema } from '@sinclair/typebox';
+import PgBoss from 'pg-boss';
+
+/**
+ * Job System Types
+ *
+ * Type definitions for the pg-boss based job system
+ */
+
+/**
+ * Job options passed to pg-boss
+ */
+interface JobOptions {
+    /**
+     * Maximum retry attempts
+     * @default 3
+     */
+    retryLimit?: number;
+    /**
+     * Delay between retries in milliseconds
+     * @default 1000
+     */
+    retryDelay?: number;
+    /**
+     * Job expiration in seconds
+     * @default 300 (5 minutes)
+     */
+    expireInSeconds?: number;
+    /**
+     * Job priority (higher = more important)
+     * @default 0
+     */
+    priority?: number;
+    /**
+     * Singleton key - only one job with this key can exist
+     */
+    singletonKey?: string;
+    /**
+     * Keep completed jobs for this many seconds
+     * @default 604800 (7 days)
+     */
+    retentionSeconds?: number;
+}
+/**
+ * Send options for individual job dispatch
+ */
+interface JobSendOptions {
+    /**
+     * Delay execution by this many seconds
+     */
+    startAfter?: number | Date;
+    /**
+     * Singleton key for this specific job instance
+     */
+    singletonKey?: string;
+    /**
+     * Priority override
+     */
+    priority?: number;
+}
+/**
+ * Job handler function type
+ */
+type JobHandler<TInput, TOutput = void> = TInput extends void ? () => Promise<TOutput> : (input: TInput) => Promise<TOutput>;
+/**
+ * Compensate handler function type (for rollback)
+ */
+type CompensateHandler<TInput, TOutput> = (input: TInput, output: TOutput) => Promise<void>;
+/**
+ * Job definition interface
+ */
+interface JobDef<TInput = void, TOutput = void> {
+    /**
+     * Unique job name
+     */
+    readonly name: string;
+    /**
+     * TypeBox input schema (optional)
+     */
+    readonly inputSchema?: TSchema;
+    /**
+     * TypeBox output schema (optional, for workflow integration)
+     */
+    readonly outputSchema?: TSchema;
+    /**
+     * Cron expression for scheduled jobs
+     */
+    readonly cronExpression?: string;
+    /**
+     * Run once on server start
+     */
+    readonly runOnce?: boolean;
+    /**
+     * Event name this job subscribes to
+     */
+    readonly subscribedEvent?: string;
+    /**
+     * Event definition this job subscribes to (internal use)
+     */
+    readonly _subscribedEventDef?: unknown;
+    /**
+     * Job options
+     */
+    readonly options?: JobOptions;
+    /**
+     * Job handler
+     */
+    readonly handler: JobHandler<TInput, TOutput>;
+    /**
+     * Compensate handler for rollback (optional, for workflow integration)
+     */
+    readonly compensate?: CompensateHandler<TInput, TOutput>;
+    /**
+     * Send job to queue (returns immediately, executes in background)
+     */
+    send: TInput extends void ? (options?: JobSendOptions) => Promise<string | null> : (input: TInput, options?: JobSendOptions) => Promise<string | null>;
+    /**
+     * Run job synchronously (for testing/debugging)
+     */
+    run: TInput extends void ? () => Promise<TOutput> : (input: TInput) => Promise<TOutput>;
+    /**
+     * Type inference helpers
+     */
+    _input: TInput;
+    _output: TOutput;
+}
+/**
+ * Job router entry - can be a job or nested router
+ */
+type JobRouterEntry = JobDef<any, any> | JobRouter<any>;
+/**
+ * Job router interface
+ */
+interface JobRouter<TJobs extends Record<string, JobRouterEntry> = Record<string, JobRouterEntry>> {
+    readonly jobs: TJobs;
+    readonly _jobs: TJobs;
+}
+/**
+ * Infer input type from JobDef
+ */
+type InferJobInput<TJob> = TJob extends JobDef<infer TInput, any> ? TInput : never;
+/**
+ * Infer output type from JobDef
+ */
+type InferJobOutput<TJob> = TJob extends JobDef<any, infer TOutput> ? TOutput : never;
+
+/**
+ * pg-boss Wrapper
+ *
+ * Manages pg-boss instance lifecycle
+ */
+
+/**
+ * Options for pg-boss initialization
+ *
+ * @example
+ * ```typescript
+ * await initBoss({
+ *     connectionString: process.env.DATABASE_URL,
+ *     schema: 'spfn_queue',
+ *     clearOnStart: process.env.NODE_ENV === 'development',
+ * });
+ * ```
+ */
+interface BossOptions {
+    /**
+     * PostgreSQL connection string
+     *
+     * @example 'postgresql://user:password@localhost:5432/mydb'
+     */
+    connectionString: string;
+    /**
+     * Schema name for pg-boss tables
+     *
+     * pg-boss creates its own tables in this schema.
+     *
+     * @default 'spfn_queue'
+     */
+    schema?: string;
+    /**
+     * Maintenance interval in seconds
+     *
+     * pg-boss runs maintenance tasks (cleanup, archiving) at this interval.
+     *
+     * @default 120
+     */
+    maintenanceIntervalSeconds?: number;
+    /**
+     * Monitor state changes interval in seconds
+     *
+     * When set, pg-boss emits state change events at this interval.
+     *
+     * @default undefined (disabled)
+     */
+    monitorIntervalSeconds?: number;
+    /**
+     * Clear all pending/scheduled jobs on startup
+     *
+     * Useful for development mode to start with a clean queue.
+     * Should be false in production.
+     *
+     * @default false
+     */
+    clearOnStart?: boolean;
+}
+/**
+ * @deprecated Use BossOptions instead
+ */
+type BossConfig = BossOptions;
+/**
+ * Initialize pg-boss with the given configuration
+ *
+ * Must be called before registerJobs(). Typically handled by defineServerConfig().
+ *
+ * @param options - pg-boss configuration options
+ * @returns The pg-boss instance
+ *
+ * @example
+ * ```typescript
+ * const boss = await initBoss({
+ *     connectionString: process.env.DATABASE_URL!,
+ *     schema: 'spfn_queue',
+ * });
+ * ```
+ */
+declare function initBoss(options: BossOptions): Promise<PgBoss>;
+/**
+ * Get the current pg-boss instance
+ */
+declare function getBoss(): PgBoss | null;
+/**
+ * Stop pg-boss gracefully
+ */
+declare function stopBoss(): Promise<void>;
+/**
+ * Check if pg-boss is initialized and running
+ */
+declare function isBossRunning(): boolean;
+/**
+ * Check if jobs should be cleared on start
+ */
+declare function shouldClearOnStart(): boolean;
+
+export { type BossOptions as B, type CompensateHandler as C, type InferJobInput as I, type JobRouter as J, type JobOptions as a, type JobHandler as b, type JobDef as c, type JobRouterEntry as d, type JobSendOptions as e, type InferJobOutput as f, getBoss as g, isBossRunning as h, initBoss as i, shouldClearOnStart as j, type BossConfig as k, stopBoss as s };

package/dist/cache/index.d.ts

@@ -2,10 +2,6 @@ import { Redis, Cluster } from 'ioredis';
 
 /**
  * Cache factory with automatic environment variable detection
- * Supports Valkey and Redis with multiple deployment patterns
- *
- * Valkey is a Redis fork (7.2.4 base) with 100% protocol compatibility
- * https://valkey.io
  */
 
 interface CacheClients {
@@ -18,35 +14,31 @@ interface CacheClients {
  * Create cache client(s) from environment variables
  *
  * Supported patterns (priority order):
- * 1. Single instance: VALKEY_URL or CACHE_URL or REDIS_URL
- * 2. Master-Replica: VALKEY_WRITE_URL + VALKEY_READ_URL (or CACHE_*, REDIS_*)
- * 3. Sentinel: VALKEY_SENTINEL_HOSTS + VALKEY_MASTER_NAME (or REDIS_*)
- * 4. Cluster: VALKEY_CLUSTER_NODES (or REDIS_*)
+ * 1. Single instance: CACHE_URL
+ * 2. Master-Replica: CACHE_WRITE_URL + CACHE_READ_URL
+ * 3. Sentinel: CACHE_SENTINEL_HOSTS + CACHE_MASTER_NAME
+ * 4. Cluster: CACHE_CLUSTER_NODES
  *
  * @returns Cache client(s) or undefined if no configuration found
  *
  * @example
  * ```bash
  * # Single (most common)
- * VALKEY_URL=valkey://localhost:6379
  * CACHE_URL=redis://localhost:6379
- *
- * # Legacy (still supported)
- * REDIS_URL=redis://localhost:6379
- * REDIS_URL=rediss://secure.redis.com:6380  # TLS
+ * CACHE_URL=rediss://secure.cache.com:6380  # TLS
  *
  * # Master-Replica
- * VALKEY_WRITE_URL=valkey://master:6379
- * VALKEY_READ_URL=valkey://replica:6379
+ * CACHE_WRITE_URL=redis://master:6379
+ * CACHE_READ_URL=redis://replica:6379
  *
  * # Sentinel
- * VALKEY_SENTINEL_HOSTS=sentinel1:26379,sentinel2:26379
- * VALKEY_MASTER_NAME=mymaster
- * VALKEY_PASSWORD=secret
+ * CACHE_SENTINEL_HOSTS=sentinel1:26379,sentinel2:26379
+ * CACHE_MASTER_NAME=mymaster
+ * CACHE_PASSWORD=secret
  *
  * # Cluster
- * VALKEY_CLUSTER_NODES=node1:6379,node2:6379,node3:6379
- * VALKEY_PASSWORD=secret
+ * CACHE_CLUSTER_NODES=node1:6379,node2:6379,node3:6379
+ * CACHE_PASSWORD=secret
  * ```
  */
 declare function createCacheFromEnv(): Promise<CacheClients>;
@@ -195,17 +187,5 @@ declare function getCacheInfo(): {
     isReplica: boolean;
     disabled: boolean;
 };
-/** @deprecated Use getCache() instead */
-declare const getRedis: typeof getCache;
-/** @deprecated Use getCacheRead() instead */
-declare const getRedisRead: typeof getCacheRead;
-/** @deprecated Use setCache() instead */
-declare const setRedis: typeof setCache;
-/** @deprecated Use initCache() instead */
-declare const initRedis: typeof initCache;
-/** @deprecated Use closeCache() instead */
-declare const closeRedis: typeof closeCache;
-/** @deprecated Use getCacheInfo() instead */
-declare const getRedisInfo: typeof getCacheInfo;
 
-export { type CacheClients, type CacheClients as RedisClients, closeCache, closeRedis, createCacheFromEnv, createCacheFromEnv as createRedisFromEnv, createSingleCacheFromEnv, createSingleCacheFromEnv as createSingleRedisFromEnv, getCache, getCacheInfo, getCacheRead, getRedis, getRedisInfo, getRedisRead, initCache, initRedis, isCacheDisabled, setCache, setRedis };
+export { type CacheClients, type CacheClients as RedisClients, closeCache, createCacheFromEnv, createCacheFromEnv as createRedisFromEnv, createSingleCacheFromEnv, createSingleCacheFromEnv as createSingleRedisFromEnv, getCache, getCacheInfo, getCacheRead, initCache, isCacheDisabled, setCache };