mikser-io 6.12.0 → 6.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mikser-io",
-	"version": "6.12.0",
+	"version": "6.15.0",
 	"description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
 	"main": "index.js",
 	"scripts": {

package/src/api.js

@@ -87,24 +87,41 @@ export function useRenderer(runtime, { defaultTimeout = 30_000 } = {}) {
      * `runtime.process()` cycle — within that cycle, mikser's worker pool
      * renders the batch in parallel.
      *
-     * By default the entity is **not** kept in the catalog: after the
-     * render resolves, the catalog row is pruned so it doesn't accumulate.
-     * The rendered output file is always kept on disk — the bytes are the
-     * work product. Pass `catalog: true` to also keep the catalog row,
-     * useful if you'll re-render the same entity later or query it via
-     * `findEntities`.
+     * Two control flags mirror mikser's default-keep-everything behavior;
+     * both opt-out via strict `=== false`:
+     *
+     * - `catalog: true` (default) — keep the entity in the catalog after
+     *   the render. Pass `catalog: false` to prune the catalog row;
+     *   useful for on-demand renders where the metadata row would just
+     *   accumulate.
+     * - `save: true` (default) — write the rendered output to disk at
+     *   `<outputFolder>/<entity.destination>`. Pass `save: false` to
+     *   skip the final disk write; the bytes still come back via
+     *   `output.result` for you to pipe wherever you want (HTTP
+     *   response, S3, …). For layouts with a postprocessor (e.g.
+     *   `*.html-pdf.*`), the intermediate file is still written so the
+     *   postprocessor can consume it; only the FINAL output is skipped.
+     *
+     * The rendered output's bytes are always returned in `output.result`
+     * regardless of either flag — `save` only affects whether they also
+     * end up on disk.
      *
      * @param {object} entity                - any entity-shaped object
      * @param {object} [opts]
      * @param {number}  [opts.timeout]       - override the default timeout
-     * @param {boolean} [opts.catalog=false] - keep the catalog row after render
+     * @param {boolean} [opts.catalog=true]  - keep the catalog row after render
+     * @param {boolean} [opts.save=true]     - write the rendered output to disk
      * @returns {Promise<{output, entity}>}
      */
-    async function render(entity, { timeout = defaultTimeout, catalog = false } = {}) {
+    async function render(entity, { timeout = defaultTimeout, catalog = true, save = true } = {}) {
         const result = await new Promise((resolve, reject) => {
             const correlationId = randomUUID()
+            const stamped = { ...entity, _correlationId: correlationId }
+            // Only stamp _save when explicitly opting out — keeps the
+            // entity object clean for the common case.
+            if (save === false) stamped._save = false
             pending.push({
-                entity: { ...entity, _correlationId: correlationId },
+                entity: stamped,
                 correlationId,
                 timeout,
                 resolve,
@@ -114,13 +131,15 @@ export function useRenderer(runtime, { defaultTimeout = 30_000 } = {}) {
             if (!cycleRunning) setImmediate(runBatch)
         })
 
-        if (!catalog) {
-            // Prune the catalog row so it doesn't accumulate, but LEAVE
-            // the rendered output file on disk — the bytes are the work
-            // product. We deliberately bypass the journal/DELETE path
-            // here (which would also unlink the file via engine.js's
-            // manifest cleanup) and splice the entity out of the
-            // in-memory catalog directly.
+        if (catalog === false) {
+            // Explicit opt-out: prune the catalog row so it doesn't
+            // accumulate. The rendered output file stays on disk — the
+            // bytes are the work product. We deliberately bypass the
+            // journal/DELETE path here (which would also unlink the file
+            // via engine.js's manifest cleanup) and splice the entity
+            // out of the in-memory catalog directly. Strict equality so
+            // ambiguous inputs (null, "false", 0) fall through to the
+            // default of keeping the row.
             const entities = runtime.catalog?.data?.entities
             if (entities) {
                 const idx = entities.findIndex(e => e.id === result.entity.id)

package/src/plugins/api.js

@@ -148,13 +148,16 @@ export default ({
 
         router.post('/render', auth, async (req, res) => {
             try {
-                // Pull `catalog` out as a control flag; everything else
-                // is treated as the entity. Default is NOT to keep the
-                // catalog row (the rendered output stays on disk either
-                // way). Send `catalog: true` to keep the row, e.g. if
-                // you'll re-render or query the entity later.
-                const { catalog, ...entityShape } = req.body
-                const { output, entity } = await render(entityShape, { catalog })
+                // Body shape mirrors the JS API: entity fields at top
+                // level, control flags grouped under `options`. Forwarded
+                // straight to render(entity, options). Defaults match
+                // mikser's lifecycle (save and keep the catalog row);
+                // strict opt-outs via the literal `false`:
+                //   options.catalog: false → prune the catalog row
+                //   options.save:    false → skip the final disk write
+                //                            (bytes still in the response)
+                const { options = {}, ...entityShape } = req.body
+                const { output, entity } = await render(entityShape, options)
                 await sendRenderOutput(res, output, entity)
             } catch (err) {
                 logger.error('Api render error: %s', err.message)

package/src/plugins/layouts.js

@@ -370,13 +370,32 @@ export default ({
     onComplete(async ({ entity, options, output }) => {
         const logger = useLogger()
         if (entity.layout && !options?.ignore && output.result != null) {
-            const destinationFile = path.join(runtime.options.outputFolder, entity.destination)
-            await mkdir(path.dirname(destinationFile), { recursive: true })
-            try {
-                await unlink(destinationFile)
-            } catch { }
-            await writeFile(destinationFile, output.result)
-            logger.debug('Layout render finished: %s', entity.destination.replace(runtime.options.workingFolder, ''))
+            // `_save: false` (stamped by useRenderer when called with
+            // { save: false }) opts out of writing the final output to
+            // disk. The bytes still come back to the caller via
+            // output.result. Strict equality — only the literal `false`
+            // opts out, matching the catalog-flag pattern.
+            //
+            // The intermediate file (when a postprocessor will run next)
+            // must still be written so the postprocessor can consume it,
+            // so we only honour `_save: false` for the FINAL output —
+            // detected as either "no postprocessor configured" or "we're
+            // running on the postprocess side already" (origin set).
+            const isFinal = !entity.layout.postprocessor || entity.origin != null
+            const skipWrite = entity._save === false && isFinal
+
+            if (!skipWrite) {
+                const destinationFile = path.join(runtime.options.outputFolder, entity.destination)
+                await mkdir(path.dirname(destinationFile), { recursive: true })
+                try {
+                    await unlink(destinationFile)
+                } catch { }
+                await writeFile(destinationFile, output.result)
+                logger.debug('Layout render finished: %s', entity.destination.replace(runtime.options.workingFolder, ''))
+            } else {
+                logger.debug('Layout render finished (save:false, bytes only): %s', entity.id)
+            }
+
             if (entity.origin && entity.origin !== entity.destination) {
                 // Don't unlink the origin if it was the same path we just
                 // wrote to (post plugins that produce the same extension as