mikser-io 9.1.0 → 9.2.1

package/package.json

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

package/src/catalog.js

@@ -567,19 +567,38 @@ async function expandAndProject(entity, expand) {
     return { ...result, meta: projectMeta(result.meta) }
 }
 
+// Combine a caller's filter with an endpoint scope. A sift-shaped scope
+// becomes part of the query so sift-to-sql can push it down; a function scope
+// returns the filter untouched and is applied by the caller after the fetch.
+export function scopedFilter(filter, scope) {
+    if (!scope || typeof scope === 'function') return filter
+    const hasFilter = filter && Object.keys(filter).length > 0
+    return hasFilter ? { $and: [filter, scope] } : scope
+}
+
 export async function queryEntities({
     filter, sort, fields, skip, limit, expand, scope,
 } = {}) {
     const effectiveLimit = Math.min(100, Math.max(1, limit ?? 25))
     const effectiveSkip = Math.max(0, skip ?? 0)
 
-    recordQuery(filter)
+    // A sift-shaped `scope` is merged into the filter so it reaches
+    // findEntities, where sift-to-sql pushes what it can into the WHERE
+    // clause. A function `scope` cannot be translated and stays a post-fetch
+    // predicate — which means the query materializes every row the caller's
+    // own filter matched, including the ones the endpoint would then reject.
+    // For an endpoint whose filter is broad (or absent) that is the entire
+    // catalog, per request, and `limit` does not help: it is applied after
+    // this. Prefer the object form.
+    const scopePredicate = typeof scope === 'function' ? scope : null
+    const effectiveFilter = scopedFilter(filter, scope)
+
+    recordQuery(effectiveFilter)
 
     // Materialize via findEntities (which handles sqlite + shim
-    // dispatch + js fallback). scope is a JS predicate applied
-    // post-fetch.
-    let all = await findEntities(filter)
-    if (scope) all = all.filter(scope)
+    // dispatch + js fallback).
+    let all = await findEntities(effectiveFilter)
+    if (scopePredicate) all = all.filter(scopePredicate)
 
     const total = all.length
 

package/src/plugins/api.js

@@ -407,7 +407,28 @@ export function api(options = {}) {
                 : ['list']
             const allowedOps = new Set(ep.operations ?? defaultOps)
 
-            const query = typeof ep.query === 'function' ? ep.query : null
+            // The endpoint's scope. A sift filter is the form to prefer —
+            // queryEntities merges it into the WHERE clause, so the endpoint
+            // never materializes rows it would only reject. A function still
+            // works and is applied post-fetch, which costs every row the
+            // caller's filter matched.
+            const query = (typeof ep.query === 'function' || (ep.query && typeof ep.query === 'object'))
+                ? ep.query
+                : null
+
+            // The same scope as a PREDICATE. Two paths hold one entity in
+            // hand and have no query to push a filter into — admitting a
+            // POST /render body, and the graph-subscription filter — so
+            // they have to test it directly. Calling `query` there works
+            // only while the scope is a function; the sift-object form
+            // this endpoint now accepts is not callable, and the failure
+            // is a bare `query is not a function` surfacing from whichever
+            // route touched it first.
+            const matchesScope = typeof ep.query === 'function'
+                ? ep.query
+                : query
+                    ? sift(query)
+                    : null
             const pageSize = ep.pageSize ?? globalPageSize
             const renderTimeout = ep.renderTimeout ?? globalRenderTimeout
 
@@ -607,7 +628,7 @@ export function api(options = {}) {
                                 : null
                             const handle = runtime.refs.subscribeGraph({
                                 filter: (entity) => {
-                                    if (query && !query(entity)) return false
+                                    if (matchesScope && !matchesScope(entity)) return false
                                     if (requestFilter && !requestFilter(entity)) return false
                                     return true
                                 },
@@ -638,7 +659,10 @@ export function api(options = {}) {
                     // is a 500. Same shape used by the POST handler below.
                     const status = err instanceof ExpandError ? err.status : 500
                     if (status >= 500) {
-                        logger.error('Api[%s] list error (%dms): %s', name, Date.now() - t0, err.message)
+                        logger.error(
+                            'Api[%s] list error (%dms): %s\n%s',
+                            name, Date.now() - t0, err.message, err.stack || '(no stack)',
+                        )
                     } else {
                         logger.debug('Api[%s] list rejected (%dms): %s', name, Date.now() - t0, err.message)
                     }
@@ -796,6 +820,10 @@ export function api(options = {}) {
             })
 
             router.post('/render', allow('render'), auth, async (req, res) => {
+                // Hoisted so the catch can name WHICH entity failed. A
+                // render that throws before this is assigned is itself the
+                // finding — it means the body never parsed.
+                let renderId
                 try {
                     // Body shape mirrors the JS API: entity fields at top
                     // level, control flags grouped under `options`. Forwarded
@@ -806,19 +834,42 @@ export function api(options = {}) {
                     //   options.save:    false → skip the final disk write
                     //                            (bytes still in the response)
                     const { options = {}, ...entityShape } = req.body
+                    renderId = entityShape.id
                     // When the endpoint declares a scope, reject anything
                     // outside it BEFORE pushing through the renderer.
-                    if (query && !query(entityShape)) {
+                    if (matchesScope && !matchesScope(entityShape)) {
                         return res.status(403).json({ error: 'Entity is outside this endpoint\'s scope' })
                     }
                     const { output, entity } = await render(entityShape, options)
                     await sendRenderOutput(res, output, entity)
                 } catch (err) {
-                    logger.error('Api[%s] render error: %s', name, err.message)
+                    // useRenderer tags an unrenderable entity (no layout)
+                    // with err.status = 422; everything else is a 500.
+                    const status = err.status ?? 500
+                    if (status >= 500) {
+                        // The stack, not just the message — and this is the
+                        // one route where that is not optional. A render
+                        // reaches here through a renderer, a postprocessor
+                        // chain and any template helper they call, so the
+                        // message is routinely a bare TypeError from a frame
+                        // the operator cannot name. Logging `{error: message}`
+                        // alone leaves bisecting deployed versions as the only
+                        // way to find out where it came from, which is exactly
+                        // as expensive as it sounds. The id says which entity;
+                        // `undefined` there means the body never parsed.
+                        logger.error(
+                            'Api[%s] render error for %s: %s\n%s',
+                            name, renderId ?? '(no id in body)', err.message,
+                            err.stack || '(no stack)',
+                        )
+                    } else {
+                        logger.debug(
+                            'Api[%s] render rejected for %s (%d): %s',
+                            name, renderId ?? '(no id in body)', status, err.message,
+                        )
+                    }
                     if (!res.headersSent) {
-                        // useRenderer tags an unrenderable entity (no layout)
-                        // with err.status = 422; everything else is a 500.
-                        res.status(err.status ?? 500).json({ error: err.message })
+                        res.status(status).json({ error: err.message })
                     }
                 }
             })

package/src/render.js

@@ -376,7 +376,10 @@ export function useRenderer(runtime, { defaultTimeout = 30_000 } = {}) {
      * - `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.
+     *   accumulate. Requires `save: false` — the prune goes through the
+     *   journal, and a DELETE takes the manifest's file cleanup with it,
+     *   so it is only safe for a render that wrote nothing. With
+     *   `save: true` the row is kept and a warning is logged.
      * - `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
@@ -439,18 +442,24 @@ export function useRenderer(runtime, { defaultTimeout = 30_000 } = {}) {
         })
 
         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 the manifest module's 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)
+            // Prune the row through the journal, so the DELETE lands in
+            // sqlite at onPersist alongside the CREATE that put it there.
+            // Strict equality — null / "false" / 0 keep the row.
+            //
+            // Only when `save` is also false. A DELETE carries the
+            // manifest's file cleanup with it, which unlinks the render's
+            // output; that is correct for an entity that produced no file
+            // and wrong for one that did. `catalog: false, save: true`
+            // therefore keeps its row, and says so rather than dropping
+            // the output on the floor.
+            if (save === false) {
+                await runtime.delete(result.entity)
+            } else {
+                useLogger()?.warn(
+                    'render: catalog:false ignored for %s — it needs save:false, ' +
+                    'because pruning the row also unlinks the rendered output',
+                    result.entity.id,
+                )
             }
         }