bunqueue 2.8.54 → 2.8.57

package/dist/infrastructure/persistence/sqlite.d.ts

@@ -1,281 +1,6 @@
-/**
- * SQLite Storage Implementation
- * Persistence layer using Bun's native SQLite
- * Uses MessagePack for ~2-3x faster serialization than JSON
- */
-import type { Job, JobId, JobTimelineEntry } from '../../domain/types/job';
-import type { FlowFailureRecord } from '../../domain/types/flow';
-import type { StallConfig } from '../../domain/types/stall';
-import type { CronJob } from '../../domain/types/cron';
-import { type DlqConfig, type DlqEntry } from '../../domain/types/dlq';
-import { type DependencyCompletionRecord } from './dependencyCompletionStore';
-/** Critical-loss callback: invoked when WriteBuffer drops jobs after exhausting retries. */
-export type SqliteCriticalLossCallback = (jobs: Job[], lastError: Error, attempts: number) => void;
-/** Record of a critical job loss event (jobs dropped after max retries). */
-export interface SqliteCriticalLoss {
-    jobs: Job[];
-    error: string;
-    attempts: number;
-    at: number;
-}
-/** SQLite configuration */
-export interface SqliteConfig {
-    path: string;
-    walMode?: boolean;
-    synchronous?: 'OFF' | 'NORMAL' | 'FULL';
-    cacheSize?: number;
-    /** Write buffer size (default: 100) */
-    writeBufferSize?: number;
-    /** Write buffer flush interval in ms (default: 50) */
-    writeBufferFlushMs?: number;
-    /** Callback invoked when WriteBuffer drops jobs after exhausting retries. */
-    onCriticalLoss?: SqliteCriticalLossCallback;
-}
-/**
- * SQLite Storage class with write buffering for high throughput
- */
-export declare class SqliteStorage {
-    private readonly db;
-    private readonly statements;
-    private readonly batchManager;
-    private readonly writeBuffer;
-    private readonly dependencyCompletionStore;
-    private _diskFull;
-    private _lastDiskFullError;
-    private _lastDiskFullAt;
-    private readonly _criticalLosses;
-    private readonly _onCriticalLoss?;
-    /** Cap on retained critical-loss records to prevent unbounded growth */
-    private static readonly MAX_RETAINED_LOSSES;
-    constructor(config: SqliteConfig);
-    /**
-     * Default handler for WriteBuffer critical loss. Logs every dropped job so
-     * ops can recover from logs, retains the last MAX_RETAINED_LOSSES records
-     * for programmatic inspection, and forwards to a user-provided callback.
-     *
-     * Without this handler the dropped jobs would be silently discarded by
-     * sqliteBatch.ts:209-223 (no callback = no recovery path).
-     */
-    private handleCriticalLoss;
-    /** Truncate job data preview to keep logs readable. */
-    private previewJobData;
-    /** Retrieve retained critical-loss records (most recent last). */
-    getCriticalLosses(): readonly SqliteCriticalLoss[];
-    /** Clear retained critical-loss records (e.g. after operator acknowledgement). */
-    clearCriticalLosses(): void;
-    /** Mark disk as full and log */
-    private setDiskFull;
-    /** Execute a write operation with SQLITE_FULL detection */
-    private safeWrite;
-    /** Check if storage is in disk-full state */
-    get diskFull(): boolean;
-    /** Get disk full error details */
-    getDiskFullStatus(): {
-        diskFull: boolean;
-        error: string | null;
-        since: number | null;
-    };
-    /** Flush write buffer to disk. Returns number of jobs flushed. */
-    flushWriteBuffer(): number;
-    private migrate;
-    /**
-     * Insert job using write buffer for better throughput.
-     * @param job The job to insert
-     * @param durable If true, bypasses write buffer and writes immediately to disk
-     */
-    insertJob(job: Job, durable?: boolean): void;
-    /** Insert job immediately (bypass buffer) */
-    insertJobImmediate(job: Job): void;
-    /** Run the insertJob statement for one job (no safeWrite/transaction wrapper). */
-    private runInsertJobStmt;
-    /**
-     * Ensure a job's buffered INSERT has been written to disk before issuing a
-     * state-mutating UPDATE. Without this, markActive/markCompleted's UPDATE
-     * would silently match 0 rows and the state change would be overwritten
-     * when the buffered INSERT eventually fires with the original
-     * 'waiting'/'delayed' state baked at insert time.
-     */
-    private flushIfBuffered;
-    markActive(jobId: JobId, startedAt: number, timeline?: JobTimelineEntry[]): void;
-    /** Persist a manually parked parent so recovery does not requeue it. */
-    markWaitingChildren(jobId: JobId, timeline?: JobTimelineEntry[]): void;
-    markCompleted(jobId: JobId, completedAt: number, timeline?: JobTimelineEntry[]): void;
-    markFailed(job: Job, error: string | null): void;
-    /** Save DLQ entry with full metadata */
-    saveDlqEntry(entry: DlqEntry): void;
-    /**
-     * Commit a terminal child outcome, its optional DLQ row, and its flow outbox
-     * record together. Recovery therefore never observes only half the transition.
-     */
-    commitFailedJob(jobId: JobId, entry: DlqEntry | null, flowFailure: FlowFailureRecord | null): void;
-    /** Delete DLQ entry by job ID */
-    deleteDlqEntry(jobId: JobId): void;
-    /** Clear all DLQ entries for a queue */
-    clearDlqQueue(queue: string): void;
-    /**
-     * Permanently purge terminal DLQ jobs in one transaction.
-     * Pending buffered inserts are removed first so a purged job cannot be
-     * written back after the transaction commits.
-     */
-    purgeDlqEntries(queue: string, dlqJobIds: readonly JobId[], terminalJobIds: readonly JobId[], clearQueue: boolean): void;
-    /** Load all DLQ entries */
-    loadDlq(): Map<string, DlqEntry[]>;
-    updateForRetry(job: Job): void;
-    deleteJob(jobId: JobId): void;
-    /** Update a job's data blob (e.g. after adding __parentId) */
-    updateJobData(jobId: JobId, data: unknown): void;
-    /** Clear a released deduplication key so recovery cannot resurrect it. */
-    clearJobUniqueKey(jobId: JobId): void;
-    /** Persist priority ordering, including its LIFO tie-break, across recovery. */
-    updateJobPriority(jobId: JobId, priority: number, lifo: boolean): void;
-    /** Persist progress and its heartbeat as one active-job mutation. */
-    updateJobProgress(jobId: JobId, progress: number, message: string | null, lastHeartbeat: number): void;
-    /**
-     * Persist a delay change (moveToDelayed / changeDelay) so the new `run_at`
-     * survives a restart. Without this the delay lives only in the in-memory heap:
-     * recovery reloads the stale on-disk `run_at` and the job is immediately
-     * pullable again. State is re-derived from `run_at` (future → 'delayed'),
-     * mirroring the insert convention; `started_at` is cleared because a job moved
-     * back to the queue from `active` is no longer running.
-     */
-    updateRunAt(jobId: JobId, runAt: number): void;
-    /** Update a job's children_ids blob and parent_id */
-    updateJobChildrenIds(jobId: JobId, childrenIds: JobId[]): void;
-    /** Persist both sides of a legacy parent link in one SQLite transaction. */
-    updateFlowLink(child: Pick<Job, 'id' | 'parentId' | 'data'>, parent: Pick<Job, 'id' | 'childrenIds' | 'dependsOn' | 'data'>, parentState: 'waiting-children' | 'waiting' | 'prioritized' | 'delayed'): void;
-    /**
-     * Persist a legacy SDK parent-id backpatch without changing parent state.
-     *
-     * A fast child can finish before the SDK sends UpdateParent. Completed jobs
-     * remain in `jobs`, while failed jobs live only in the serialized DLQ entry.
-     * The failure outbox is re-keyed in the same transaction so a crash between
-     * this write and in-memory propagation still targets the real parent.
-     */
-    backpatchFlowChild(child: Pick<Job, 'id' | 'parentId' | 'data'>, previousParentId: JobId | null): void;
-    /** Persist both sides of a removed parent/child relationship atomically. */
-    removeFlowLink(child: Pick<Job, 'id' | 'parentId' | 'data'>, parent: Pick<Job, 'id' | 'childrenIds' | 'dependsOn' | 'data' | 'runAt'>, parentState: 'waiting-children' | 'waiting' | 'prioritized'): void;
-    /** Record terminal child propagation before applying its parent-side effect. */
-    saveFlowFailure(record: FlowFailureRecord): void;
-    loadFlowFailures(): FlowFailureRecord[];
-    deleteFlowFailure(parentId: JobId, childId?: JobId): void;
-    /** Persist dependency removal/promotion as one parent-side recovery checkpoint. */
-    updateFlowParentResolution(job: Pick<Job, 'id' | 'dependsOn' | 'runAt' | 'priority' | 'timeline'>, stateOverride?: 'waiting-children' | 'waiting' | 'prioritized' | 'delayed'): void;
-    getJob(id: JobId): Job | null;
-    storeResult(jobId: JobId, result: unknown): void;
-    getResult(jobId: JobId): unknown;
-    /** Check if a job result exists (for dependency checking during recovery) */
-    hasResult(jobId: JobId): boolean;
-    /** Check if a job has a DLQ entry (used for state/job fallback after restart) */
-    hasDlqEntry(jobId: JobId): boolean;
-    /** Get latest DLQ entry for a job (used for getJob fallback after restart) */
-    getDlqEntry(jobId: JobId): DlqEntry | null;
-    /** Load all DLQ job IDs (used by recovery to skip stale active rows) */
-    loadDlqJobIds(): Set<JobId>;
-    /** Get the persisted `state` column for a job. Returns null if the row is missing. */
-    getJobStateRaw(jobId: JobId): string | null;
-    /** Load all completed job IDs (for dependency recovery) */
-    loadCompletedJobIds(): Set<JobId>;
-    /** Atomically replace a removed completed job with payload-free dependency evidence. */
-    commitRemovedCompletion(job: Pick<Job, 'id' | 'queue'>, retentionLimit: number, pinned: boolean, completedAt?: number): void;
-    loadDependencyCompletions(): DependencyCompletionRecord[];
-    pinDependencyCompletions(jobIds: Iterable<JobId>): void;
-    unpinDependencyCompletions(jobIds: Iterable<JobId>, retentionLimit: number): DependencyCompletionRecord[];
-    reconcileDependencyCompletionPins(referenced: ReadonlySet<JobId>, retentionLimit: number): DependencyCompletionRecord[];
-    deleteDependencyCompletion(jobId: JobId): boolean;
-    deleteDependencyCompletionsForQueue(queue: string): JobId[];
-    /**
-     * Insert batch of jobs. By default the jobs go through the write buffer.
-     * When `durable` is true they bypass the buffer and are written to disk
-     * immediately (matching single-push durable semantics) — used for addBulk
-     * jobs flagged `durable: true`.
-     */
-    insertJobsBatch(jobs: Job[], durable?: boolean): void;
-    /**
-     * Query jobs by queue with optional state filter and pagination.
-     * This is the raw persisted-state query. Logical waiting/prioritized/delayed
-     * views should use queryJobsByLogicalStates().
-     */
-    queryJobs(queue: string, options: {
-        state?: string;
-        states?: string[];
-        limit: number;
-        offset: number;
-        asc: boolean;
-    }): Job[];
-    /**
-     * Query public/logical job states before applying pagination.
-     *
-     * SQLite persists pending jobs as waiting/delayed, while the public state is
-     * time-dependent: a delayed row becomes waiting or prioritized once run_at
-     * is reached. Keeping these predicates in SQL makes OFFSET count the logical
-     * result rather than the unfiltered persisted rows.
-     */
-    queryJobsByLogicalStates(queue: string, states: string[], options: {
-        limit: number;
-        offset: number;
-        asc: boolean;
-        now: number;
-    }): Job[];
-    /**
-     * Load pending jobs with pagination for efficient recovery.
-     * Orders by priority (desc), run_at (asc), and id (asc) so page boundaries
-     * remain deterministic when scheduling fields compare equal.
-     * @param limit Max jobs to return (default: 10000)
-     * @param offset Skip first N jobs (default: 0)
-     */
-    loadPendingJobs(limit?: number, offset?: number): Job[];
-    /**
-     * Load active jobs with pagination.
-     * @param limit Max jobs to return (default: 10000)
-     * @param offset Skip first N jobs (default: 0)
-     */
-    loadActiveJobs(limit?: number, offset?: number): Job[];
-    /**
-     * Load completed jobs with pagination.
-     * Uses job_results join to get only jobs that were successfully completed.
-     * @param limit Max jobs to return (default: 10000)
-     * @param offset Skip first N jobs (default: 0)
-     */
-    loadCompletedJobs(limit?: number, offset?: number): Job[];
-    /**
-     * Count pending jobs (for pagination)
-     */
-    countPendingJobs(): number;
-    /**
-     * Count active jobs (for pagination)
-     */
-    countActiveJobs(): number;
-    saveCron(cron: CronJob): void;
-    loadCronJobs(): CronJob[];
-    deleteCron(name: string): void;
-    /** Update cron job execution state (executions count and next run time) */
-    updateCron(name: string, executions: number, nextRun: number): void;
-    /**
-     * Persist a queue's control-state (paused / rate-limit / concurrency) so it
-     * survives a server restart. Write-through on every pause/resume/limit change.
-     */
-    saveQueueState(name: string, state: {
-        paused: boolean;
-        rateLimit: number | null;
-        concurrencyLimit: number | null;
-        rateLimitDuration?: number | null;
-        rateLimitExpiresAt?: number | null;
-        stallConfig?: StallConfig | null;
-        dlqConfig?: DlqConfig | null;
-    }): void;
-    /** Load all persisted queue control-state rows (used by recover() on boot). */
-    loadQueueState(): Array<{
-        name: string;
-        paused: boolean;
-        rateLimit: number | null;
-        concurrencyLimit: number | null;
-        rateLimitDuration: number | null;
-        rateLimitExpiresAt: number | null;
-        stallConfig: StallConfig | null;
-        dlqConfig: DlqConfig | null;
-    }>;
-    /** Drop a queue's persisted control-state (e.g. on obliterate). */
-    deleteQueueState(name: string): void;
-    close(): void;
-    getSize(): number;
+import { SqliteLifecycle } from './sqlite/lifecycle';
+export type { SqliteConfig, SqliteCriticalLoss, SqliteCriticalLossCallback, } from './types/sqlite';
+export type { DurableAdmissionMetadata } from './types/admission';
+/** SQLite persistence façade. Implementation is split by responsibility. */
+export declare class SqliteStorage extends SqliteLifecycle {
 }