mikser-io 6.12.0 → 6.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mikser-io",
-	"version": "6.12.0",
+	"version": "6.17.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/data.js

@@ -36,9 +36,18 @@ export default ({
             }
         }
         for (let entitiesName in entitiesConfig) {
+            // Per-config namespacing token. When set, this entity-writer's
+            // files land under <dataFolder>/<token>/ instead of straight
+            // in <dataFolder>. Each named entity config can declare its
+            // own token, so they can target different namespaces (useful
+            // for multi-tenant exports into shared storage).
+            const token = entitiesConfig[entitiesName].token
+            const targetFolder = token
+                ? path.join(runtime.options.dataFolder, token)
+                : runtime.options.dataFolder
             const {
                 query,
-                map,
+                map: mapEntity = entity => entity,
                 pick,
                 save: saveEntity = async entity => {
                     if (!entity.name) {
@@ -46,12 +55,12 @@ export default ({
                         return
                     }
                     const dump = JSON.stringify(normalize(entity))
-                    const entityFile = path.join(runtime.options.dataFolder, `${entity.name}.${entitiesName}.json`)
+                    const entityFile = path.join(targetFolder, `${entity.name}.${entitiesName}.json`)
                     await mkdir(path.dirname(entityFile), { recursive: true })
                     await writeFile(entityFile, dump, 'utf8')
                 },
                 delete: deleteEntity = async entity => {
-                    const entityFile = path.join(runtime.options.dataFolder, `${entity.name}.json`)
+                    const entityFile = path.join(targetFolder, `${entity.name}.json`)
                     await unlink(entityFile)
                 }
             } = entitiesConfig[entitiesName]
@@ -62,12 +71,12 @@ export default ({
                         case OPERATION.CREATE:
                         case OPERATION.UPDATE:
                             logger.debug('Data export entity %s %s: %s', entity.collection, operation, entity.id)
-                            await saveEntity(map ? await map(entity) : {
+                            await saveEntity(({
                                 refId: ('/' + entity.name.replaceAll('\\', '/')).replace(/\/index$/g, '/'),
                                 name: entity.name,
                                 date: new Date(entity.time),
-                                data: _.pick(entity, pick || ['collection', 'format', 'type', 'destination', 'stamp', 'meta', 'id',])
-                            })
+                                data: _.pick(await mapEntity(entity), pick || ['collection', 'format', 'type', 'destination', 'stamp', 'meta', 'id',])
+                            }))
                             break
                         case OPERATION.DELETE:
                             await deleteEntity(entity)
@@ -90,14 +99,19 @@ export default ({
             }
         }
         for (let contextName in contextConfig) {
+            // Per-config namespacing token — see the entities loop above.
+            const token = contextConfig[contextName].token
+            const targetFolder = token
+                ? path.join(runtime.options.dataFolder, token)
+                : runtime.options.dataFolder
             const {
                 query,
-                map,
+                map: mapEntityContext = (entity, context) => context,
                 pick,
                 save: saveConext = async (entity, context) => {
                     if (context?.data) {
                         const entityName = entity.name
-                        const contextFile = path.join(runtime.options.dataFolder, `${entityName}.${contextName}.json`)
+                        const contextFile = path.join(targetFolder, `${entityName}.${contextName}.json`)
                         await mkdir(path.dirname(contextFile), { recursive: true })
                         await writeFile(contextFile, JSON.stringify(context), 'utf8')
                     }
@@ -107,7 +121,7 @@ export default ({
             for await (let { entity, context } of useJournal('Data context', [OPERATION.RENDER])) {
                 if (query(entity)) {
                     logger.debug('Data export context: %s', entity.name)
-                    await saveConext(entity, map ? await map(entity, context) : _.pick(context, pick || ['data']))
+                    await saveConext(entity, _.pick(await mapEntityContext(entity, context), pick || ['data']))
                 }
             }
         }
@@ -116,23 +130,29 @@ export default ({
     onFinalize(async () => {
         const logger = useLogger()
         for (let catalogName in runtime.config.data?.catalog || {}) {
+            // Per-config namespacing token — see the entities loop above.
+            const token = runtime.config.data?.catalog[catalogName].token
+            const targetFolder = token
+                ? path.join(runtime.options.dataFolder, token)
+                : runtime.options.dataFolder
             const {
                 query: queryEntities = entity => entity.type == 'document',
-                map,
+                map: mapEntity = entity => entity,
                 pick,
                 save: saveEntities = async entities => {
-                    const entitiesFile = path.join(runtime.options.dataFolder, `${catalogName}.json`)
+                    const entitiesFile = path.join(targetFolder, `${catalogName}.json`)
+                    await mkdir(path.dirname(entitiesFile), { recursive: true })
                     logger.debug('Data export catalog %s %s: %s', catalogName, entities.length, entitiesFile)
                     await writeFile(entitiesFile, JSON.stringify(entities), 'utf8')
                 }
             } = runtime.config.data?.catalog[catalogName]
             const entities = await findEntities(queryEntities)
-            await saveEntities(await pMap(entities, async entity => map ? await map(entity) : {
+            await saveEntities(await pMap(entities, async entity => ({
                 refId: ('/' + entity.name.replaceAll('\\', '/')).replace(/\/index$/g, '/'),
                 name: entity.name,
                 date: new Date(entity.time),
-                data: _.pick(entity, pick || ['collection', 'format', 'type', 'destination', 'stamp', 'meta', 'id',])
-            }))
+                data: _.pick(await mapEntity(entity), pick || ['collection', 'format', 'type', 'destination', 'stamp', 'meta', 'id',])
+            })))
         }
     })
 }

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/plugins/resources.js

@@ -24,6 +24,7 @@ export default ({
     trackProgress,
     updateProgress,
     updateEntry,
+    matchEntity,
     constants: { OPERATION },
 }) => {
     const collection = 'resources'
@@ -65,8 +66,7 @@ export default ({
                 _.eachDeep(entity.meta, resource => {
                     if (typeof resource == 'string') {
                         for (let library in resourceLib) {
-                            const match = new RegExp(library)
-                            if (resource.match(match)) {
+                            if (matchEntity(resource, library)) {
                                 resourceMap[entity.id].push({ library, resource, entity })
                             }
                         }

package/src/utils.js

@@ -49,9 +49,9 @@ export function matchEntity(entity, match) {
     if (typeof match == 'function') return match(entity)
     else if (typeof match == 'string') {
         if (match.substring(0, 2) == '@/') {
-            return minimatch(entity.name, match.substring(2))
+            return minimatch(typeof entity == 'string' ? entity : entity.name, match.substring(2))
         } else {
-            return minimatch(entity.id, match)
+            return minimatch(typeof entity == 'string' ? entity : entity.id, match)
         }
     }
     else if (typeof match == 'object') return _.isMatch(entity, match)