@spinajs/templates 2.0.481 → 2.0.484

package/lib/mjs/index.js

@@ -9,11 +9,15 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 import { InvalidOperation } from '@spinajs/exceptions';
 import { AsyncService, Inject, Autoinject } from '@spinajs/di';
-import { Log, Logger } from '@spinajs/log';
+import { Log, Logger, Perf } from '@spinajs/log';
 import { TemplateRenderer } from './interfaces.js';
 import { extname } from 'path';
 import { Intl } from '@spinajs/intl';
 export * from './interfaces.js';
+export * from './progress.js';
+export * from './io.js';
+export * from './CompiledTemplateRenderer.js';
+export * from './cli/renderHelpers.js';
 /**
  * Inject INTL module for language support. We does nothing but to initialize module for use in templates.
  */
@@ -21,12 +25,9 @@ let Templates = class Templates extends AsyncService {
     getRendererFor(extname) {
         return this.Renderers.find((x) => x.Extension === extname);
     }
-    async compileToFile(template, renderer, model, filePath, language) {
-        const engine = this.Renderers.find((x) => x.Type === renderer);
-        if (!engine) {
-            throw new InvalidOperation(`No renderer for ${renderer}`);
-        }
-        return await engine.renderToFile(template, model, filePath, language);
+    async compileToFile(template, renderer, model, filePath, language, options) {
+        const engine = this.engineByType(renderer);
+        return await Perf.measure('template.compile', () => engine.renderToFile(template, model, filePath, language, options), { labels: { engine: engine.Type }, fields: { template } });
     }
     /**
      *
@@ -36,14 +37,12 @@ let Templates = class Templates extends AsyncService {
      * @param renderer
      * @param model
      * @param language
+     * @param options - optional render options (e.g. progress reporting)
      * @returns
      */
-    async compile(template, renderer, model, language) {
-        const engine = this.Renderers.find((x) => x.Type === renderer);
-        if (!engine) {
-            throw new InvalidOperation(`No renderer for ${renderer}`);
-        }
-        return await engine.render(template, model, language);
+    async compile(template, renderer, model, language, options) {
+        const engine = this.engineByType(renderer);
+        return await Perf.measure('template.compile', () => engine.render(template, model, language, options), { labels: { engine: engine.Type }, fields: { template } });
     }
     /**
      *
@@ -53,23 +52,39 @@ let Templates = class Templates extends AsyncService {
      * @param template
      * @param model
      * @param language
+     * @param options - optional render options (e.g. progress reporting)
      * @returns
      */
-    async render(template, model, language) {
-        const extension = extname(template);
-        const renderer = this.Renderers.find((x) => x.Extension === extension);
-        if (!renderer) {
-            throw new InvalidOperation(`No renderer for file ${template} with extension ${extension}`);
+    async render(template, model, language, options) {
+        const renderer = this.engineByExtension(template);
+        return await Perf.measure('template.render', () => renderer.render(template, model, language, options), { labels: { engine: renderer.Type }, fields: { template } });
+    }
+    async renderToFile(template, model, filePath, language, options) {
+        const renderer = this.engineByExtension(template);
+        return await Perf.measure('template.render', () => renderer.renderToFile(template, model, filePath, language, options), { labels: { engine: renderer.Type }, fields: { template } });
+    }
+    /**
+     * Finds the renderer registered under the given renderer type (e.g. `handlebars`,
+     * `pdf`), throwing if none is registered.
+     */
+    engineByType(renderer) {
+        const engine = this.Renderers.find((x) => x.Type === renderer);
+        if (!engine) {
+            throw new InvalidOperation(`No renderer for ${renderer}`);
         }
-        return await renderer.render(template, model, language);
+        return engine;
     }
-    async renderToFile(template, model, filePath, language) {
+    /**
+     * Finds the renderer matching the template file's extension, throwing if none
+     * is registered for that extension.
+     */
+    engineByExtension(template) {
         const extension = extname(template);
         const renderer = this.Renderers.find((x) => x.Extension === extension);
         if (!renderer) {
             throw new InvalidOperation(`No renderer for file ${template} with extension ${extension}`);
         }
-        return await renderer.renderToFile(template, model, filePath, language);
+        return renderer;
     }
 };
 __decorate([

package/lib/mjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAEhC;;GAEG;AAEI,IAAM,SAAS,GAAf,MAAM,SAAU,SAAQ,YAAY;IAOlC,cAAc,CAAC,OAAe;QACnC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,OAAO,CAAE,CAAC;IAC9D,CAAC;IAEM,KAAK,CAAC,aAAa,CAAC,QAAgB,EAAE,QAAgB,EAAE,KAAc,EAAE,QAAgB,EAAE,QAAiB;QAChH,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;QAC/D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,gBAAgB,CAAC,mBAAmB,QAAQ,EAAE,CAAC,CAAC;QAC5D,CAAC;QAED,OAAO,MAAM,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACxE,CAAC;IAED;;;;;;;;;OASG;IACI,KAAK,CAAC,OAAO,CAAC,QAAgB,EAAE,QAAgB,EAAE,KAAc,EAAE,QAAiB;QACxF,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;QAC/D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,gBAAgB,CAAC,mBAAmB,QAAQ,EAAE,CAAC,CAAC;QAC5D,CAAC;QAED,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IACxD,CAAC;IAED;;;;;;;;;OASG;IACI,KAAK,CAAC,MAAM,CAAC,QAAgB,EAAE,KAAc,EAAE,QAAiB;QACrE,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC;QAEvE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,gBAAgB,CAAC,wBAAwB,QAAQ,mBAAmB,SAAS,EAAE,CAAC,CAAC;QAC7F,CAAC;QAED,OAAO,MAAM,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC1D,CAAC;IAEM,KAAK,CAAC,YAAY,CAAC,QAAgB,EAAE,KAAc,EAAE,QAAgB,EAAE,QAAiB;QAC7F,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC;QAEvE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,gBAAgB,CAAC,wBAAwB,QAAQ,mBAAmB,SAAS,EAAE,CAAC,CAAC;QAC7F,CAAC;QAED,OAAO,MAAM,QAAQ,CAAC,YAAY,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC1E,CAAC;CACF,CAAA;AApEW;IADT,MAAM,CAAC,WAAW,CAAC;8BACL,GAAG;sCAAC;AAGT;IADT,UAAU,CAAC,gBAAgB,CAAC;;4CACW;AAL7B,SAAS;IADrB,MAAM,CAAC,IAAI,CAAC;GACA,SAAS,CAsErB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/lib/mjs/interfaces.d.ts

@@ -1,21 +1,64 @@
 import { IMappableService } from '@spinajs/di';
 import { AsyncService } from '@spinajs/di';
 import { Log } from '@spinajs/log';
+import { IStat } from '@spinajs/fs';
+import { IRenderOptions } from './progress.js';
+/**
+ * How aggressively compiled templates are reused.
+ *
+ * cache      - compile once, reuse forever. Default.
+ * revalidate - stat() the source and recompile only when its change token differs.
+ * always     - recompile on every render.
+ */
+export type TemplateCacheMode = 'cache' | 'revalidate' | 'always';
+export interface ITemplateCacheEntry {
+    compiled: unknown;
+    /**
+     * Change token captured when this entry was compiled. Null when the mode does
+     * not track one, or when the source could not be stat-ed.
+     */
+    token: string | null;
+}
 export declare abstract class TemplateRenderer extends AsyncService implements IMappableService {
     protected Log: Log;
-    protected TemplatePaths: string[];
-    protected TemplateFiles: Map<string, string[]>;
+    protected ConfiguredCacheMode: TemplateCacheMode;
+    protected DevMode: boolean;
+    protected Cache: Map<string, ITemplateCacheEntry>;
     abstract get Type(): string;
     abstract get Extension(): string;
     get ServiceName(): string;
-    abstract render(templatePath: string, model: unknown, language?: string): Promise<string>;
-    abstract renderToFile(templatePath: string, model: unknown, filePath: string, language?: string): Promise<void>;
+    abstract render(templatePath: string, model: unknown, language?: string, options?: IRenderOptions): Promise<string>;
+    abstract renderToFile(templatePath: string, model: unknown, filePath: string, language?: string, options?: IRenderOptions): Promise<void>;
+    /**
+     * Explicit config wins; otherwise dev mode implies always-recompile.
+     */
+    protected get CacheMode(): TemplateCacheMode;
+    protected isUri(template: string): boolean;
+    /**
+     * Bare paths are normalized as before. URIs must be left alone - path.normalize
+     * would turn fs://name/x into fs:\name\x on windows and break URI parsing.
+     */
+    protected normalizeTemplate(template: string): string;
+    /**
+     * Template source as text. Bare paths read from local disk exactly as before -
+     * routing them through the default provider would re-resolve relative paths
+     * against its basePath and break existing callers.
+     */
+    protected resolveContent(template: string): Promise<string>;
+    /**
+     * A real local path. For renderers that cannot compile from a string (pug),
+     * remote sources are materialised to temp storage.
+     */
+    protected resolveLocalPath(template: string): Promise<string>;
+    /**
+     * Opaque token that changes when the source changes. Null means "cannot tell" -
+     * callers must then trust whatever they already have cached.
+     */
+    protected changeToken(template: string): Promise<string | null>;
+    protected tokenFromStat(s: IStat): string;
     /**
-     * Function used for precompiling templates at load time. Not all template engines can support it, leave it empty if so.
-     *
-     * @param templateName - template name
-     * @param path - template full path
+     * Compiled-template cache honouring CacheMode. `compile` runs only on a miss.
      */
-    protected abstract compile(templateName: string, path: string): Promise<void>;
+    protected withCache<T>(template: string, compile: () => Promise<T>): Promise<T>;
 }
 //# sourceMappingURL=interfaces.d.ts.map

package/lib/mjs/interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAU,GAAG,EAAE,MAAM,cAAc,CAAC;AAG3C,8BAAsB,gBAAiB,SAAQ,YAAa,YAAW,gBAAgB;IAErF,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC;IAGnB,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC;IAElC,SAAS,CAAC,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAA+B;IAE7E,aAAoB,IAAI,IAAI,MAAM,CAAC;IAEnC,aAAoB,SAAS,IAAI,MAAM,CAAC;IAExC,IAAW,WAAW,WAGrB;aAEe,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;aAChF,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEtH;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAC9E"}
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAU,GAAG,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAM,KAAK,EAAO,MAAM,aAAa,CAAC;AAG7C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,YAAY,GAAG,QAAQ,CAAC;AAElE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,8BAAsB,gBAAiB,SAAQ,YAAa,YAAW,gBAAgB;IAErF,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC;IAGnB,SAAS,CAAC,mBAAmB,EAAE,iBAAiB,CAAC;IAGjD,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC;IAE3B,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAA0C;IAE3F,aAAoB,IAAI,IAAI,MAAM,CAAC;IAEnC,aAAoB,SAAS,IAAI,MAAM,CAAC;IAExC,IAAW,WAAW,WAGrB;aAEe,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;aAC1G,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhJ;;OAEG;IACH,SAAS,KAAK,SAAS,IAAI,iBAAiB,CAM3C;IAED,SAAS,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI1C;;;OAGG;IACH,SAAS,CAAC,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIrD;;;;OAIG;cACa,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASjE;;;OAGG;cACa,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQnE;;;OAGG;cACa,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAcrE,SAAS,CAAC,aAAa,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM;IAQzC;;OAEG;cACa,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CA2BtF"}

package/lib/mjs/interfaces.js

@@ -7,25 +7,121 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { Config } from '@spinajs/configuration';
 import { AsyncService } from '@spinajs/di';
+import { Config } from '@spinajs/configuration';
 import { Logger, Log } from '@spinajs/log';
+import { fs, URI } from '@spinajs/fs';
+import { readFile, stat as localStat } from 'fs/promises';
+import { normalize } from 'path';
 export class TemplateRenderer extends AsyncService {
     constructor() {
         super(...arguments);
-        this.TemplateFiles = new Map();
+        this.Cache = new Map();
     }
     get ServiceName() {
         // we map this service by extension
         return this.Extension;
     }
+    /**
+     * Explicit config wins; otherwise dev mode implies always-recompile.
+     */
+    get CacheMode() {
+        if (this.ConfiguredCacheMode) {
+            return this.ConfiguredCacheMode;
+        }
+        return this.DevMode ? 'always' : 'cache';
+    }
+    isUri(template) {
+        return /^fs:\/\//.test(template);
+    }
+    /**
+     * Bare paths are normalized as before. URIs must be left alone - path.normalize
+     * would turn fs://name/x into fs:\name\x on windows and break URI parsing.
+     */
+    normalizeTemplate(template) {
+        return this.isUri(template) ? template : normalize(template);
+    }
+    /**
+     * Template source as text. Bare paths read from local disk exactly as before -
+     * routing them through the default provider would re-resolve relative paths
+     * against its basePath and break existing callers.
+     */
+    async resolveContent(template) {
+        if (!this.isUri(template)) {
+            return await readFile(template, 'utf-8');
+        }
+        const content = await fs.read(new URI(template), 'utf-8');
+        return Buffer.isBuffer(content) ? content.toString('utf-8') : content;
+    }
+    /**
+     * A real local path. For renderers that cannot compile from a string (pug),
+     * remote sources are materialised to temp storage.
+     */
+    async resolveLocalPath(template) {
+        if (!this.isUri(template)) {
+            return template;
+        }
+        return await fs.download(new URI(template));
+    }
+    /**
+     * Opaque token that changes when the source changes. Null means "cannot tell" -
+     * callers must then trust whatever they already have cached.
+     */
+    async changeToken(template) {
+        try {
+            if (this.isUri(template)) {
+                return this.tokenFromStat(await fs.stat(new URI(template)));
+            }
+            const s = await localStat(template);
+            return `${s.mtimeMs}|${s.size}`;
+        }
+        catch (err) {
+            this.Log.warn(`Cannot stat template ${template}, serving cached version. ${err}`);
+            return null;
+        }
+    }
+    tokenFromStat(s) {
+        if (s.Version) {
+            return s.Version;
+        }
+        return `${s.ModifiedTime?.toMillis() ?? 0}|${s.Size ?? 0}`;
+    }
+    /**
+     * Compiled-template cache honouring CacheMode. `compile` runs only on a miss.
+     */
+    async withCache(template, compile) {
+        const mode = this.CacheMode;
+        if (mode === 'always') {
+            return await compile();
+        }
+        const key = this.normalizeTemplate(template);
+        const entry = this.Cache.get(key);
+        let token = null;
+        if (mode === 'revalidate') {
+            token = await this.changeToken(template);
+            // null token => stat failed; prefer a stale entry over failing the render
+            if (entry && (token === null || token === entry.token)) {
+                return entry.compiled;
+            }
+        }
+        else if (entry) {
+            return entry.compiled;
+        }
+        const compiled = await compile();
+        this.Cache.set(key, { compiled, token });
+        return compiled;
+    }
 }
 __decorate([
     Logger('renderer'),
     __metadata("design:type", Log)
 ], TemplateRenderer.prototype, "Log", void 0);
 __decorate([
-    Config('system.dirs.templates', { defaultValue: [] }),
-    __metadata("design:type", Array)
-], TemplateRenderer.prototype, "TemplatePaths", void 0);
+    Config('templates.cache.mode'),
+    __metadata("design:type", String)
+], TemplateRenderer.prototype, "ConfiguredCacheMode", void 0);
+__decorate([
+    Config('configuration.isDevelopment', { defaultValue: false }),
+    __metadata("design:type", Boolean)
+], TemplateRenderer.prototype, "DevMode", void 0);
 //# sourceMappingURL=interfaces.js.map

package/lib/mjs/interfaces.js.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/interfaces.ts"],"names":[],"mappings":";;;;;;;;;AACA,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAG3C,MAAM,OAAgB,gBAAiB,SAAQ,YAAY;IAA3D;;QAOY,kBAAa,GAA0B,IAAI,GAAG,EAAoB,CAAC;IAqB/E,CAAC;IAfC,IAAW,WAAW;QACpB,mCAAmC;QACnC,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CAYF;AA1BW;IADT,MAAM,CAAC,UAAU,CAAC;8BACJ,GAAG;6CAAC;AAGT;IADT,MAAM,CAAC,uBAAuB,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;;uDACpB"}
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/interfaces.ts"],"names":[],"mappings":"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"}

package/lib/mjs/io.d.ts

@@ -0,0 +1,3 @@
+/** Ensure the parent directory of `filePath` exists, creating it recursively if needed. */
+export declare function ensureParentDir(filePath: string): void;
+//# sourceMappingURL=io.d.ts.map

package/lib/mjs/io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../src/io.ts"],"names":[],"mappings":"AAGA,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAKtD"}

package/lib/mjs/io.js

@@ -0,0 +1,10 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/** Ensure the parent directory of `filePath` exists, creating it recursively if needed. */
+export function ensureParentDir(filePath) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+//# sourceMappingURL=io.js.map

package/lib/mjs/io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.js","sourceRoot":"","sources":["../../src/io.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,2FAA2F;AAC3F,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;AACH,CAAC"}

package/lib/mjs/progress.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Milestones a (puppeteer) render passes through. Text engines complete
+ * synchronously and do not report phases.
+ */
+export declare enum RenderPhase {
+    /** Local static server + pooled browser + page are being set up. */
+    Starting = "starting",
+    /** HTML is being built (template compiled / raw HTML injected) - before load. */
+    Preparing = "preparing",
+    /** Page content is loading - external resources (images, css, fonts) downloading. */
+    Loading = "loading",
+    /** The output is being produced (page.pdf() / screenshot). */
+    Rendering = "rendering",
+    /** Render finished successfully. */
+    Done = "done",
+    /** Render failed - `message` carries the reason. */
+    Failed = "failed"
+}
+/**
+ * A single progress snapshot delivered to a {@link RenderProgressCallback}.
+ * Resource counters are meaningful only for network-backed engines (puppeteer);
+ * they stay at 0 otherwise.
+ */
+export interface IRenderProgress {
+    /** Current render phase. */
+    phase: RenderPhase;
+    /** Best-effort completion, 0..100, weighted per phase. */
+    percent: number;
+    /** Resources whose response completed since loading started. */
+    resourcesLoaded: number;
+    /** Resources requested but not yet finished or failed. */
+    resourcesPending: number;
+    /** Resources that failed to load (e.g. broken images). */
+    resourcesFailed: number;
+    /** Milliseconds elapsed since the render started. */
+    elapsedMs: number;
+    /** Output file being produced. */
+    filePath: string;
+    /** Short human-readable status line. */
+    message?: string;
+}
+/**
+ * Progress listener. Invoked fire-and-forget by the renderer - it is never
+ * awaited and any thrown error / rejected promise is swallowed, so a slow or
+ * faulty listener can neither stall nor break a render. Emissions are throttled.
+ */
+export type RenderProgressCallback = (progress: IRenderProgress) => void | Promise<void>;
+/**
+ * Optional per-render options threaded through the {@link TemplateRenderer}
+ * contract and the {@link Templates} facade. All fields are optional; engines
+ * that do not support a given field ignore it.
+ */
+export interface IRenderOptions {
+    /** Receives throttled progress updates during the render. */
+    onProgress?: RenderProgressCallback;
+}
+//# sourceMappingURL=progress.d.ts.map

package/lib/mjs/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../src/progress.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,oBAAY,WAAW;IACrB,oEAAoE;IACpE,QAAQ,aAAa;IACrB,iFAAiF;IACjF,SAAS,cAAc;IACvB,qFAAqF;IACrF,OAAO,YAAY;IACnB,8DAA8D;IAC9D,SAAS,cAAc;IACvB,oCAAoC;IACpC,IAAI,SAAS;IACb,oDAAoD;IACpD,MAAM,WAAW;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,KAAK,EAAE,WAAW,CAAC;IACnB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,eAAe,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,eAAe,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,QAAQ,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEzF;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,sBAAsB,CAAC;CACrC"}

package/lib/mjs/progress.js

@@ -0,0 +1,20 @@
+/**
+ * Milestones a (puppeteer) render passes through. Text engines complete
+ * synchronously and do not report phases.
+ */
+export var RenderPhase;
+(function (RenderPhase) {
+    /** Local static server + pooled browser + page are being set up. */
+    RenderPhase["Starting"] = "starting";
+    /** HTML is being built (template compiled / raw HTML injected) - before load. */
+    RenderPhase["Preparing"] = "preparing";
+    /** Page content is loading - external resources (images, css, fonts) downloading. */
+    RenderPhase["Loading"] = "loading";
+    /** The output is being produced (page.pdf() / screenshot). */
+    RenderPhase["Rendering"] = "rendering";
+    /** Render finished successfully. */
+    RenderPhase["Done"] = "done";
+    /** Render failed - `message` carries the reason. */
+    RenderPhase["Failed"] = "failed";
+})(RenderPhase || (RenderPhase = {}));
+//# sourceMappingURL=progress.js.map

package/lib/mjs/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../src/progress.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAN,IAAY,WAaX;AAbD,WAAY,WAAW;IACrB,oEAAoE;IACpE,oCAAqB,CAAA;IACrB,iFAAiF;IACjF,sCAAuB,CAAA;IACvB,qFAAqF;IACrF,kCAAmB,CAAA;IACnB,8DAA8D;IAC9D,sCAAuB,CAAA;IACvB,oCAAoC;IACpC,4BAAa,CAAA;IACb,oDAAoD;IACpD,gCAAiB,CAAA;AACnB,CAAC,EAbW,WAAW,KAAX,WAAW,QAatB"}