@lavoro/core 0.3.0

package/build/index.d.ts

@@ -0,0 +1,595 @@
+import { Logger as Logger$1, LogObject, Levels } from '@julr/utils/logger';
+import { LockFactory } from '@verrou/core';
+import { SerializedLock, Duration } from '@verrou/core/types';
+import { Cron } from 'croner';
+
+declare class Logger {
+    private internalLogger;
+    constructor(internalLogger: Logger$1);
+    child(obj: LogObject): Logger;
+    trace(msg: any, obj?: any): void;
+    debug(msg: any, obj?: any): void;
+    warn(msg: any, obj?: any): void;
+    error(msg: any, obj?: any): void;
+    fatal(msg: any, obj?: any): void;
+    info(msg: any, obj?: any): void;
+}
+declare function createDefaultLogger(name: string, level?: Levels): Logger;
+
+/**
+ * Interface to be augmented by users to define their queue names.
+ * This enables type-safe queue names throughout the application.
+ */
+interface QueueList {
+}
+/**
+ * Interface to be augmented by users to map connections to their queue names.
+ * This enables connection-specific type-safe queue names.
+ */
+interface ConnectionQueues {
+}
+/**
+ * Extract queue names from QueueList.
+ * Defaults to string if no queues are defined.
+ */
+type QueueName = keyof QueueList extends never ? string : keyof QueueList;
+/**
+ * Extract queue names for a specific connection from ConnectionQueues.
+ */
+type QueueNameForConnection<C extends QueueConnectionName> = C extends keyof ConnectionQueues ? ConnectionQueues[C] : QueueName;
+type QueueDriverStopOptions = {
+    /**
+     * Whether to wait for the jobs to finish processing before stopping.
+     *
+     * Default: true
+     */
+    graceful?: boolean;
+    /**
+     * The timeout in milliseconds to wait for the jobs to finish processing.
+     *
+     * Default: 30000 (30 seconds)
+     */
+    timeout?: number;
+};
+type QueueDriverConfig = {};
+declare abstract class QueueDriver<Config extends QueueDriverConfig = QueueDriverConfig> {
+    protected config: QueueConfig;
+    protected options: Record<string, WorkerOptions>;
+    protected driverConfig: Config;
+    protected logger: Logger;
+    protected registeredQueues: Set<string>;
+    protected registeredJobs: Map<string, new () => Job>;
+    connection: QueueConnectionName | undefined;
+    constructor(config: QueueConfig, options: Record<string, WorkerOptions>, driverConfig?: Config);
+    setLogger(logger: Logger): void;
+    protected getMergedWorkerOptions(queue: QueueName, options?: WorkerOptions): WorkerOptions;
+    listen(queue: QueueName, options?: WorkerOptions): Promise<void>;
+    register(job: new () => Job): Promise<void>;
+    unregister(job: new () => Job): Promise<void>;
+    start(): Promise<void>;
+    stop(_options?: QueueDriverStopOptions): Promise<void>;
+    protected checkIfQueueIsRegistered(queue: string): void;
+    protected checkIfJobIsRegistered(job: string): void;
+    getDefaultQueue(): QueueName;
+    /**
+     * Parent method to be extended by the driver.
+     * It implements checks for the job and queue being registered.
+     */
+    enqueue<T extends Job, P extends Payload<T>>(job: T, payload: P): Promise<void>;
+    /**
+     * Create a lock factory instance for this driver.
+     *
+     * Each driver implementation should return a
+     * [Verrou LockFactory instance](https://verrou.dev/docs/quick-setup#lockfactory-api)
+     * that matches the driver's backing store.
+     *
+     * @returns A LockFactory instance
+     */
+    abstract createLockProvider(): LockFactory;
+    /**
+     * Clean up resources associated with a lock factory created by this driver.
+     * This is called when the queue is stopped to ensure proper resource cleanup.
+     *
+     * @param lockFactory - The lock factory instance to clean up
+     */
+    destroyLockProvider(_lockFactory: LockFactory): Promise<void>;
+}
+
+declare class PendingDispatch<T extends Job, P extends Payload<T>, C extends QueueConnectionName = DefaultConnection extends {
+    name: infer N;
+} ? N extends QueueConnectionName ? N : QueueConnectionName : QueueConnectionName> {
+    protected job: T;
+    protected payload: P;
+    constructor(job: T, payload: P);
+    onConnection<NewC extends QueueConnectionName>(connection: NewC): PendingDispatch<T, P, NewC>;
+    onQueue(queue: QueueNameForConnection<C>): this;
+    protected execute(): Promise<void>;
+    /**
+     * By defining the "then" method, PendingDispatch becomes "thenable",
+     * allowing it to trigger automatically when await is called.
+     */
+    then<TResult1 = void, TResult2 = never>(onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}
+
+declare class Queue {
+    private config;
+    private drivers;
+    private started;
+    private logger;
+    private scheduledJobs;
+    private lockFactories;
+    constructor(config: QueueConfig & {
+        logger?: Logger;
+    });
+    private createDriver;
+    start(): Promise<void>;
+    stop(options?: QueueDriverStopOptions): Promise<void>;
+    protected register(job: new () => Job): Promise<void>;
+    protected unregister(job: new () => Job): Promise<void>;
+    enqueue<T extends Job, P extends Payload<T>>(job: T, payload: P): Promise<void>;
+    /**
+     * Get the default connection name.
+     *
+     * Returns the name of the first available connection.
+     * Throws an error if no connections are available.
+     */
+    getDefaultConnection(): QueueConnectionName;
+    getDefaultQueue(): QueueName;
+    /**
+     * Get the lock factory instance for a specific connection.
+     * Returns the explicitly configured lock provider or the auto-created lock factory.
+     * Throws an error if no lock factory is available.
+     *
+     * @param connection - The connection name
+     * @returns The lock factory instance
+     */
+    getLockProvider(connection: QueueConnectionName): LockFactory;
+    /**
+     * Register a scheduled job ID with this Queue instance.
+     * This allows the Queue to clean up scheduled jobs when it stops.
+     */
+    registerScheduledJob(id: string): void;
+}
+
+type Payload<T extends Job> = T extends Job<infer P> ? P : unknown;
+type PayloadWithLock<T extends Job, P extends Payload<T>> = P & {
+    _lock?: SerializedLock;
+};
+type Options = {
+    connection?: QueueConnectionName;
+    queue?: string;
+    retries: number;
+    delay: number;
+};
+declare abstract class Job<P = unknown> {
+    private _id;
+    options: Options;
+    static compileName(queue: string, name: string): string;
+    static parseName(name: string): {
+        queue: string;
+        name: string;
+    };
+    get connection(): QueueConnectionName | undefined;
+    set connection(connection: QueueConnectionName | undefined);
+    get queue(): string | undefined;
+    set queue(queue: string | undefined);
+    get name(): string;
+    get id(): string;
+    set id(id: string);
+    get fullyQualifiedName(): string;
+    private static defaultQueueServiceResolver;
+    static setDefaultQueueServiceResolver(queueServiceResolver: () => Promise<Queue>): void;
+    setQueueServiceResolver(queueServiceResolver: () => Promise<Queue>): void;
+    private queueServiceResolver?;
+    get getQueueServiceResolver(): () => Promise<Queue>;
+    /**
+     * Handle the job with the typed payload.
+     */
+    abstract handle(payload: P): Promise<void>;
+    /**
+     * Dispatch a job of type with a typed payload.
+     */
+    static dispatch<T extends Job, P extends Payload<T>>(this: new () => T, payload: P): PendingDispatch<T, P>;
+}
+
+type WorkerOptions = {
+    concurrency?: number;
+};
+/**
+ * Constructor type for an abstract QueueDriver
+ * that accepts optional driver-specific config.
+ */
+type QueueDriverConstructor<Driver extends QueueDriver = QueueDriver> = new (config: QueueConfig, queues: Record<string, WorkerOptions>, driverConfig?: any) => Driver;
+/**
+ * Driver descriptor that combines both the driver and its config.
+ * This is used by builder functions like postgres() and memory().
+ */
+type ConfiguredDriver<Driver extends QueueDriver = QueueDriver, Config extends QueueDriverConfig = QueueDriverConfig> = {
+    constructor: QueueDriverConstructor<Driver>;
+    config?: Config;
+};
+/**
+ * Configuration for a specific queue connection.
+ */
+type QueueConnectionConfig<Driver extends QueueDriver = QueueDriver, Queues extends Record<string, WorkerOptions> = Record<string, WorkerOptions>> = {
+    driver: ConfiguredDriver<Driver>;
+    queues: Queues;
+    lockProvider?: LockFactory;
+};
+/**
+ * Interface to be augmented by users to define their connection names.
+ * This enables type-safe connection names throughout the application.
+ *
+ * Each key should be a connection name mapped to the connection's configuration type.
+ *
+ * Usage in config files:
+ * ```ts
+ * declare module 'lavoro' {
+ *   export interface QueueConnections
+ *     extends InferConnections<typeof queueConfig> {}
+ * }
+ * ```
+ */
+interface QueueConnections {
+}
+/**
+ * Interface to be augmented by users to define their default connection.
+ * This is used to provide correct type hints when no explicit connection is specified.
+ */
+interface DefaultConnection {
+}
+/**
+ * List of registered queue connections
+ * and their related driver configuration.
+ */
+type QueueConnectionsList = Record<string, QueueConnectionConfig<QueueDriver>>;
+/**
+ * Possible connection names using keys from augmented QueueConnections.
+ *
+ * If QueueConnections is not augmented, defaults to string.
+ */
+type QueueConnectionName = keyof QueueConnections extends never ? string : keyof QueueConnections;
+/**
+ * Queue service configuration
+ */
+type QueueConfig = {
+    jobs: readonly (new () => Job)[];
+    worker?: boolean;
+    connection: QueueConnectionName;
+    connections: QueueConnectionsList;
+};
+/**
+ * Infer connection names from the config
+ */
+type InferConnections<T> = T extends {
+    connections: infer Connections;
+} ? Connections : never;
+/**
+ * Infer the default connection name from the config
+ */
+type InferDefaultConnection<T> = T extends {
+    connection: infer Connection;
+} ? Connection : never;
+/**
+ * Infer queue names from all connections
+ */
+type InferQueueNames<T> = T extends {
+    connections: infer Connections;
+} ? Connections extends Record<string, {
+    queues: Record<string, any>;
+}> ? {
+    [K in {
+        [CK in keyof Connections]: keyof Connections[CK]['queues'];
+    }[keyof Connections]]: never;
+} : never : never;
+/**
+ * Infer queue names for a specific connection
+ */
+type InferQueueNamesForConnection<T, ConnectionName extends string> = T extends {
+    connections: infer Connections;
+} ? Connections extends Record<string, {
+    queues: Record<string, any>;
+}> ? ConnectionName extends keyof Connections ? keyof Connections[ConnectionName]['queues'] : never : never : never;
+/**
+ * Infer the connection-to-queues mapping from the config
+ * Returns a mapped type where each connection name maps to its queue names
+ */
+type InferConnectionQueues<T> = T extends {
+    connections: infer Connections;
+} ? Connections extends Record<string, {
+    queues: Record<string, any>;
+}> ? {
+    [K in keyof Connections]: keyof Connections[K]['queues'];
+} : never : never;
+
+type MaybePromise<T> = T | Promise<T>;
+
+type QueueConfigWithConnections<Connections, Connection> = QueueConfig & {
+    connection: Connection;
+    connections: Connections;
+};
+/**
+ * Define config for queue service.
+ *
+ * @example
+ * ```ts
+ * // config/queue.ts
+ * import { memory } from '@lavoro/memory'
+ * import { postgres } from '@lavoro/postgres'
+ *
+ * const config = {
+ *   jobs: [...],
+ *   connection: 'main',
+ *   connections: {
+ *     main: {
+ *       driver: memory(),
+ *       queues: {
+ *         default: { concurrency: 1 },
+ *         emails: { concurrency: 3 },
+ *       },
+ *     },
+ *     background: {
+ *       driver: postgres({ ... }),
+ *       queues: {
+ *         'heavy-tasks': { concurrency: 2 },
+ *         reports: { concurrency: 1 },
+ *       },
+ *     },
+ *   },
+ * }
+ *
+ * const queueConfig = defineConfig(config)
+ *
+ * // Type augmentation to enable type-safe queue names
+ * declare module '@lavoro/core' {
+ *   interface QueueList extends InferQueueNames<typeof config> {}
+ *   interface DefaultConnection {
+ *     name: InferDefaultConnection<typeof config>
+ *   }
+ *   interface QueueConnections extends InferConnections<typeof config> {}
+ *   interface ConnectionQueues extends InferConnectionQueues<typeof config> {}
+ * }
+ * ```
+ *
+ * After defining your queue names, you'll get autocomplete and type checking:
+ * ```ts
+ * await queue.listen('emails')        // ✓ Valid
+ * await queue.listen('heavy-tasks')   // ✓ Valid
+ * await queue.listen('invalid')       // ✗ Type error
+ *
+ * await job.dispatch(payload).onQueue('emails')  // ✓ Valid
+ * await job.dispatch(payload).onQueue('typo')    // ✗ Type error
+ * ```
+ */
+declare function defineConfig<const Connections extends QueueConnectionsList, const Connection extends keyof Connections = keyof Connections>(config: QueueConfigWithConnections<Connections, Connection>): QueueConfigWithConnections<Connections, Connection>;
+
+type ScheduleInterval = 'second' | 'two seconds' | 'three seconds' | 'four seconds' | 'five seconds' | 'ten seconds' | 'fifteen seconds' | 'twenty seconds' | 'thirty seconds' | 'minute' | 'two minutes' | 'three minutes' | 'four minutes' | 'five minutes' | 'ten minutes' | 'fifteen minutes' | 'twenty minutes' | 'thirty minutes' | 'hour' | 'two hours' | 'three hours' | 'four hours' | 'five hours' | 'six hours' | 'seven hours' | 'eight hours' | 'nine hours' | 'ten hours' | 'eleven hours' | 'twelve hours' | 'day' | 'week' | 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'month' | 'last day of month';
+type ScheduleIntervalDayOfWeek = 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday';
+type Hour = `${0 | 1 | 2}${0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9}`;
+type Minute = `${0 | 1 | 2 | 3 | 4 | 5}${0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9}`;
+type ScheduleIntervalTime = `${Hour}:${Minute}`;
+declare function parseTime(time: ScheduleIntervalTime): [number, number];
+interface IntervalCronOptions {
+    /** Minute to run. Default: 0 */
+    minute?: number;
+    /** Hour to run. Default: 0 */
+    hour?: number;
+    /** Day of month to run. Default: 1 */
+    dayOfMonth?: number;
+    /** Day of week to run. Default: 0 */
+    dayOfWeek?: ScheduleIntervalDayOfWeek;
+}
+/**
+ * Converts a ScheduleInterval to a cron pattern string.
+ * For longer intervals (hour, day, week, etc.), you can customize when they run.
+ *
+ * @param interval - The schedule interval
+ * @param options - Options to customize the cron pattern
+ * @returns A cron pattern string
+ *
+ * @example
+ * intervalToCron('minute')                           // '* * * * *' - every minute
+ * intervalToCron('hour', { minute: 30 })             // '30 * * * *' - every hour at :30
+ * intervalToCron('day', { hour: 14, minute: 30 })    // '30 14 * * *' - daily at 2:30 PM
+ * intervalToCron('week', { dayOfWeek: 1, hour: 9 })  // '0 9 * * 1' - Mondays at 9 AM
+ */
+declare function intervalToCron(interval: ScheduleInterval, options?: IntervalCronOptions): string;
+
+declare const getDistributedLockKey: (name: string) => string;
+declare class PendingSchedule {
+    protected name: string;
+    protected cb: (serializedLock?: SerializedLock) => MaybePromise<void>;
+    protected lockProviderResolver: () => LockFactory;
+    protected cronPattern?: string;
+    protected interval: ScheduleInterval;
+    protected intervalOptions?: IntervalCronOptions;
+    protected distributedLockOptions: {
+        /**
+         * The lock key is based on the task name to ensure only one instance runs
+         *
+         * @param name - The task name
+         * @returns The lock key
+         */
+        key: (name: string) => string;
+        /**
+         * The lock TTL is the duration for which the lock is held
+         */
+        ttl: Duration;
+        /**
+         * Whether to allow overlapping executions of the same task
+         */
+        overlap: boolean;
+        /**
+         * Whether to hand off the lock to the queue worker
+         */
+        handOff: boolean;
+    };
+    constructor(name: string, cb: (serializedLock?: SerializedLock) => MaybePromise<void>, lockProviderResolver: () => LockFactory);
+    /**
+     * Schedule using a cron pattern.
+     * You can use https://crontab.guru to generate a cron pattern.
+     *
+     * @param pattern - Cron pattern string
+     *
+     * @example
+     * Schedule.call('my-task', () => {}).cron('0 0 * * *')       // Daily at midnight
+     * Schedule.call('my-task', () => {}).cron('*\/5 * * * *')    // Every 5 minutes
+     * Schedule.call('my-task', () => {}).cron('0 *\/2 * * *')    // Every 2 hours
+     */
+    cron(pattern: string): this;
+    /**
+     * Schedule to run at a specific interval.
+     * For longer intervals (hour, day, week, etc.), you can customize when they run.
+     *
+     * @param interval - The schedule interval
+     * @param options - Options to customize the cron pattern
+     *
+     * @example
+     * Schedule.call('my-task', () => {}).every('minute')
+     * Schedule.call('my-task', () => {}).every('hour', { minute: 30 })
+     * Schedule.call('my-task', () => {}).every('day', { hour: 14, minute: 30 })
+     * Schedule.call('my-task', () => {}).every('week', { dayOfWeek: 1, hour: 9 })
+     */
+    every(interval: ScheduleInterval, options?: IntervalCronOptions): this;
+    on(dayOfWeek: ScheduleIntervalDayOfWeek): this;
+    at(time: ScheduleIntervalTime): this;
+    /**
+     * Set the duration during which other instances
+     * of the same task will be prevented from running.
+     *
+     * This should be roughly the duration of the task execution or longer
+     * since the lock will be released automatically after the task execution.
+     *
+     * @param ttl - The lock duration
+     *
+     * @example
+     * Schedule.call('my-task', () => {}).lockFor('10s')
+     */
+    lockFor(ttl: Duration): this;
+    /**
+     * Allow overlapping executions of the same task.
+     *
+     * @example
+     * Schedule.call('my-task', () => {}).overlapping()
+     */
+    overlapping(): this;
+    protected execute(): Promise<void>;
+    /**
+     * By defining the "then" method, PendingDispatch becomes "thenable",
+     * allowing it to trigger automatically when await is called.
+     */
+    then<TResult1 = void, TResult2 = never>(onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}
+
+declare class PendingJobSchedule<T extends Job, P extends Payload<T>, C extends QueueConnectionName = DefaultConnection extends {
+    name: infer N;
+} ? N extends QueueConnectionName ? N : QueueConnectionName : QueueConnectionName> extends PendingSchedule {
+    protected job: T;
+    protected payload: PayloadWithLock<T, P>;
+    protected lockProviderResolver: () => LockFactory;
+    /**
+     * Use composition pattern and store pending
+     * job dispatch inside a pending schedule.
+     */
+    protected dispatch: PendingDispatch<T, PayloadWithLock<T, P>, C>;
+    private _connection?;
+    private _queue?;
+    private get jobName();
+    constructor(job: T, payload: PayloadWithLock<T, P>, lockProviderResolver: () => LockFactory);
+    onConnection<NewC extends QueueConnectionName>(connection: NewC): PendingJobSchedule<T, P, NewC>;
+    onQueue(queue: QueueNameForConnection<C>): this;
+    protected execute(): Promise<void>;
+}
+
+/**
+ * Default lock provider instance for distributed locking.
+ * Uses memory store by default.
+ */
+declare const defaultScheduleLockProvider: LockFactory;
+declare class Schedule {
+    /**
+     * Default lock provider resolver for distributed locking.
+     * Returns the default memory-based instance if not overridden.
+     */
+    private static defaultLockProviderResolver;
+    /**
+     * Set a custom lock provider resolver for distributed locking.
+     *
+     * This allows dynamic resolution of lock provider instances, useful when
+     * integrating with Queue or other services that manage lock instances.
+     *
+     * @param resolver - Function that returns a LockFactory instance
+     *
+     * @example
+     * import { LockFactory } from '@verrou/core'
+     * import { redisStore } from '@verrou/core/drivers/redis'
+     *
+     * const customLockProvider = new LockFactory(
+     *   redisStore({ connection: redisClient })
+     * )
+     *
+     * Schedule.setLockProviderResolver(() => customLockProvider)
+     */
+    static setLockProviderResolver(resolver: () => LockFactory): void;
+    /**
+     * Get the current lock provider instance from the resolver.
+     * @internal
+     */
+    static getLockProvider(): LockFactory;
+    /**
+     * Clear all scheduled tasks (or specific one if name is specified).
+     *
+     * @param name - The name of the task to clear
+     *
+     * @example
+     * Schedule.clear() // Clear all tasks
+     * Schedule.clear('my-task') // Clear specific task
+     */
+    static clear(name?: string): void;
+    /**
+     * Schedule a callback to run at specified intervals.
+     *
+     * @param name - Unique identifier for the task (required for distributed systems)
+     * @param cb - The callback function to execute
+     *
+     * @example
+     * // Using cron pattern
+     * const cleanupUsers = async () => { ... }
+     * Schedule.call('cleanup-users', cleanupUsers).cron('0 0 * * *')
+     *
+     * // Using convenience methods
+     * Schedule.call('hourly-task', () => { ... }).hourly()
+     * Schedule.call('daily-task', () => { ... }).daily()
+     */
+    static call(name: string, cb: () => MaybePromise<void>): PendingSchedule;
+    /**
+     * Schedule a job to run at specified intervals.
+     *
+     * You can specify the connection and queue to use for the job
+     * the same way you would dispatch a job.
+     *
+     * @param job - The job class to schedule
+     * @param payload - The payload to pass to the job
+     *
+     * @example
+     * Schedule.job(TestJob, { arg1: 'hello', arg2: 1 }).every('minute')
+     * Schedule.job(TestJob, { arg1: 'hello', arg2: 1 })
+     *   .onConnection('main')
+     *   .onQueue('default')
+     *   .every('minute')
+     */
+    static job<T extends Job, P extends Payload<T>>(job: new () => T, payload: P): PendingJobSchedule<T, P>;
+}
+
+/**
+ * Cron instance registry for internal use
+ */
+declare class ScheduleRegistry {
+    private static instances;
+    static add(name: string, cron: Cron): void;
+    static all(): Record<string, Cron>;
+    static get(name: string): Cron | undefined;
+    static clear(name?: string): void;
+}
+
+export { type ConfiguredDriver, type ConnectionQueues, type DefaultConnection, type InferConnectionQueues, type InferConnections, type InferDefaultConnection, type InferQueueNames, type InferQueueNamesForConnection, type IntervalCronOptions, Job, Logger, type MaybePromise, type Payload, PendingDispatch, PendingJobSchedule, PendingSchedule, Queue, type QueueConfig, type QueueConnectionConfig, type QueueConnectionName, type QueueConnections, type QueueConnectionsList, QueueDriver, type QueueDriverConfig, type QueueDriverStopOptions, type QueueList, type QueueName, type QueueNameForConnection, Schedule, type ScheduleInterval, type ScheduleIntervalTime, ScheduleRegistry, type WorkerOptions, createDefaultLogger, defaultScheduleLockProvider, defineConfig, getDistributedLockKey, intervalToCron, parseTime };