mikser-io 6.9.4 → 6.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mikser-io",
-	"version": "6.9.4",
+	"version": "6.15.0",
 	"description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
 	"main": "index.js",
 	"scripts": {
@@ -57,6 +57,7 @@
 	"devDependencies": {
 		"fluent-ffmpeg": "^2.1.3",
 		"mikser-io-post-mjml": "file:../mikser-io-post-mjml",
+		"mikser-io-render-eta": "file:../mikser-io-render-eta",
 		"mikser-io-render-liquid": "file:../mikser-io-render-liquid",
 		"mikser-io-render-markdown": "file:../mikser-io-render-markdown",
 		"sharp": "^0.34.5"

package/src/api.js

@@ -5,7 +5,7 @@
 import { randomUUID } from 'node:crypto'
 import { writeFile, unlink, mkdir } from 'node:fs/promises'
 import path from 'node:path'
-import { updateEntity as defaultUpdateEntity } from './lifecycle.js'
+import './lifecycle.js' // side-effect: attaches runtime.create / update / delete
 
 /**
  * Bind to the runtime and return an on-demand renderer that pipelines
@@ -20,14 +20,10 @@ import { updateEntity as defaultUpdateEntity } from './lifecycle.js'
  *
  * @param {object} runtime                  - the mikser runtime singleton
  * @param {object} [opts]
- * @param {Function} [opts.updateEntity]    - override lifecycle.updateEntity (mostly for testing)
- * @param {number}   [opts.defaultTimeout]  - per-render timeout in ms (default 30_000)
+ * @param {number} [opts.defaultTimeout]    - per-render timeout in ms (default 30_000)
  * @returns {{ render: (entity, { timeout? }?) => Promise<{ output, entity }> }}
  */
-export function useRenderer(runtime, {
-    updateEntity = defaultUpdateEntity,
-    defaultTimeout = 30_000,
-} = {}) {
+export function useRenderer(runtime, { defaultTimeout = 30_000 } = {}) {
     let pending = []
     let cycleRunning = false
 
@@ -61,7 +57,7 @@ export function useRenderer(runtime, {
 
         try {
             for (const item of batch) {
-                await updateEntity(item.entity).catch(item.reject)
+                await runtime.update(item.entity).catch(item.reject)
             }
             await runtime.process()
         } catch (err) {
@@ -91,16 +87,41 @@ export function useRenderer(runtime, {
      * `runtime.process()` cycle — within that cycle, mikser's worker pool
      * renders the batch in parallel.
      *
+     * 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 {number}  [opts.timeout]       - override the default timeout
+     * @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}>}
      */
-    function render(entity, { timeout = defaultTimeout } = {}) {
-        return new Promise((resolve, reject) => {
+    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,
@@ -109,6 +130,24 @@ export function useRenderer(runtime, {
             })
             if (!cycleRunning) setImmediate(runBatch)
         })
+
+        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)
+                if (idx >= 0) entities.splice(idx, 1)
+            }
+        }
+
+        return result
     }
 
     return { render }

package/src/journal.js

@@ -69,7 +69,13 @@ export async function* useJournal(name, operations, signal) {
 export async function clearJournal(aborted) {
     await journal('operations').del()
     if (!aborted) {
-        if (runtime.options.watch !== true) {
+        // Tear down the sqlite connection only when this is genuinely a
+        // one-shot run that's about to exit. Watch mode and any plugin
+        // that keeps the process alive (e.g. the API plugin's HTTP server)
+        // sets `persistent` so subsequent cycles can still write to the
+        // journal — without this, the second /render request would crash
+        // with "Unable to acquire a connection".
+        if (runtime.options.watch !== true && runtime.options.persistent !== true) {
             journal.destroy()
         }
     }

package/src/lifecycle.js

@@ -34,6 +34,15 @@ export async function updateEntity(entity) {
     }
 }
 
+// Expose the three entity operations as methods on the runtime so library
+// code (useRenderer, custom plugins) can call `runtime.update(entity)`
+// instead of importing and threading the standalone functions. The
+// imports above already pulled the runtime singleton into scope; this is
+// just a single assignment per name.
+runtime.create = createEntity
+runtime.update = updateEntity
+runtime.delete = deleteEntity
+
 export async function postprocessEntity(entity, options = {}, context = {}) {
     const logger = useLogger()
     const entry = { operation: OPERATION.POSTPROCESS, entity, options, context }

package/src/plugins/api.js

@@ -68,7 +68,6 @@ export default ({
     runtime,
     onLoaded,
     useLogger,
-    updateEntity,
     findEntities,
 }) => {
     onLoaded(async () => {
@@ -95,7 +94,6 @@ export default ({
         // library entry point and the Api endpoints share the exact same
         // batching/timeouts/error semantics.
         const { render } = useRenderer(runtime, {
-            updateEntity,
             defaultTimeout: runtime.config.api?.renderTimeout ?? 30_000,
         })
 
@@ -150,7 +148,16 @@ export default ({
 
         router.post('/render', auth, async (req, res) => {
             try {
-                const { output, entity } = await render(req.body)
+                // 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)
@@ -160,6 +167,11 @@ export default ({
             }
         })
 
+        // The HTTP server keeps the process alive across many process()
+        // cycles. Tell the journal layer not to tear down the sqlite
+        // connection at the end of each cycle.
+        runtime.options.persistent = true
+
         const base = runtime.config.api?.base ?? '/api'
         app.use(base, router)
 

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

package/src/tracking.js

@@ -55,7 +55,7 @@ export function stopProgress() {
         logger.warn('%s unfinished: %d', name, total - value)
     } else {
         const time = Math.round((Date.now() - progress.stamp) / 1000)
-        logger.info('%s: %s', name, formatTime(time, { autopaddingChar: '' }))
+        logger.info('%s finished: %d %s', name, total, formatTime(time, { autopaddingChar: '' }))
     }
     progress = {}
 }