@spinajs/queue-templates-pdf 2.0.482

package/README.md

@@ -0,0 +1,101 @@
+# @spinajs/queue-templates-pdf
+
+A SpinaJS queue job that renders a PDF template in an **isolated worker process**
+and reports render progress (percent + phase + message) back to the queue.
+
+All heavy, crash-prone work — Chromium, template compilation, upload — runs in a
+forked worker. The job in the queue consumer only supervises it, so a hung or
+crashing render can never take down the worker, and memory is reclaimed per render.
+
+## Installation
+
+```bash
+npm install @spinajs/queue-templates-pdf
+```
+
+Requires a configured queue (transport + DB for the job model) and at least one
+`@spinajs/fs` provider for the output.
+
+## Usage
+
+```ts
+import { scheduleRenderPdf } from '@spinajs/queue-templates-pdf';
+
+// render now
+await scheduleRenderPdf({
+  input: 'invoices/invoice.pug', // a template (template: true) or raw HTML
+  template: true,
+  model: { total: 42 },
+  lang: 'en',
+  output: { provider: 's3', path: 'invoices/2026/1.pdf' }, // any @spinajs/fs provider
+  pdfOptions: { format: 'A4', printBackground: true },
+});
+
+// render in 5 minutes
+await scheduleRenderPdf(payload, { delay: 5 * 60 * 1000 });
+
+// recurring: every day at 06:00
+await scheduleRenderPdf(payload, { cron: '0 6 * * *' });
+```
+
+The job must be consumed by a queue worker:
+
+```ts
+import { RenderPdfJob } from '@spinajs/queue-templates-pdf';
+const queue = await DI.resolve(QueueService);
+await queue.consume(RenderPdfJob);
+```
+
+## Output
+
+`output: { provider, path }` names a configured `@spinajs/fs` provider (local,
+temp, S3, ...) and a path relative to it. The worker renders to a local temp file
+and uploads it to that provider, so the same job works for local disk or object
+storage without change.
+
+## Progress
+
+The worker streams progress; the supervisor forwards it to the queue job model:
+
+- **percent** 0–100 (phase-weighted),
+- **phase** — `starting` → `preparing` → `loading` → `rendering` → `done` (or `failed`),
+- **message** — e.g. `Loading resources (12 done, 3 pending)`.
+
+With `@spinajs/queue-http-progress` this is exposed at:
+
+```
+GET jobs/v1/:jobId/status
+-> { jobId, progress, phase, message, status, createdAt }
+```
+
+`scheduleRenderPdf` (and `RenderPdfJob.emit`) return the generated `jobId`, so you
+can hand it straight to the status endpoint:
+
+```ts
+const jobId = await scheduleRenderPdf(payload);
+// later: GET jobs/v1/${jobId}/status
+```
+
+## Worker configuration
+
+The worker re-bootstraps the app configuration by default (it runs in the app's
+config environment: same config sources / cwd, so it resolves the same
+`templates.pdf` launch args and fs providers). For environments where that is not
+possible, pass an inline `config` object in the payload and the worker will
+bootstrap from it instead.
+
+## How it works
+
+```
+scheduleRenderPdf ─► RenderPdfJob (queue consumer)
+                       │  fork()
+                       ▼
+                     render-worker (separate process)
+                       ├─ bootstrap config/DI
+                       ├─ Templates.render (template mode) ─► HTML
+                       ├─ PdfRenderer.renderHtmlToFile ──── onProgress ─┐
+                       └─ fs provider.upload(tmp → output.path)         │
+                       ▲                                                │
+   progress(percent, {phase, message}) ◄── IPC ◄─────────────────────-─┘
+   (persisted to the job model, exposed over HTTP)
+```

package/lib/cjs/RenderPdfJob.d.ts

@@ -0,0 +1,38 @@
+import { ChildProcess } from 'child_process';
+import { QueueJob, JobProgressCallback } from '@spinajs/queue';
+import { Log } from '@spinajs/log';
+import { IRenderRequest, IRenderOutput } from './protocol.js';
+/**
+ * Queue job that renders a PDF in an isolated worker process and reports render
+ * progress (percent + phase + message) back to the queue. All heavy/crash-prone
+ * work (Chromium, template compile, fs upload) runs in the forked worker; this
+ * class only supervises it.
+ */
+export declare class RenderPdfJob extends QueueJob {
+    protected Log: Log;
+    /** Template path (template mode) or raw HTML string. */
+    input: string;
+    /** When true, `input` is a template rendered by extension; otherwise raw HTML. */
+    template?: boolean;
+    model?: unknown;
+    lang?: string;
+    /** Destination @spinajs/fs provider + path. */
+    output: IRenderOutput;
+    pdfOptions?: Record<string, unknown>;
+    assetBasePath?: string;
+    /** Optional inline worker config; omit to re-bootstrap the ambient app config. */
+    config?: unknown;
+    /** Max render duration before the worker is killed (ms). */
+    timeoutMs?: number;
+    execute(progress: JobProgressCallback): Promise<unknown>;
+    /** Spawn the render worker process. Overridable in tests. */
+    protected spawnWorker(): ChildProcess;
+    protected buildRequest(): IRenderRequest;
+    /**
+     * Drive one worker to completion: relay progress to the queue, resolve on
+     * `done`, reject on `error` / unexpected exit, and force-kill on timeout.
+     * Every terminal path clears the timer and detaches listeners exactly once.
+     */
+    protected superviseChild(child: ChildProcess, progress: JobProgressCallback): Promise<IRenderOutput>;
+}
+//# sourceMappingURL=RenderPdfJob.d.ts.map

package/lib/cjs/RenderPdfJob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderPdfJob.d.ts","sourceRoot":"","sources":["../../src/RenderPdfJob.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,YAAY,EAAE,MAAM,eAAe,CAAC;AAGnD,OAAO,EAAE,QAAQ,EAAO,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,GAAG,EAAU,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,aAAa,EAAiB,MAAM,eAAe,CAAC;AAqB7E;;;;;GAKG;AACH,qBACa,YAAa,SAAQ,QAAQ;IAExC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC;IAEnB,wDAAwD;IACjD,KAAK,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAC3E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IACxC,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IAC9B,kFAAkF;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;IACxB,4DAA4D;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IAEb,OAAO,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrE,6DAA6D;IAC7D,SAAS,CAAC,WAAW,IAAI,YAAY;IAIrC,SAAS,CAAC,YAAY,IAAI,cAAc;IAaxC;;;;OAIG;IACH,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC;CA6CrG"}

package/lib/cjs/RenderPdfJob.js

@@ -0,0 +1,114 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RenderPdfJob = void 0;
+const child_process_1 = require("child_process");
+const path_1 = require("path");
+const url_1 = require("url");
+const queue_1 = require("@spinajs/queue");
+const log_1 = require("@spinajs/log");
+/** Default max render duration before the worker is force-killed (ms). */
+const DEFAULT_RENDER_TIMEOUT_MS = 120000;
+/**
+ * This module's directory, resolved across the dual ESM/CJS build. Under CJS
+ * `__dirname` exists; under ESM it does not, so we fall back to `import.meta.url`
+ * - accessed via `eval` so the `import.meta` token never appears in the
+ * commonjs-compiled output (which would otherwise fail to compile).
+ */
+function moduleDir() {
+    if (typeof __dirname !== 'undefined') {
+        return __dirname;
+    }
+    // eslint-disable-next-line no-eval
+    const url = eval('import.meta.url');
+    return (0, path_1.dirname)((0, url_1.fileURLToPath)(url));
+}
+/**
+ * Queue job that renders a PDF in an isolated worker process and reports render
+ * progress (percent + phase + message) back to the queue. All heavy/crash-prone
+ * work (Chromium, template compile, fs upload) runs in the forked worker; this
+ * class only supervises it.
+ */
+let RenderPdfJob = class RenderPdfJob extends queue_1.QueueJob {
+    async execute(progress) {
+        const child = this.spawnWorker();
+        return this.superviseChild(child, progress);
+    }
+    /** Spawn the render worker process. Overridable in tests. */
+    spawnWorker() {
+        return (0, child_process_1.fork)((0, path_1.join)(moduleDir(), 'render-worker.js'));
+    }
+    buildRequest() {
+        return {
+            input: this.input,
+            template: this.template,
+            model: this.model,
+            lang: this.lang,
+            output: this.output,
+            pdfOptions: this.pdfOptions,
+            assetBasePath: this.assetBasePath,
+            config: this.config,
+        };
+    }
+    /**
+     * Drive one worker to completion: relay progress to the queue, resolve on
+     * `done`, reject on `error` / unexpected exit, and force-kill on timeout.
+     * Every terminal path clears the timer and detaches listeners exactly once.
+     */
+    superviseChild(child, progress) {
+        const timeoutMs = this.timeoutMs ?? DEFAULT_RENDER_TIMEOUT_MS;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const settle = (action) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                child.removeAllListeners('message');
+                child.removeAllListeners('error');
+                child.removeAllListeners('exit');
+                action();
+            };
+            const timer = setTimeout(() => {
+                settle(() => reject(new Error(`Render worker timed out after ${timeoutMs}ms`)));
+                child.kill('SIGKILL');
+            }, timeoutMs);
+            child.on('message', (m) => {
+                switch (m.type) {
+                    case 'progress':
+                        // fire-and-forget: never block the worker on progress persistence
+                        progress(m.percent, { phase: m.phase, message: m.message }).catch((err) => this.Log?.warn(`Failed to persist progress: ${err.message}`));
+                        break;
+                    case 'done':
+                        settle(() => resolve(m.result));
+                        break;
+                    case 'error':
+                        settle(() => reject(new Error(m.message)));
+                        child.kill();
+                        break;
+                }
+            });
+            child.on('error', (err) => settle(() => reject(err)));
+            child.on('exit', (code) => settle(() => reject(new Error(`Render worker exited unexpectedly with code ${code}`))));
+            child.send(this.buildRequest());
+        });
+    }
+};
+exports.RenderPdfJob = RenderPdfJob;
+__decorate([
+    (0, log_1.Logger)('RenderPdfJob'),
+    __metadata("design:type", log_1.Log)
+], RenderPdfJob.prototype, "Log", void 0);
+exports.RenderPdfJob = RenderPdfJob = __decorate([
+    (0, queue_1.Job)()
+], RenderPdfJob);
+//# sourceMappingURL=RenderPdfJob.js.map

package/lib/cjs/RenderPdfJob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderPdfJob.js","sourceRoot":"","sources":["../../src/RenderPdfJob.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,iDAAmD;AACnD,+BAAqC;AACrC,6BAAoC;AACpC,0CAAoE;AACpE,sCAA2C;AAG3C,0EAA0E;AAC1E,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAEzC;;;;;GAKG;AACH,SAAS,SAAS;IAChB,IAAI,OAAO,SAAS,KAAK,WAAW,EAAE,CAAC;QACrC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,mCAAmC;IACnC,MAAM,GAAG,GAAG,IAAI,CAAC,iBAAiB,CAAW,CAAC;IAC9C,OAAO,IAAA,cAAO,EAAC,IAAA,mBAAa,EAAC,GAAG,CAAC,CAAC,CAAC;AACrC,CAAC;AAED;;;;;GAKG;AAEI,IAAM,YAAY,GAAlB,MAAM,YAAa,SAAQ,gBAAQ;IAmBjC,KAAK,CAAC,OAAO,CAAC,QAA6B;QAChD,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAED,6DAA6D;IACnD,WAAW;QACnB,OAAO,IAAA,oBAAI,EAAC,IAAA,WAAI,EAAC,SAAS,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC;IACrD,CAAC;IAES,YAAY;QACpB,OAAO;YACL,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACO,cAAc,CAAC,KAAmB,EAAE,QAA6B;QACzE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,yBAAyB,CAAC;QAE9D,OAAO,IAAI,OAAO,CAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACpD,IAAI,OAAO,GAAG,KAAK,CAAC;YAEpB,MAAM,MAAM,GAAG,CAAC,MAAkB,EAAE,EAAE;gBACpC,IAAI,OAAO,EAAE,CAAC;oBACZ,OAAO;gBACT,CAAC;gBACD,OAAO,GAAG,IAAI,CAAC;gBACf,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,KAAK,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;gBACpC,KAAK,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;gBAClC,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;gBACjC,MAAM,EAAE,CAAC;YACX,CAAC,CAAC;YAEF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,iCAAiC,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC;gBAChF,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACxB,CAAC,EAAE,SAAS,CAAC,CAAC;YAEd,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,CAAgB,EAAE,EAAE;gBACvC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;oBACf,KAAK,UAAU;wBACb,kEAAkE;wBAClE,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,+BAA+B,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;wBACzI,MAAM;oBACR,KAAK,MAAM;wBACT,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;wBAChC,MAAM;oBACR,KAAK,OAAO;wBACV,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;wBAC3C,KAAK,CAAC,IAAI,EAAE,CAAC;wBACb,MAAM;gBACV,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACtD,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,+CAA+C,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YAEnH,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QAClC,CAAC,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AA5FY,oCAAY;AAEb;IADT,IAAA,YAAM,EAAC,cAAc,CAAC;8BACR,SAAG;yCAAC;uBAFR,YAAY;IADxB,IAAA,WAAG,GAAE;GACO,YAAY,CA4FxB"}

package/lib/cjs/index.d.ts

@@ -0,0 +1,5 @@
+export * from './protocol.js';
+export * from './render.js';
+export * from './RenderPdfJob.js';
+export * from './schedule.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC"}

package/lib/cjs/index.js

@@ -0,0 +1,25 @@
+"use strict";
+// @spinajs/queue-templates-pdf
+//
+// A queue job that renders a PDF template in an isolated worker process and
+// reports render progress (percent + phase + message) back to the queue.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./protocol.js"), exports);
+__exportStar(require("./render.js"), exports);
+__exportStar(require("./RenderPdfJob.js"), exports);
+__exportStar(require("./schedule.js"), exports);
+//# sourceMappingURL=index.js.map

package/lib/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA,+BAA+B;AAC/B,EAAE;AACF,4EAA4E;AAC5E,yEAAyE;;;;;;;;;;;;;;;;AAEzE,gDAA8B;AAC9B,8CAA4B;AAC5B,oDAAkC;AAClC,gDAA8B"}

package/lib/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/lib/cjs/protocol.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Where a rendered PDF is written - a named @spinajs/fs provider and a path
+ * relative to that provider's base.
+ */
+export interface IRenderOutput {
+    /** Configured @spinajs/fs provider name (local / temp / s3 / ...). */
+    provider: string;
+    /** Destination path relative to the provider base. */
+    path: string;
+}
+/**
+ * A single PDF render request handed to the worker process.
+ */
+export interface IRenderRequest {
+    /** Template path (template mode) or a raw HTML string. */
+    input: string;
+    /** When true, `input` is a template rendered via the text engine by extension; otherwise it is raw HTML. */
+    template?: boolean;
+    /** Model passed to the template (template mode). */
+    model?: unknown;
+    /** Optional language (template mode). */
+    lang?: string;
+    /** Where to write the resulting PDF. */
+    output: IRenderOutput;
+    /** Puppeteer PDF options (format, landscape, scale, ...). */
+    pdfOptions?: Record<string, unknown>;
+    /** Directory served over the local http server so relative asset URLs resolve (raw HTML mode). */
+    assetBasePath?: string;
+    /**
+     * Optional inline configuration for the worker. When present it is used to
+     * bootstrap the worker's Configuration; otherwise the worker resolves the
+     * ambient app Configuration (re-bootstrap model).
+     */
+    config?: unknown;
+}
+/** Messages the worker sends back to its parent over the IPC channel. */
+export type WorkerMessage = {
+    type: 'progress';
+    percent: number;
+    phase: string;
+    message?: string;
+} | {
+    type: 'done';
+    result: IRenderOutput;
+} | {
+    type: 'error';
+    message: string;
+};
+//# sourceMappingURL=protocol.d.ts.map

package/lib/cjs/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/protocol.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,4GAA4G;IAC5G,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,MAAM,EAAE,aAAa,CAAC;IACtB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,kGAAkG;IAClG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,yEAAyE;AACzE,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/lib/cjs/protocol.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=protocol.js.map

package/lib/cjs/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/protocol.ts"],"names":[],"mappings":""}

package/lib/cjs/render-worker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=render-worker.d.ts.map

package/lib/cjs/render-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-worker.d.ts","sourceRoot":"","sources":["../../src/render-worker.ts"],"names":[],"mappings":""}

package/lib/cjs/render-worker.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const di_1 = require("@spinajs/di");
+const render_js_1 = require("./render.js");
+/**
+ * Render worker entrypoint. Forked by {@link RenderPdfJob} with an IPC channel:
+ * the parent sends an {@link IRenderRequest}, the worker streams `progress`
+ * messages and finishes with `done` or `error`, then exits so its process (and
+ * the pooled Chromium) is fully reclaimed.
+ */
+function send(message) {
+    process.send?.(message);
+}
+process.on('message', async (req) => {
+    try {
+        const result = await (0, render_js_1.renderPdfToProvider)(req, (m) => send(m));
+        send({ type: 'done', result });
+        await di_1.DI.dispose();
+        process.exit(0);
+    }
+    catch (err) {
+        send({ type: 'error', message: err?.message ?? String(err) });
+        try {
+            await di_1.DI.dispose();
+        }
+        catch {
+            /* best-effort cleanup on the error path */
+        }
+        process.exit(1);
+    }
+});
+//# sourceMappingURL=render-worker.js.map

package/lib/cjs/render-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-worker.js","sourceRoot":"","sources":["../../src/render-worker.ts"],"names":[],"mappings":";;AAAA,oCAAiC;AACjC,2CAAkD;AAGlD;;;;;GAKG;AACH,SAAS,IAAI,CAAC,OAAsB;IAClC,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC;AAED,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,GAAmB,EAAE,EAAE;IAClD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAA,+BAAmB,EAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9D,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/B,MAAM,OAAE,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC;YACH,MAAM,OAAE,CAAC,OAAO,EAAE,CAAC;QACrB,CAAC;QAAC,MAAM,CAAC;YACP,2CAA2C;QAC7C,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC"}

package/lib/cjs/render.d.ts

@@ -0,0 +1,17 @@
+import { IRenderRequest, IRenderOutput, WorkerMessage } from './protocol.js';
+import '@spinajs/templates-pdf';
+import '@spinajs/fs';
+type ProgressMessage = Extract<WorkerMessage, {
+    type: 'progress';
+}>;
+/**
+ * Render a PDF for `req` and upload it to the requested @spinajs/fs provider,
+ * reporting progress via `onProgress`. This is the testable core shared by the
+ * worker entrypoint - it performs the heavy work (template compile, Chromium
+ * render, upload) and cleans up its temp file.
+ *
+ * @returns the output descriptor (provider + path) on success.
+ */
+export declare function renderPdfToProvider(req: IRenderRequest, onProgress: (m: ProgressMessage) => void): Promise<IRenderOutput>;
+export {};
+//# sourceMappingURL=render.d.ts.map

package/lib/cjs/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/render.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG7E,OAAO,wBAAwB,CAAC;AAChC,OAAO,aAAa,CAAC;AAErB,KAAK,eAAe,GAAG,OAAO,CAAC,aAAa,EAAE;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,CAAC;AA4BpE;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,CA0B/H"}

package/lib/cjs/render.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderPdfToProvider = renderPdfToProvider;
+const di_1 = require("@spinajs/di");
+const configuration_1 = require("@spinajs/configuration");
+const templates_1 = require("@spinajs/templates");
+const templates_pdf_1 = require("@spinajs/templates-pdf");
+const fs_1 = require("@spinajs/fs");
+const path_1 = require("path");
+const os_1 = require("os");
+const promises_1 = require("fs/promises");
+// registers the PDF renderer (+ puppeteer/pug) and the fs providers as a side effect
+require("@spinajs/templates-pdf");
+require("@spinajs/fs");
+let tmpCounter = 0;
+/**
+ * Bootstrap the worker's DI/config. With an inline `config` a Configuration is
+ * registered from it; otherwise the ambient Configuration is resolved (the
+ * re-bootstrap model - the worker shares the app's config environment). The fs
+ * providers are then initialized.
+ */
+async function bootstrap(config) {
+    if (config) {
+        class WorkerConfiguration extends configuration_1.FrameworkConfiguration {
+            onLoad() {
+                return config;
+            }
+        }
+        di_1.DI.register(WorkerConfiguration).as(configuration_1.Configuration);
+    }
+    await di_1.DI.resolve(configuration_1.Configuration);
+    // register the `__file_provider__` factory, then build the configured providers
+    const fsBootstrapper = await di_1.DI.resolve(fs_1.FsBootsrapper);
+    fsBootstrapper.bootstrap();
+    await di_1.DI.resolve(fs_1.fsService);
+}
+/**
+ * Render a PDF for `req` and upload it to the requested @spinajs/fs provider,
+ * reporting progress via `onProgress`. This is the testable core shared by the
+ * worker entrypoint - it performs the heavy work (template compile, Chromium
+ * render, upload) and cleans up its temp file.
+ *
+ * @returns the output descriptor (provider + path) on success.
+ */
+async function renderPdfToProvider(req, onProgress) {
+    await bootstrap(req.config);
+    const templates = await di_1.DI.resolve(templates_1.Templates);
+    const renderer = await di_1.DI.resolve(templates_pdf_1.PdfRenderer, [req.pdfOptions ?? {}]);
+    const provider = await di_1.DI.resolve('__file_provider__', [req.output.provider]);
+    const html = req.template ? await templates.render(req.input, req.model, req.lang) : req.input;
+    const tmp = (0, path_1.join)((0, os_1.tmpdir)(), `spinajs-pdf-${process.pid}-${Date.now()}-${tmpCounter++}.pdf`);
+    try {
+        await renderer.renderHtmlToFile(html, tmp, {
+            assetBasePath: req.assetBasePath,
+            onProgress: (p) => onProgress({ type: 'progress', percent: p.percent, phase: p.phase, message: p.message }),
+        });
+        // push the locally-rendered temp file to the configured destination provider
+        await provider.upload(tmp, req.output.path);
+        return req.output;
+    }
+    finally {
+        await (0, promises_1.unlink)(tmp).catch(() => {
+            /* temp may not exist if the render failed before writing */
+        });
+    }
+}
+//# sourceMappingURL=render.js.map

package/lib/cjs/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/render.ts"],"names":[],"mappings":";;AAkDA,kDA0BC;AA5ED,oCAAiC;AACjC,0DAA+E;AAC/E,kDAA+C;AAC/C,0DAAqD;AACrD,oCAA2D;AAC3D,+BAA4B;AAC5B,2BAA4B;AAC5B,0CAAqC;AAGrC,qFAAqF;AACrF,kCAAgC;AAChC,uBAAqB;AAIrB,IAAI,UAAU,GAAG,CAAC,CAAC;AAEnB;;;;;GAKG;AACH,KAAK,UAAU,SAAS,CAAC,MAAgB;IACvC,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,mBAAoB,SAAQ,sCAAsB;YAC5C,MAAM;gBACd,OAAO,MAAM,CAAC;YAChB,CAAC;SACF;QACD,OAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC,EAAE,CAAC,6BAAa,CAAC,CAAC;IACrD,CAAC;IAED,MAAM,OAAE,CAAC,OAAO,CAAC,6BAAa,CAAC,CAAC;IAEhC,gFAAgF;IAChF,MAAM,cAAc,GAAG,MAAM,OAAE,CAAC,OAAO,CAAC,kBAAa,CAAC,CAAC;IACvD,cAAc,CAAC,SAAS,EAAE,CAAC;IAC3B,MAAM,OAAE,CAAC,OAAO,CAAC,cAAS,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,mBAAmB,CAAC,GAAmB,EAAE,UAAwC;IACrG,MAAM,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAE5B,MAAM,SAAS,GAAG,MAAM,OAAE,CAAC,OAAO,CAAC,qBAAS,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,MAAM,OAAE,CAAC,OAAO,CAAC,2BAAW,EAAE,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,CAAC;IACvE,MAAM,QAAQ,GAAG,MAAM,OAAE,CAAC,OAAO,CAAK,mBAAmB,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IAElF,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;IAE/F,MAAM,GAAG,GAAG,IAAA,WAAI,EAAC,IAAA,WAAM,GAAE,EAAE,eAAe,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,UAAU,EAAE,MAAM,CAAC,CAAC;IAE3F,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE;YACzC,aAAa,EAAE,GAAG,CAAC,aAAa;YAChC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;SAC5G,CAAC,CAAC;QAEH,6EAA6E;QAC7E,MAAM,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAE5C,OAAO,GAAG,CAAC,MAAM,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,MAAM,IAAA,iBAAM,EAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YAC3B,4DAA4D;QAC9D,CAAC,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/lib/cjs/schedule.d.ts

@@ -0,0 +1,48 @@
+import { IRenderOutput } from './protocol.js';
+/** Payload for a {@link RenderPdfJob} - the fields describing what to render and where. */
+export interface IRenderPdfJobPayload {
+    /** Template path (template mode) or raw HTML string. */
+    input: string;
+    /** When true, `input` is a template rendered by extension; otherwise raw HTML. */
+    template?: boolean;
+    model?: unknown;
+    lang?: string;
+    /** Destination @spinajs/fs provider + path. */
+    output: IRenderOutput;
+    pdfOptions?: Record<string, unknown>;
+    assetBasePath?: string;
+    /** Optional inline worker config; omit to re-bootstrap the ambient app config. */
+    config?: unknown;
+    /** Max render duration before the worker is killed (ms). */
+    timeoutMs?: number;
+}
+/** Scheduling options for {@link scheduleRenderPdf}. */
+export interface IScheduleRenderPdfOptions {
+    /** Delay before the job is delivered (ms). */
+    delay?: number;
+    /** Cron expression for recurring rendering (e.g. `0 6 * * *` for a daily report). */
+    cron?: string;
+    /** Period between repeats (ms), used with `repeat`. */
+    period?: number;
+    /** Number of times to repeat the schedule. */
+    repeat?: number;
+}
+/**
+ * Enqueue a PDF render job. With no options it runs as soon as a consumer picks
+ * it up; `delay` schedules it later; `cron` (or `period` + `repeat`) makes it
+ * recurring.
+ *
+ * Progress is tracked on the queue job model and exposed via
+ * `@spinajs/queue-http-progress` at `GET jobs/v1/:jobId/status`
+ * (percent + phase + message).
+ *
+ * @returns the JobId, for correlating the render with its progress/status endpoint.
+ *
+ * @example
+ * // render now, then poll GET jobs/v1/:jobId/status
+ * const jobId = await scheduleRenderPdf({ input: 'invoice.pug', template: true, model, output: { provider: 's3', path: 'invoices/1.pdf' } });
+ * // daily at 6am
+ * await scheduleRenderPdf({ input: 'report.pug', template: true, output: { provider: 'local', path: 'daily.pdf' } }, { cron: '0 6 * * *' });
+ */
+export declare function scheduleRenderPdf(payload: IRenderPdfJobPayload, options?: IScheduleRenderPdfOptions): Promise<string | undefined>;
+//# sourceMappingURL=schedule.d.ts.map

package/lib/cjs/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/schedule.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,2FAA2F;AAC3F,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wDAAwD;AACxD,MAAM,WAAW,yBAAyB;IACxC,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAWvI"}

package/lib/cjs/schedule.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scheduleRenderPdf = scheduleRenderPdf;
+const RenderPdfJob_js_1 = require("./RenderPdfJob.js");
+/**
+ * Enqueue a PDF render job. With no options it runs as soon as a consumer picks
+ * it up; `delay` schedules it later; `cron` (or `period` + `repeat`) makes it
+ * recurring.
+ *
+ * Progress is tracked on the queue job model and exposed via
+ * `@spinajs/queue-http-progress` at `GET jobs/v1/:jobId/status`
+ * (percent + phase + message).
+ *
+ * @returns the JobId, for correlating the render with its progress/status endpoint.
+ *
+ * @example
+ * // render now, then poll GET jobs/v1/:jobId/status
+ * const jobId = await scheduleRenderPdf({ input: 'invoice.pug', template: true, model, output: { provider: 's3', path: 'invoices/1.pdf' } });
+ * // daily at 6am
+ * await scheduleRenderPdf({ input: 'report.pug', template: true, output: { provider: 'local', path: 'daily.pdf' } }, { cron: '0 6 * * *' });
+ */
+async function scheduleRenderPdf(payload, options) {
+    // Only include schedule fields that are set. IMessageOptions declares all fields
+    // required, but emit() spreads options into the message, so absent fields behave
+    // exactly like calling emit with no options.
+    const scheduleOptions = {};
+    if (options?.delay !== undefined)
+        scheduleOptions.ScheduleDelay = options.delay;
+    if (options?.cron !== undefined)
+        scheduleOptions.ScheduleCron = options.cron;
+    if (options?.period !== undefined)
+        scheduleOptions.SchedulePeriod = options.period;
+    if (options?.repeat !== undefined)
+        scheduleOptions.ScheduleRepeat = options.repeat;
+    return RenderPdfJob_js_1.RenderPdfJob.emit(payload, scheduleOptions);
+}
+//# sourceMappingURL=schedule.js.map

package/lib/cjs/schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.js","sourceRoot":"","sources":["../../src/schedule.ts"],"names":[],"mappings":";;AAmDA,8CAWC;AA7DD,uDAAiD;AAiCjD;;;;;;;;;;;;;;;;GAgBG;AACI,KAAK,UAAU,iBAAiB,CAAC,OAA6B,EAAE,OAAmC;IACxG,iFAAiF;IACjF,iFAAiF;IACjF,6CAA6C;IAC7C,MAAM,eAAe,GAA6B,EAAE,CAAC;IACrD,IAAI,OAAO,EAAE,KAAK,KAAK,SAAS;QAAE,eAAe,CAAC,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC;IAChF,IAAI,OAAO,EAAE,IAAI,KAAK,SAAS;QAAE,eAAe,CAAC,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAC7E,IAAI,OAAO,EAAE,MAAM,KAAK,SAAS;QAAE,eAAe,CAAC,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IACnF,IAAI,OAAO,EAAE,MAAM,KAAK,SAAS;QAAE,eAAe,CAAC,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAEnF,OAAO,8BAAY,CAAC,IAAI,CAAC,OAAO,EAAE,eAAkC,CAAC,CAAC;AACxE,CAAC"}

package/lib/mjs/RenderPdfJob.d.ts

@@ -0,0 +1,38 @@
+import { ChildProcess } from 'child_process';
+import { QueueJob, JobProgressCallback } from '@spinajs/queue';
+import { Log } from '@spinajs/log';
+import { IRenderRequest, IRenderOutput } from './protocol.js';
+/**
+ * Queue job that renders a PDF in an isolated worker process and reports render
+ * progress (percent + phase + message) back to the queue. All heavy/crash-prone
+ * work (Chromium, template compile, fs upload) runs in the forked worker; this
+ * class only supervises it.
+ */
+export declare class RenderPdfJob extends QueueJob {
+    protected Log: Log;
+    /** Template path (template mode) or raw HTML string. */
+    input: string;
+    /** When true, `input` is a template rendered by extension; otherwise raw HTML. */
+    template?: boolean;
+    model?: unknown;
+    lang?: string;
+    /** Destination @spinajs/fs provider + path. */
+    output: IRenderOutput;
+    pdfOptions?: Record<string, unknown>;
+    assetBasePath?: string;
+    /** Optional inline worker config; omit to re-bootstrap the ambient app config. */
+    config?: unknown;
+    /** Max render duration before the worker is killed (ms). */
+    timeoutMs?: number;
+    execute(progress: JobProgressCallback): Promise<unknown>;
+    /** Spawn the render worker process. Overridable in tests. */
+    protected spawnWorker(): ChildProcess;
+    protected buildRequest(): IRenderRequest;
+    /**
+     * Drive one worker to completion: relay progress to the queue, resolve on
+     * `done`, reject on `error` / unexpected exit, and force-kill on timeout.
+     * Every terminal path clears the timer and detaches listeners exactly once.
+     */
+    protected superviseChild(child: ChildProcess, progress: JobProgressCallback): Promise<IRenderOutput>;
+}
+//# sourceMappingURL=RenderPdfJob.d.ts.map