@zerotal/queue 1.6.3 → 1.7.0

package/api-surface.md

@@ -0,0 +1,421 @@
+# @zerotal/queue — public API surface
+
+<!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
+     Run `bun run api:surface` to regenerate after an intentional API change. -->
+
+## .  `(./src/index.ts)`
+
+class Batch = {
+  new (_r: BatchRecord): Batch
+  createdAt: string
+  failed: () => boolean
+  failedJobIds: number[]
+  failedJobs: number
+  finished: () => boolean
+  finishedAt: string | undefined
+  id: string
+  name: string
+  options: BatchOptions
+  pendingJobs: number
+  progress: () => number
+  totalJobs: number
+}
+
+class Bus = {
+  new (): Bus
+  static batch: (jobs: Job[]) => PendingBatch
+  static chain: (jobs: Job[]) => {    dispatch(): Promise<void>;}
+  static reset: () => void
+  static setManager: (manager: QueueManager) => void
+}
+
+class Job = {
+  new (): Job
+  _chain: SerializedJob[] | undefined
+  batchId: string | undefined
+  className: string
+  debounceKey: () => string
+  handle: () => Promise<void>
+  payload: () => Record<string, unknown>
+  readonly debounce?: number
+  readonly maxAttempts: number
+  readonly queue: string
+  readonly retryDelay: number
+}
+
+class JobRan = {
+  new (className: string, queue: string, status: 'dispatched' | 'completed' | 'failed' | 'retried', durationMs: number, error?: string | undefined): JobRan
+  readonly className: string
+  readonly durationMs: number
+  readonly error?: string | undefined
+  readonly queue: string
+  readonly status: 'dispatched' | 'completed' | 'failed' | 'retried'
+}
+
+class PendingBatch = {
+  new (_jobs: Job[], _dispatcher: BatchDispatcher): PendingBatch
+  batchName: string
+  catch: (job: Job | Job[]) => PendingBatch
+  dispatch: () => Promise<Batch>
+  finally: (job: Job | Job[]) => PendingBatch
+  jobs: Job[]
+  name: (n: string) => PendingBatch
+  options: BatchOptions
+  then: (job: Job | Job[]) => PendingBatch
+}
+
+class QueueBatchingUnsupportedError = {
+  new (): QueueBatchingUnsupportedError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class QueueDebounceUnsupportedError = {
+  new (className: string, driver: string): QueueDebounceUnsupportedError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class QueueError = {
+  new (message: string, code?: string, status?: number, context?: Record<string, unknown>): QueueError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class QueueFake = {
+  new (app: Application, original: Binding): QueueFake
+  static install: () => QueueFake
+  assertDispatched: <T extends Job>(JobClass: new (...args: never[]) => T, callback?: (job: T) => boolean) => void
+  assertDispatchedCount: (count: number) => void
+  assertNotDispatched: <T extends Job>(JobClass: new (...args: never[]) => T) => void
+  assertNothingDispatched: () => void
+  dispatch: (job: Job) => Promise<void>
+  dispatched: () => Job[]
+  drain: () => Promise<void>
+  flush: () => Promise<void>
+  isShuttingDown: boolean
+  processNext: () => Promise<boolean>
+  restore: () => void
+  size: () => Promise<number>
+}
+
+class QueueManager = {
+  new (driver: QueueDriver): QueueManager
+  activeJobCount: number
+  clearFailed: (queue?: string) => Promise<void>
+  dispatch: (job: Job) => Promise<void>
+  dispatchBatch: (pending: PendingBatch) => Promise<Batch>
+  drain: () => Promise<void>
+  failed: (queue?: string) => Promise<FailedRecord[]>
+  flush: () => Promise<void>
+  forgetFailed: (id: number) => Promise<void>
+  isShuttingDown: boolean
+  pending: (queue?: string, limit?: number, offset?: number) => Promise<JobRecord[]>
+  processNext: (queue?: string) => Promise<boolean>
+  queues: () => Promise<{    queue: string;    pending: number;}[]>
+  retryFailed: (id: number) => Promise<boolean>
+  setWorkerPool: (pool: JobExecutor) => void
+  size: (queue?: string) => Promise<number>
+  stats: () => QueueStats
+}
+
+class QueueNotInitializedError = {
+  new (): QueueNotInitializedError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class QueueProvider = {
+  new (app: Application): QueueProvider
+  static dependsOn?: (new (app: Application) => ServiceProvider)[]
+  static environments: AppEnvironment[]
+  static priority?: number
+  static provides: readonly ['queue']
+  devProcesses: () => DevProcessDefinition[]
+  doctorChecks: () => DoctorCheck[]
+  onBooted: () => Promise<void>
+  onBooting: () => Promise<void>
+  onRegister: () => void
+  onRequestProcessed: (_ctx: HttpContext) => Promise<void>
+  onRequestReceived: (_ctx: HttpContext) => Promise<void>
+  onResponseSent: (_ctx: HttpContext) => Promise<void>
+  onStarted: () => Promise<void>
+  onStarting: () => Promise<void>
+  onStopped: () => Promise<void>
+  onStopping: () => Promise<void>
+  replContext: () => Record<string, unknown>
+}
+
+class QueueShuttingDownError = {
+  new (className: string): QueueShuttingDownError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class RedisDriver = {
+  new (prefix?: string, options?: { visibilityTimeout?: number; client?: RedisClientLike; }): RedisDriver
+  clearFailed: (queue?: string) => Promise<void>
+  delete: (record: JobRecord) => Promise<void>
+  deleteFailedRecord: (id: number, queue?: string) => Promise<void>
+  fail: (record: JobRecord, error: string) => Promise<void>
+  flush: () => Promise<void>
+  listFailed: (queue?: string) => Promise<FailedRecord[]>
+  pop: (queue?: string) => Promise<JobRecord | null>
+  push: (record: Omit<JobRecord, 'id' | 'createdAt'>) => Promise<void>
+  pushDebounced: (record: Omit<JobRecord, 'id' | 'createdAt'>, key: string) => Promise<void>
+  retry: (record: JobRecord) => Promise<void>
+  size: (queue?: string) => Promise<number>
+}
+
+class SqliteDriver = {
+  new (sql: SQLInstance, options?: { visibilityTimeout?: number; }): SqliteDriver
+  clearFailed: (queue?: string) => Promise<void>
+  createBatch: (id: string, name: string, totalJobs: number, optionsJson: string) => Promise<void>
+  delete: (record: JobRecord) => Promise<void>
+  deleteFailedRecord: (id: number) => Promise<void>
+  fail: (record: JobRecord, error: string) => Promise<void>
+  flush: () => Promise<void>
+  getBatch: (batchId: string) => Promise<BatchRecord | null>
+  listFailed: (queue?: string) => Promise<FailedRecord[]>
+  listPending: (queue?: string, limit?: number, offset?: number) => Promise<JobRecord[]>
+  pop: (queue?: string) => Promise<JobRecord | null>
+  push: (record: Omit<JobRecord, 'id' | 'createdAt'>) => Promise<void>
+  pushDebounced: (record: Omit<JobRecord, 'id' | 'createdAt'>, key: string) => Promise<void>
+  queues: () => Promise<{    queue: string;    pending: number;}[]>
+  recordBatchJobComplete: (batchId: string) => Promise<BatchStatus>
+  recordBatchJobFailed: (batchId: string, jobId: number) => Promise<BatchStatus>
+  retry: (record: JobRecord) => Promise<void>
+  size: (queue?: string) => Promise<number>
+}
+
+class SyncDriver = {
+  new (): SyncDriver
+  static _pendingJob: Job | undefined
+  clearFailed: (queue?: string) => Promise<void>
+  delete: (_record: JobRecord) => Promise<void>
+  deleteFailedRecord: (id: number) => Promise<void>
+  fail: (record: JobRecord, error: string) => Promise<void>
+  failedJobs: FailedEntry[]
+  flush: () => Promise<void>
+  listFailed: (queue?: string) => Promise<FailedRecord[]>
+  pop: () => Promise<JobRecord | null>
+  push: (record: Omit<JobRecord, 'id' | 'createdAt'>) => Promise<void>
+  retry: (record: JobRecord) => Promise<void>
+  size: () => Promise<number>
+}
+
+class WorkerPool = {
+  new (opts: WorkerPoolOptions): WorkerPool
+  run: (record: JobRecord) => Promise<WorkerResult>
+  start: () => Promise<void>
+  terminate: () => Promise<void>
+}
+
+const JobRegistry = {    _map: Map<string, JobClass>;    register(JobClass: JobClass): void;    resolve(className: string): JobClass | undefined;    all(): ReadonlyMap<string, JobClass>;}
+
+const Queue = QueueManager
+
+function QueueConfig = (options?: Partial<QueueConfigShape>) => QueueConfigShape
+
+function queueStats = () => QueueStats
+
+interface BatchOptions = {
+  catchJobs?: SerializedJob[] | undefined
+  finallyJobs?: SerializedJob[] | undefined
+  thenJobs?: SerializedJob[] | undefined
+}
+
+interface BatchRecord = {
+  createdAt: string
+  failedJobIds: number[]
+  failedJobs: number
+  finishedAt: string | undefined
+  id: string
+  name: string
+  options: BatchOptions
+  pendingJobs: number
+  totalJobs: number
+}
+
+interface JobRecord = {
+  attempts: number
+  availableAt: number
+  batchId?: string | undefined
+  className: string
+  createdAt: string
+  debounceKey?: string | undefined
+  id: number
+  maxAttempts: number
+  payload: string
+  queue: string
+  retryDelay: number
+}
+
+interface QueueConfigShape = {
+  driver: 'sqlite' | 'redis' | 'sync'
+  pollInterval: number
+  queues: string[]
+  workerBootstrap?: string
+  workers: number
+}
+
+interface QueueDriver = {
+  clearFailed: (queue?: string) => Promise<void>
+  createBatch?: (id: string, name: string, totalJobs: number, optionsJson: string) => Promise<void>
+  delete: (record: JobRecord) => Promise<void>
+  deleteFailedRecord: (id: number) => Promise<void>
+  fail: (record: JobRecord, error: string) => Promise<void>
+  flush: () => Promise<void>
+  getBatch?: (batchId: string) => Promise<BatchRecord | null>
+  listFailed: (queue?: string) => Promise<FailedRecord[]>
+  listPending?: (queue?: string, limit?: number, offset?: number) => Promise<JobRecord[]>
+  pop: (queue?: string) => Promise<JobRecord | null>
+  push: (record: Omit<JobRecord, 'id' | 'createdAt'>) => Promise<void>
+  pushDebounced?: (record: Omit<JobRecord, 'id' | 'createdAt'>, key: string) => Promise<void>
+  queues?: () => Promise<{    queue: string;    pending: number;}[]>
+  recordBatchJobComplete?: (batchId: string) => Promise<BatchStatus>
+  recordBatchJobFailed?: (batchId: string, jobId: number) => Promise<BatchStatus>
+  retry: (record: JobRecord) => Promise<void>
+  size: (queue?: string) => Promise<number>
+}
+
+interface QueueStats = {
+  failedLast5m: number
+  failedTotal: number
+  processedLast5m: number
+  processedTotal: number
+}
+
+interface WorkerPoolOptions = {
+  bootstrapPath?: string | undefined
+  maxPending?: number | undefined
+  maxRespawns?: number | undefined
+  size: number
+}
+
+type BatchStatus = 'failed' | 'pending' | 'complete'
+
+type JobStatus = 'dispatched' | 'completed' | 'failed' | 'retried'
+
+type SerializedJob = {    className: string;    payload: Record<string, unknown>;}
+
+type WorkerResult = {    success: true;} | {    success: false;    error: string;}
+
+## ./commands  `(./src/commands/index.ts)`
+
+class QueueFailedCommand = {
+  new (): QueueFailedCommand
+  static args: ArgDef[]
+  static commandName: string
+  static description: string
+  static flags: {    name: string;    short: string;    type: 'string';    description: string;    default: string;}[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}
+
+class QueueFlushCommand = {
+  new (): QueueFlushCommand
+  static args: ArgDef[]
+  static commandName: string
+  static description: string
+  static flags: ({    name: string;    short: string;    type: 'string';    description: string;    default: string;} | {    name: string;    type: 'boolean';    description: string;    default: boolean;    short?: never;})[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}
+
+class QueueRetryCommand = {
+  new (): QueueRetryCommand
+  static args: {    name: string;    required: boolean;    description: string;}[]
+  static commandName: string
+  static description: string
+  static flags: FlagDef[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}
+
+class QueueWorkCommand = {
+  new (): QueueWorkCommand
+  static args: ArgDef[]
+  static commandName: string
+  static description: string
+  static flags: ({    name: string;    short: string;    type: 'string';    description: string;    default: string;} | {    name: string;    type: 'boolean';    description: string;    default: boolean;    short?: never;})[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/queue",
-  "version": "1.6.3",
+  "version": "1.7.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -13,6 +13,7 @@
   },
   "files": [
     "CHANGELOG.md",
+    "api-surface.md",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
@@ -30,8 +31,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.6.3",
-    "@zerotal/orm": "1.6.3"
+    "@zerotal/core": "1.7.0",
+    "@zerotal/orm": "1.7.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"