@zero-server/sdk 1.0.2 → 1.1.0

package/README.md

@@ -5,18 +5,18 @@
 <h1 align="center">zero-server</h1>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@zero-server/sdk"><img src="https://img.shields.io/badge/%40zero--server%2Fsdk-000?style=flat-square&logo=npm&logoColor=white" alt="@zero-server/sdk"></a>
-  <a href="https://www.npmjs.com/package/@zero-server/sdk"><img src="https://img.shields.io/npm/v/%40zero-server%2Fsdk?style=flat-square&logo=npm&logoColor=white&label=&color=00d8e0" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/@zero-server/sdk"><img src="https://img.shields.io/npm/dm/%40zero-server%2Fsdk?style=flat-square&logo=npm&logoColor=white&label=downloads&color=ff6b35" alt="npm downloads"></a>
+  <a href="https://www.npmjs.com/package/@zero-server/sdk"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-server-sdk-name-zserver.svg?v=18d4e9a4" alt="@zero-server/sdk"></a>
+  <a href="https://www.npmjs.com/package/@zero-server/sdk"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-server-npm-zserver.svg?v=f9009a13" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@zero-server/sdk"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-server-dm-zserver.svg?v=1d29d0dd" alt="npm downloads"></a>
 </p>
 
 <p align="center">
-  <a href="https://github.com/tonywied17/zero-server/actions"><img src="https://img.shields.io/github/actions/workflow/status/tonywied17/zero-server/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=CI" alt="CI"></a>
-  <a href="https://github.com/tonywied17/zero-server/actions"><img src="https://img.shields.io/badge/tests-8016%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white" alt="tests"></a>
-  <a href="https://github.com/tonywied17/zero-server"><img src="https://img.shields.io/badge/coverage-95.84%25-brightgreen?style=flat-square&logo=vitest&logoColor=white" alt="coverage"></a>
-  <a href="https://z-server.dev"><img src="https://img.shields.io/badge/docs-z--server.dev-00d8e0?style=flat-square&logo=readthedocs&logoColor=white" alt="docs"></a>
-  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-00d8e0?style=flat-square&logo=opensourceinitiative&logoColor=white" alt="MIT"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square&logo=nodedotjs&logoColor=white" alt="node >=18"></a>
+  <a href="https://github.com/tonywied17/zero-server/actions/workflows/ci.yml"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-server-ci-zserver.svg?v=f09fb8a3" alt="CI"></a>
+  <a href="https://github.com/tonywied17/zero-server/actions"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-server-tests-zserver.svg?v=3a8e5d37" alt="tests"></a>
+  <a href="https://github.com/tonywied17/zero-server"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-server-coverage-zserver.svg?v=fdecde38" alt="coverage"></a>
+  <a href="https://z-server.dev"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-server-docs-zserver.svg?v=00dc1cc0" alt="docs"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-server-license-zserver.svg?v=92c4db7f" alt="license"></a>
+  <a href="https://nodejs.org"><img src="https://raw.githubusercontent.com/tonywied17/tonywied17/main/.github/badges/zero-server-node-zserver.svg?v=c0f8c528" alt="node >=18"></a>
 </p>
 
 > **Zero-dependency backend framework for Node.js - routing, ORM, auth, WebSocket, SSE, observability, and 20+ middleware as one SDK or focused scoped packages.**

package/lib/app.js

@@ -172,6 +172,24 @@ class App
      *   before calling `fn` so downstream sees relative paths).
      * - `use('/prefix', router)` - mount a Router sub-app at the given prefix.
      *
+     * Route matching order: the app matches its OWN verb routes (those declared
+     * with `app.get()`, `app.post()`, etc.) BEFORE probing any `use()`-mounted
+     * child routers. An app-level catch-all like `app.get('/*', ssr)` therefore
+     * shadows every mounted router. Give a catch-all its own child router and
+     * mount it LAST so real routes win:
+     *
+     * @example | Catch-all that does not shadow mounted routers
+     *   const { createApp, Router } = require('@zero-server/sdk');
+     *   const app = createApp();
+     *
+     *   const api = Router();
+     *   api.get('/users', listUsers);
+     *   app.use('/api', api);            // real routes
+     *
+     *   const ssr = Router();
+     *   ssr.get('/*', renderApp);        // SPA / SSR fallback
+     *   app.use('/', ssr);               // mounted LAST - only handles what /api did not
+     *
      * @param {string|Function}       pathOrFn - A path prefix string, or middleware function.
      * @param {Function|Router}       [fn]     - Middleware function or Router when first arg is a path.
      */

package/lib/fetch/index.js

@@ -10,13 +10,24 @@ const { URL } = require('url');
 
 const STATUS_CODES = http.STATUS_CODES;
 
+/**
+ * Default `User-Agent` sent when a request does not specify one.
+ * Many APIs (e.g. GitHub) reject requests without a User-Agent, so a sensible
+ * default avoids surprising 403s. Override per request via `opts.headers`.
+ * @private
+ */
+let DEFAULT_USER_AGENT;
+try { DEFAULT_USER_AGENT = `zero-server/${require('../../package.json').version}`; }
+catch (e) { DEFAULT_USER_AGENT = 'zero-server'; }
+
 /**
  * Perform an HTTP(S) request.
  *
  * @param {string} url  - Absolute URL to fetch.
  * @param {object} [opts] - Configuration options.
  * @param {string}   [opts.method='GET']           - HTTP method.
- * @param {object}   [opts.headers]                - Request headers.
+ * @param {object}   [opts.headers]                - Request headers. A default
+ *        `User-Agent` of `zero-server/<version>` is sent unless one is provided here.
  * @param {string|Buffer|object|ReadableStream} [opts.body] - Request body.
  * @param {number}   [opts.timeout]                - Request timeout in ms.
  * @param {AbortSignal} [opts.signal]              - Abort signal for cancellation.
@@ -59,6 +70,12 @@ function miniFetch(url, opts = {})
             const method = (opts.method || 'GET').toUpperCase();
             const headers = Object.assign({}, opts.headers || {});
 
+            // Send a default User-Agent unless the caller supplied one (any case).
+            if (!Object.keys(headers).some(h => h.toLowerCase() === 'user-agent'))
+            {
+                headers['User-Agent'] = DEFAULT_USER_AGENT;
+            }
+
             // Normalize body
             let body = opts.body;
             if (body && typeof body === 'object' && typeof body.toString === 'function' && body.constructor && body.constructor.name === 'URLSearchParams')

package/lib/orm/adapters/sqlite.js

@@ -431,6 +431,27 @@ class SqliteAdapter extends BaseSqlAdapter
     {
         const { action, table, fields, where, orderBy, limit, offset, distinct, joins, groupBy, having } = descriptor;
 
+        // Raw SQL passthrough (e.g. AuditLog.install() issues DDL this way).
+        if (descriptor.raw)
+        {
+            const stmt = this._db.prepare(descriptor.raw);
+            return stmt.reader ? stmt.all(...(descriptor.params || [])) : stmt.run(...(descriptor.params || []));
+        }
+
+        // Row insert descriptor (e.g. AuditLog entry writes).
+        if (action === 'insert')
+        {
+            return this.insert(table, descriptor.data);
+        }
+
+        // Conditional delete descriptor (e.g. AuditLog.purge()).
+        if (action === 'delete')
+        {
+            const { clause, values } = this._buildWhereFromChain(where);
+            const result = this._prepare(`DELETE FROM "${table}"${clause}`).run(...values);
+            return result.changes;
+        }
+
         if (action === 'count')
         {
             const { clause, values } = this._buildWhereFromChain(where);

package/lib/orm/audit.js

@@ -465,7 +465,8 @@ class AuditLog
             action: 'find',
             table: this.tableName,
             where,
-            orderBy: [{ field: 'timestamp', direction: order }],
+            // Adapters read the canonical `dir` key ('ASC' | 'DESC').
+            orderBy: [{ field: 'timestamp', dir: String(order).toUpperCase() === 'ASC' ? 'ASC' : 'DESC' }],
             limit,
             offset,
         };

package/lib/router/index.js

@@ -75,6 +75,13 @@ class Router
         this.routes = [];
         /** @type {{ prefix: string, router: Router }[]} */
         this._children = [];
+        /**
+         * Router-level middleware. Each entry runs before the handlers of any
+         * matching route in this router (and in mounted child routers), in
+         * registration order.
+         * @type {{ prefix: string|null, handler: Function }[]}
+         */
+        this._middleware = [];
         /**
          * Parameter pre-processing handlers (set by parent App).
          * @type {Object<string, Function[]>}
@@ -104,23 +111,82 @@ class Router
     }
 
     /**
-     * Mount a child Router under a path prefix.
-     * Requests matching the prefix are delegated to the child router with
-     * the prefix stripped from `req.url`.
+     * Register router-level middleware or mount a child Router.
+     *
+     * Three forms are supported:
+     * - `use(fn, ...fns)` - middleware that runs before the handlers of every
+     *   matching route in this router (and its mounted children).
+     * - `use(prefix, fn, ...fns)` - middleware scoped to routes whose path is at
+     *   or below `prefix`.
+     * - `use(prefix, router)` - mount a child Router under a path prefix.
+     *   Requests matching the prefix are delegated to the child router with the
+     *   prefix stripped from `req.url`.
+     *
+     * Middleware runs as part of the matched route's handler chain, so it only
+     * executes when a route actually matches (a 404 runs no middleware). This
+     * makes it a natural fit for auth/feature guards. Unlike the earlier
+     * releases, passing a function is no longer silently ignored - an
+     * unsupported argument shape throws a `TypeError`.
      *
-     * @param {string} prefix - Path prefix (e.g. '/api').
-     * @param {Router} router - Child router instance.
+     * @param {string|Function} prefixOrFn - Path prefix, or a middleware function.
+     * @param {...(Function|Router)} rest  - A child `Router`, or one or more middleware functions.
      * @returns {Router} `this` for chaining.
+     * @throws {TypeError} When the argument shape is not one of the supported forms.
      */
-    use(prefix, router)
+    use(prefixOrFn, ...rest)
     {
-        if (typeof prefix === 'string' && router instanceof Router)
+        // use(prefix, router) - mount a child router
+        if (typeof prefixOrFn === 'string' && rest.length === 1 && rest[0] instanceof Router)
         {
-            const cleanPrefix = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
-            this._children.push({ prefix: cleanPrefix, router });
+            const cleanPrefix = prefixOrFn.endsWith('/') ? prefixOrFn.slice(0, -1) : prefixOrFn;
+            this._children.push({ prefix: cleanPrefix, router: rest[0] });
             log.debug('mounted child router at %s', cleanPrefix);
+            return this;
+        }
+
+        // use(fn, ...fns) - global router middleware
+        if (typeof prefixOrFn === 'function')
+        {
+            for (const fn of [prefixOrFn, ...rest])
+            {
+                if (typeof fn !== 'function')
+                    throw new TypeError('Router.use(): every middleware argument must be a function');
+                this._middleware.push({ prefix: null, handler: fn });
+            }
+            log.debug('registered %d router middleware', 1 + rest.length);
+            return this;
+        }
+
+        // use(prefix, fn, ...fns) - prefix-scoped router middleware
+        if (typeof prefixOrFn === 'string' && rest.length > 0 && rest.every(f => typeof f === 'function'))
+        {
+            const cleanPrefix = prefixOrFn.endsWith('/') ? prefixOrFn.slice(0, -1) : prefixOrFn;
+            for (const fn of rest) this._middleware.push({ prefix: cleanPrefix, handler: fn });
+            log.debug('registered %d router middleware at %s', rest.length, cleanPrefix);
+            return this;
+        }
+
+        throw new TypeError(
+            'Router.use() expects use(fn), use(prefix, fn), or use(prefix, router)'
+        );
+    }
+
+    /**
+     * Collect the router-level middleware whose scope matches a path.
+     * @param {string} url - Router-local request path (query already stripped).
+     * @returns {Function[]} Applicable middleware handlers in registration order.
+     * @private
+     */
+    _applicableMiddleware(url)
+    {
+        if (this._middleware.length === 0) return [];
+        const out = [];
+        for (const m of this._middleware)
+        {
+            if (m.prefix === null || url === m.prefix || url.startsWith(m.prefix + '/'))
+                out.push(m.handler);
         }
-        return this;
+        return out;
     }
 
     /**
@@ -159,15 +225,20 @@ class Router
      *
      * @param {import('./request')}  req - HTTP request object.
      * @param {import('./response')} res - HTTP response object.
+     * @param {Function[]} [inherited] - Middleware inherited from parent routers,
+     *        already resolved as applicable to this request.
      * @returns {boolean} Boolean result.
      * @private
      */
-    _matchAndExecute(req, res)
+    _matchAndExecute(req, res, inherited = [])
     {
         const method = req.method.toUpperCase();
         const url = req.url.split('?')[0];
         log.debug('%s %s', method, url);
 
+        // Middleware applicable at this router for the current path
+        const ownMiddleware = this._applicableMiddleware(url);
+
         // Try own routes first
         for (let ri = 0; ri < this.routes.length; ri++)
         {
@@ -248,8 +319,37 @@ class Router
                 }
             };
 
-            if (paramCount > 0) runParams();
-            else runHandlers();
+            // Middleware (inherited from parents, then this router's own) runs
+            // ahead of param handlers and route handlers. A middleware that
+            // sends a response without calling next() short-circuits the chain.
+            const middleware = inherited.length || ownMiddleware.length
+                ? [...inherited, ...ownMiddleware]
+                : null;
+            const startChain = () => (paramCount > 0 ? runParams() : runHandlers());
+
+            if (middleware)
+            {
+                let mIdx = 0;
+                const runMiddleware = () =>
+                {
+                    if (mIdx < middleware.length)
+                    {
+                        const fn = middleware[mIdx++];
+                        try
+                        {
+                            const result = fn(req, res, runMiddleware);
+                            if (result && typeof result.catch === 'function')
+                            {
+                                result.catch(e => this._handleRouteError(e, req, res));
+                            }
+                        }
+                        catch (e) { this._handleRouteError(e, req, res); }
+                    }
+                    else { startChain(); }
+                };
+                runMiddleware();
+            }
+            else { startChain(); }
             return true;
         }
 
@@ -262,11 +362,21 @@ class Router
                 const origUrl = req.url;
                 const origBaseUrl = req.baseUrl || '';
                 req.baseUrl = origBaseUrl + child.prefix;
-                req.url = req.url.slice(child.prefix.length) || '/';
+                // Keep the query string attached to a normalized path: a
+                // request for exactly the mount prefix plus a query
+                // ('/api/files?x=1') must delegate as '/?x=1', not '?x=1'.
+                const rest = req.url.slice(child.prefix.length);
+                req.url = rest === '' || rest.startsWith('?') ? '/' + rest : rest;
                 child.router._paramHandlers = this._paramHandlers;
+                // Carry this router's applicable middleware down so mounted
+                // routes are guarded too. Applicability is resolved here, against
+                // the parent-relative URL, before the prefix is stripped.
+                const childInherited = inherited.length || ownMiddleware.length
+                    ? [...inherited, ...ownMiddleware]
+                    : inherited;
                 try
                 {
-                    const found = child.router._matchAndExecute(req, res);
+                    const found = child.router._matchAndExecute(req, res, childInherited);
                     if (found) return true;
                 }
                 catch (e) { this._handleRouteError(e, req, res); return true; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zero-server/sdk",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Zero-dependency backend framework for Node.js - routing, ORM, auth, WebSocket, SSE, gRPC, observability, and 20+ middleware. Distributed as a single SDK and as scoped @zero-server/* packages.",
   "main": "index.js",
   "bin": {