redmine-context 1.0.0

package/dist/extract/pdf.js

@@ -0,0 +1,322 @@
+/**
+ * Extrator de texto de PDF via `pdftotext` (poppler) — M4-extra, #145, ADR-002.
+ *
+ * Roda o binário `pdftotext` sobre um PDF já baixado no cache e devolve a CAMADA
+ * DE TEXTO do documento num {@link ExtractionResult}. ESPELHA ponto-a-ponto o
+ * padrão do {@link TesseractExtractor} (ADR-002), todas as decisões exercitadas
+ * por testes:
+ *
+ * - INVOCAÇÃO SEM SHELL: usa `execFile` (nunca `exec`/shell) com lista de
+ *   argumentos explícita (`pdftotext -enc UTF-8 <file> -`, `-` = stdout) — o
+ *   `filePath` NUNCA é interpolado numa string de shell, eliminando injeção por
+ *   nome de arquivo malicioso.
+ * - ENV SANITIZADO: o subprocesso recebe um env MÍNIMO e EXPLÍCITO (só `PATH`) —
+ *   segredos do processo pai (ex.: `REDMINE_API_KEY`) NUNCA vazam para o pdftotext.
+ * - TIMEOUT + KILL: um watchdog envia `SIGTERM` no timeout e, após a graça,
+ *   `SIGKILL` — um pdftotext travado (PDF patológico) não pendura a fila de jobs.
+ * - DEGRADAÇÃO GRACIOSA: binário ausente do PATH/locais convencionais NÃO lança;
+ *   devolve `{ status: 'failed', metadata.reason }` com dica de instalação (o
+ *   `doctor` da #53 orienta o usuário).
+ *
+ * SEMÂNTICA DO PDF SEM CAMADA DE TEXTO (escaneado): quando o `pdftotext` sai com
+ * sucesso mas a saída é VAZIA ou só whitespace (form-feed por página), NÃO
+ * devolvemos `{ status: 'done', text: '' }` — isso MENTIRIA ao consumidor,
+ * afirmando "extração concluída, sem texto" quando na verdade não há camada de
+ * texto extraível (o conteúdo é imagem, exigindo OCR). Devolvemos
+ * `{ status: 'failed', reason: 'pdf-sem-camada-de-texto' }` com um `hint` de que
+ * o OCR por página fica para uma issue futura — falha honesta e diagnosticável.
+ *
+ * A chave de cache do anexo (ADR-004) depende de `version` + `model` + `params`
+ * ({@link buildAttachmentKey}); por isso o extrator expõe {@link PdfExtractor.version}
+ * (derivada do binário real quando detectável, senão a versão da integração) e
+ * {@link PdfExtractor.params} (inclui `enc`/`layout`, estáveis para a chave).
+ */
+import { execFile } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { delimiter, join } from 'node:path';
+/** Identificador estável do extrator (entra em metadados). */
+const EXTRACTOR_ID = 'pdftotext';
+/** Modelo lógico para a chave de cache (ADR-004). PDF→texto não versiona "modelo". */
+const EXTRACTOR_MODEL = 'pdftotext';
+/**
+ * Versão de FALLBACK da integração, usada quando o binário não é detectável (não
+ * instalado) e portanto sua versão não pode ser lida. Mantém `version` estável e
+ * não-vazia para {@link buildAttachmentKey}.
+ */
+const INTEGRATION_VERSION = 'pdftotext-integration-1';
+/** Encoding de saída — sempre UTF-8 (participa da chave de cache via `params`). */
+const OUTPUT_ENCODING = 'UTF-8';
+/** Timeout default de uma extração antes do `SIGTERM` (ms). */
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** Graça entre `SIGTERM` e `SIGKILL` (ms) — dá ao pdftotext chance de sair limpo. */
+const DEFAULT_KILL_GRACE_MS = 2_000;
+/** Teto do stdout capturado (32 MiB) — PDFs textuais densos cabem com folga. */
+const MAX_BUFFER_BYTES = 32 * 1024 * 1024;
+/** MIME REAL (magic bytes `%PDF`, ver `./magic.ts`) que o pdftotext aceita. */
+export const PDF_MIMES = ['application/pdf'];
+/**
+ * Locais convencionais do binário `pdftotext`, por plataforma — consultados após
+ * o `PATH`. No Windows, os builds do poppler (oschwartz10612.Poppler / choco)
+ * instalam em `…\poppler\bin`. Reutilizados pelo `doctor` (#53) via {@link findPdftotext}.
+ */
+const CONVENTIONAL_UNIX = ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin'];
+const CONVENTIONAL_WINDOWS = [
+    'C:\\Program Files\\poppler\\bin',
+    'C:\\Program Files\\poppler\\Library\\bin',
+    'C:\\poppler\\bin',
+];
+/**
+ * Verifica se um caminho aponta para um arquivo executável (bit X), sem lançar.
+ *
+ * @param candidate - Caminho absoluto candidato ao binário.
+ * @returns `true` se o arquivo existe e é executável pelo processo atual.
+ */
+function isExecutable(candidate) {
+    try {
+        accessSync(candidate, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Localiza o binário `pdftotext` no `PATH` e em locais convencionais por
+ * plataforma (`/opt/homebrew/bin`, `/usr/local/bin`, `C:\\Program Files\\poppler\\bin`).
+ * Função pura e reutilizável pelo `doctor` (#53). Não executa o binário.
+ *
+ * @returns A localização encontrada, ou `undefined` se não instalado.
+ * @example
+ * const found = findPdftotext();
+ * if (found === undefined) logger.warn('pdftotext (poppler) não instalado');
+ */
+export function findPdftotext() {
+    const isWindows = process.platform === 'win32';
+    const exe = isWindows ? 'pdftotext.exe' : 'pdftotext';
+    const pathDirs = (process.env.PATH ?? '').split(delimiter).filter((dir) => dir.length > 0);
+    const conventional = isWindows ? CONVENTIONAL_WINDOWS : CONVENTIONAL_UNIX;
+    for (const dir of [...pathDirs, ...conventional]) {
+        const candidate = join(dir, exe);
+        if (isExecutable(candidate)) {
+            return { path: candidate };
+        }
+    }
+    return undefined;
+}
+/**
+ * Monta o env MÍNIMO e EXPLÍCITO do subprocesso (ADR-002). Só repassa `PATH`;
+ * NENHUM outro segredo do pai (ex.: `REDMINE_API_KEY`) é herdado.
+ *
+ * @returns Env sanitizado para o subprocesso pdftotext.
+ */
+function sanitizedEnv() {
+    return { PATH: process.env.PATH ?? '/usr/bin:/bin' };
+}
+/** Erro interno: o watchdog matou o pdftotext por estourar o timeout. */
+class PdftotextTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`pdftotext excedeu o timeout de ${timeoutMs}ms e foi encerrado`);
+        this.timeoutMs = timeoutMs;
+        this.name = 'PdftotextTimeoutError';
+    }
+}
+/**
+ * Executa `pdftotext -enc UTF-8 [-layout] <file> -` SEM shell, com env sanitizado
+ * e watchdog de timeout (`SIGTERM` → graça → `SIGKILL`). O `-` final direciona a
+ * saída para o stdout.
+ *
+ * @param options - Ver {@link RunOptions}.
+ * @returns O stdout (texto do PDF) do pdftotext.
+ * @throws {PdftotextTimeoutError} Se estourar o timeout.
+ * @throws {Error} Se o binário falhar (exit != 0, não encontrado em runtime, etc.).
+ */
+function runPdftotext(options) {
+    const { bin, filePath, layout, timeoutMs, killGraceMs } = options;
+    const args = ['-enc', OUTPUT_ENCODING, ...(layout ? ['-layout'] : []), filePath, '-'];
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timedOut = false;
+        const timers = [];
+        const cleanup = () => {
+            for (const timer of timers)
+                clearTimeout(timer);
+        };
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            fn();
+        };
+        const child = execFile(bin, args, { env: sanitizedEnv(), encoding: 'utf8', maxBuffer: MAX_BUFFER_BYTES, windowsHide: true }, (error, stdout) => {
+            if (timedOut) {
+                settle(() => reject(new PdftotextTimeoutError(timeoutMs)));
+                return;
+            }
+            if (error !== null) {
+                settle(() => reject(error));
+                return;
+            }
+            settle(() => resolve(stdout));
+        });
+        timers.push(setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+            // Reason: após a graça, força SIGKILL e desiste — um processo que ignora
+            // SIGTERM não pode segurar a fila de jobs indefinidamente (ADR-002).
+            timers.push(setTimeout(() => {
+                child.kill('SIGKILL');
+                settle(() => reject(new PdftotextTimeoutError(timeoutMs)));
+            }, killGraceMs));
+        }, timeoutMs));
+    });
+}
+/**
+ * Extrator de texto de PDF baseado no binário `pdftotext` do poppler (ADR-002).
+ * Implementa {@link Extractor} e, além do contrato, expõe {@link params} e
+ * {@link extractorConfig} estáveis para {@link buildAttachmentKey}.
+ */
+export class PdfExtractor {
+    id = EXTRACTOR_ID;
+    version;
+    supportedMimes = PDF_MIMES;
+    /** Modelo lógico para a chave de cache (ADR-004). */
+    model = EXTRACTOR_MODEL;
+    /** Parâmetros escalares estáveis (`enc`, `layout`) — participam da chave de cache. */
+    params;
+    binaryPath;
+    layout;
+    timeoutMs;
+    killGraceMs;
+    /**
+     * @param options - Ver {@link PdfExtractorOptions}.
+     */
+    constructor(options) {
+        this.version = options.version;
+        this.binaryPath = options.binaryPath;
+        this.layout = options.layout ?? false;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+        this.params = { enc: OUTPUT_ENCODING, layout: this.layout };
+    }
+    /**
+     * Configuração do extrator pronta para {@link buildAttachmentKey} (ADR-004).
+     * @returns `{ version, model, params }` estáveis desta instância.
+     */
+    get extractorConfig() {
+        return { version: this.version, model: this.model, params: this.params };
+    }
+    /**
+     * Extrai a camada de texto de `filePath`. Nunca lança: falhas (binário ausente,
+     * timeout, erro de execução, PDF sem texto) viram `{ status: 'failed',
+     * metadata.reason }` — degradação graciosa (ADR-002).
+     *
+     * IMPORTANTE (semântica): um PDF ESCANEADO (sem camada de texto) produz saída
+     * vazia/whitespace no `pdftotext`; nesse caso devolvemos `failed` com
+     * `reason: 'pdf-sem-camada-de-texto'` (e um `hint` de OCR), e NÃO
+     * `{ status: 'done', text: '' }` — que afirmaria falsamente sucesso sem texto.
+     *
+     * @param filePath - Caminho absoluto do PDF baixado.
+     * @param options - MIME real + logger — ver {@link ExtractOptions}.
+     * @returns `done` com `text` no sucesso; `failed` com motivo claro na falha.
+     */
+    async extract(filePath, options) {
+        const bin = this.binaryPath;
+        if (bin === undefined) {
+            options.logger?.warn('pdftotext: binário não encontrado no PATH nem em locais convencionais; ' +
+                'instale o poppler (ex.: `brew install poppler`) — veja o doctor');
+            return this.failed(options.mime, 'pdftotext-nao-instalado', {
+                hint: 'instale o poppler (pdftotext); o doctor (#53) valida a instalação',
+            });
+        }
+        let stdout;
+        try {
+            stdout = await runPdftotext({
+                bin,
+                filePath,
+                layout: this.layout,
+                timeoutMs: this.timeoutMs,
+                killGraceMs: this.killGraceMs,
+            });
+        }
+        catch (error) {
+            const isTimeout = error instanceof PdftotextTimeoutError;
+            return this.failed(options.mime, isTimeout ? 'timeout' : 'erro-execucao', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        const text = stdout.trim();
+        if (text.length === 0) {
+            // PDF escaneado / sem camada de texto: `done` com text vazio MENTIRIA.
+            return this.failed(options.mime, 'pdf-sem-camada-de-texto', {
+                hint: 'PDF sem camada de texto (provavelmente escaneado) — OCR por página fica para issue futura',
+            });
+        }
+        return {
+            status: 'done',
+            text,
+            mime: options.mime,
+            metadata: { extractorId: this.id, version: this.version, layout: this.layout },
+        };
+    }
+    /**
+     * Monta um `ExtractionResult` `failed` com metadados de diagnóstico, sem
+     * injetar chaves `undefined` (respeita `exactOptionalPropertyTypes`).
+     *
+     * @param mime - MIME real detectado (do dispatcher).
+     * @param reason - Motivo canônico da falha.
+     * @param extra - Metadados adicionais (hint/erro).
+     * @returns Resultado `failed` tipado.
+     */
+    failed(mime, reason, extra) {
+        return {
+            status: 'failed',
+            mime,
+            metadata: { extractorId: this.id, version: this.version, reason, ...extra },
+        };
+    }
+}
+/**
+ * Lê a versão do binário via `pdftotext -v`. O poppler imprime
+ * `pdftotext version X.Y.Z` no STDERR (não stdout) e sai com código 0. Não lança:
+ * retorna `undefined` se o binário falhar ou a saída for inesperada.
+ *
+ * @param bin - Caminho absoluto do binário.
+ * @returns A versão semântica detectada (ex.: `24.02.0`), ou `undefined`.
+ */
+export function detectPdftotextVersion(bin) {
+    return new Promise((resolve) => {
+        execFile(bin, ['-v'], { env: sanitizedEnv(), encoding: 'utf8', windowsHide: true, timeout: DEFAULT_KILL_GRACE_MS }, (error, stdout, stderr) => {
+            // Reason: `pdftotext -v` sai com status 0 e escreve a versão no STDERR;
+            // toleramos `error` não-nulo e ainda tentamos parsear ambos os streams.
+            const combined = `${stderr}${stdout}`;
+            const match = /pdftotext\s+version\s+(\d+\.\d+\.\d+)/i.exec(combined);
+            if (match === null && error !== null) {
+                resolve(undefined);
+                return;
+            }
+            resolve(match?.[1]);
+        });
+    });
+}
+/**
+ * Cria um {@link PdfExtractor} resolvendo binário e versão. Localiza o
+ * `pdftotext` ({@link findPdftotext}); se presente, lê a versão real do binário e
+ * expõe `version = pdftotext-<X.Y.Z>`; se ausente (não instalado) ou versão
+ * ilegível, usa {@link INTEGRATION_VERSION} e o extrator degrada em `extract`.
+ *
+ * @param config - Sobrescreve `layout`/timeouts — ver {@link PdfExtractorOptions}.
+ * @returns O extrator pronto para registro no {@link ExtractorRegistry}.
+ * @example
+ * const extractor = await createPdfExtractor({ layout: true });
+ */
+export async function createPdfExtractor(config = {}) {
+    const found = findPdftotext();
+    let version = INTEGRATION_VERSION;
+    if (found !== undefined) {
+        const detected = await detectPdftotextVersion(found.path);
+        version = detected !== undefined ? `pdftotext-${detected}` : INTEGRATION_VERSION;
+    }
+    return new PdfExtractor({ ...config, binaryPath: found?.path, version });
+}

package/dist/extract/queue.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Núcleo da fila de jobs de extração (#67 / M4-10.1, ADR-005).
+ *
+ * A extração de mídia é longa (minutos) e há vários anexos por issue; esta fila
+ * roda os jobs com **concorrência limitada** (`os.cpus().length − 1`, piso de 1),
+ * expõe as **transições de estado de forma observável** e **isola falhas** — um
+ * job que rejeita vira `failed` sem derrubar os demais.
+ *
+ * ## Observabilidade — contrato do core (ADR-005)
+ *
+ * A fila é consumida como `AsyncIterable<QueueEvent<T>>`, o mesmo padrão
+ * `AsyncIterable<ProgressEvent | Result>` que as superfícies já usam: cada
+ * transição de um job é um item da sequência, e o iterável termina quando a fila
+ * drena. O status REUSA o vocabulário canônico {@link ExtractionStatus}
+ * (`pending → processing → done | failed | cancelled`) — sem status paralelo.
+ *
+ * ## Cancelamento (#69)
+ *
+ * A fila aceita um `AbortSignal` opcional ({@link RunQueueOptions.signal}) e o
+ * propaga a cada job via {@link JobContext.signal}. Ao abortar: os jobs em
+ * execução recebem o signal (o extrator o repassa ao `runWithWatchdog`, que MATA
+ * o subprocesso) e são observados como `cancelled`; os jobs `pending` que ainda
+ * não iniciaram são marcados `cancelled` sem iniciar. Cada transição emite UM
+ * evento — as superfícies consomem só o `AsyncIterable`, sem API de cancelamento
+ * acoplada.
+ *
+ * ## Fronteira e escopo
+ *
+ * Módulo de core (pipeline de extração): não importa de `src/surfaces/**` e não
+ * usa `console.*` — falhas são reportadas via {@link Logger} injetado. O
+ * {@link JobContext} passado a cada job é o ponto de extensão do timeout/kill de
+ * subprocesso (#68, `timeoutMs`) e do cancelamento (#69, `signal`), sem quebrar a
+ * assinatura de {@link QueueJob}.
+ */
+import type { Logger } from '../client/index.js';
+import type { ExtractionStatus } from '../contract.js';
+/**
+ * Estado observável de um job da fila — subconjunto do vocabulário canônico
+ * {@link ExtractionStatus}. Derivado por `Extract<>` para que qualquer mudança
+ * no contrato do core se propague aqui (sem status paralelo).
+ */
+export type QueueJobStatus = Extract<ExtractionStatus, 'pending' | 'processing' | 'done' | 'failed' | 'cancelled'>;
+/**
+ * Contexto passado ao {@link QueueJob.run} de cada job.
+ *
+ * Carrega o `jobId` (útil para logs/telemetria do próprio job) e, opcionalmente,
+ * o `timeoutMs` — o ORÇAMENTO DE TEMPO que um job de extração deve repassar ao
+ * watchdog do subprocesso (#68), que o encerra com `SIGTERM`→`SIGKILL` no estouro.
+ * A fila NÃO cancela o job por conta própria (o kill correto vive no subprocesso);
+ * ela só PROPAGA o orçamento. É o seam reservado ao `AbortSignal` do cancelamento
+ * (#69), que entra aqui como mais um campo OPCIONAL — aditivo, sem quebrar jobs
+ * existentes.
+ */
+export interface JobContext {
+    /** Id do job em execução (o mesmo de {@link QueueJob.id}). */
+    readonly jobId: string;
+    /**
+     * Orçamento de tempo (ms) que o job deve aplicar ao seu subprocesso, quando a
+     * fila é criada com {@link RunQueueOptions.jobTimeoutMs}. Ausente = o job usa seu
+     * próprio default. Respeita `exactOptionalPropertyTypes` (nunca `undefined`).
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Sinal de CANCELAMENTO (#69, ADR-005) propagado a cada job em execução quando
+     * a fila é criada com {@link RunQueueOptions.signal}. O job de extração o repassa
+     * ao `runWithWatchdog`, que MATA o subprocesso (`SIGTERM`→`SIGKILL`) ao abortar;
+     * a fila então observa o job como `cancelled`. Ausente = a fila não é cancelável.
+     * Presente só quando a fila recebe um signal (respeita `exactOptionalPropertyTypes`).
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Uma unidade de trabalho da fila. `run` é uma função async qualquer — nos
+ * testes, um job FAKE controlável via Promise; em produção, a extração de um
+ * anexo.
+ *
+ * @typeParam T - Tipo do resultado produzido pelo job em caso de sucesso.
+ */
+export interface QueueJob<T> {
+    /** Identificador único da execução (escolhido por quem enfileira). */
+    readonly id: string;
+    /**
+     * Executa o trabalho.
+     *
+     * @param context - Contexto da execução — ver {@link JobContext}.
+     * @returns O resultado do job; a rejeição vira uma transição `failed`.
+     */
+    run(context: JobContext): Promise<T>;
+}
+/**
+ * Uma transição de estado observável de um job (item do `AsyncIterable`).
+ *
+ * Respeita `exactOptionalPropertyTypes`: `result` só aparece em `done`,
+ * `reason`/`error` só aparecem em `failed` — nunca com valor `undefined`.
+ *
+ * @typeParam T - Tipo do resultado do job (presente em `status === 'done'`).
+ */
+export interface QueueEvent<T> {
+    /** Id do job ({@link QueueJob.id}) a que esta transição se refere. */
+    readonly id: string;
+    /** Novo estado do job. */
+    readonly status: QueueJobStatus;
+    /** Resultado do job — presente apenas quando `status === 'done'`. */
+    readonly result?: T;
+    /** Motivo legível da falha — presente apenas quando `status === 'failed'`. */
+    readonly reason?: string;
+    /** Erro bruto que causou a falha — presente apenas quando `status === 'failed'`. */
+    readonly error?: unknown;
+}
+/** Opções de {@link runQueue}. */
+export interface RunQueueOptions {
+    /**
+     * Número máximo de jobs em `processing` ao mesmo tempo. Injetável para testes
+     * determinísticos; valores `< 1` são elevados ao piso de 1. Default:
+     * {@link defaultConcurrency}.
+     */
+    readonly concurrency?: number;
+    /** Logger para avisar sobre jobs que falharam (boundary ADR-005; sem `console.*`). */
+    readonly logger?: Logger;
+    /**
+     * Orçamento de tempo (ms) propagado a cada job via {@link JobContext.timeoutMs}
+     * (#68) — os jobs de extração o repassam ao watchdog do subprocesso. Omitido =
+     * cada job usa seu próprio default. A fila NÃO cancela o job por conta própria.
+     */
+    readonly jobTimeoutMs?: number;
+    /**
+     * Sinal de CANCELAMENTO da fila inteira (#69, ADR-005). Ao disparar: os jobs em
+     * execução recebem o signal via {@link JobContext.signal} (matam o subprocesso e
+     * rejeitam) e são observados como `cancelled`; os jobs `pending` que ainda NÃO
+     * iniciaram são marcados `cancelled` sem iniciar. Cada transição emite UM evento.
+     * Omitido = a fila não é cancelável (comportamento #67/#68 inalterado).
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Limite de concorrência padrão da fila: `os.cpus().length − 1`, com piso de 1
+ * para máquinas de 1 núcleo (ADR-005 — deixa um núcleo livre para a UI/event
+ * loop enquanto o binário externo trabalha).
+ *
+ * @returns O número máximo de jobs simultâneos recomendado para esta máquina.
+ */
+export declare function defaultConcurrency(): number;
+/**
+ * Roda uma coleção de jobs com concorrência limitada, expondo cada transição de
+ * estado como um `AsyncIterable<QueueEvent<T>>` (contrato do core, ADR-005).
+ *
+ * Garantias:
+ * - **Concorrência**: nunca há mais que `concurrency` jobs em `processing` ao
+ *   mesmo tempo; os excedentes ficam em `pending` até um slot liberar (FIFO —
+ *   a ordem de enfileiramento é respeitada).
+ * - **Observabilidade**: todo job emite `pending` (no enfileiramento), depois
+ *   `processing` (ao iniciar) e por fim `done` (com `result`) ou `failed` (com
+ *   `reason`/`error`).
+ * - **Isolamento de falha**: um job que rejeita vira `failed` e NÃO interrompe
+ *   os demais — a fila continua até drenar. `runQueue` nunca rejeita por causa
+ *   de um job.
+ *
+ * @typeParam T - Tipo do resultado dos jobs em caso de sucesso.
+ * @param jobs - Jobs a executar, na ordem de prioridade (FIFO).
+ * @param options - Concorrência e logger — ver {@link RunQueueOptions}.
+ * @returns Sequência assíncrona de transições, terminada quando a fila drena.
+ * @example
+ * for await (const event of runQueue(jobs, { concurrency: 2 })) {
+ *   if (event.status === 'failed') logger.warn(event.reason ?? 'falhou');
+ * }
+ */
+export declare function runQueue<T>(jobs: Iterable<QueueJob<T>>, options?: RunQueueOptions): AsyncIterable<QueueEvent<T>>;