lazylog-trace 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# Lazylog
+
+Request-scoped logging for Express. All logs produced during a request are tied to that request and stored (SQLite by default). Retrieve logs by request id, and optionally attach context (e.g. user id) to every log for that request.
+
+No UI, no heavy abstractions—just middleware, a request-scoped logger, and persistence.
+
+## Install
+
+```bash
+npm install lazylog
+```
+
+Peer dependency: **Express** (v4 or v5). You must have `express` installed in your app.
+
+## Build and test (in this repo)
+
+There is no build step—the package is plain JavaScript and `main` points at `src/index.js`.
+
+**Run tests in this repo:**
+
+```bash
+npm install
+npm test
+```
+
+This runs the integration test (Express app, one request, asserts logs and request are stored). You need Node.js build tools for the `better-sqlite3` native addon; on Windows you may need [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools) or Visual Studio Build Tools.
+
+**Test lazylog in another repo (local development):**
+
+1. In **lazylog** (this repo):  
+   `npm link`
+
+2. In your **app repo**:  
+   `npm link lazylog`  
+   Then use it as usual: `const { requestLogger, getRequestLogger } = require('lazylog');`
+
+**Or install from a tarball (no link):**
+
+1. In **lazylog**:  
+   `npm pack`  
+   This creates `lazylog-1.0.0.tgz`.
+
+2. In your **app repo**:  
+   `npm install /path/to/lazylog/lazylog-1.0.0.tgz`
+
+## Usage
+
+### 1. Middleware
+
+Mount the middleware to enable request-scoped logging and persistence:
+
+```js
+const { requestLogger } = require('lazylog');
+
+app.use(express.json()); // if you need req.body
+app.use(requestLogger({
+  ignorePaths: ['/health'],
+  logBody: true,
+  logResponse: true,
+  databasePath: './logs.sqlite',  // optional; default is ./logs.sqlite
+  // or databaseUrl: 'file:./logs.sqlite',
+}));
+```
+
+**Options:**
+
+| Option          | Default        | Description |
+|-----------------|----------------|-------------|
+| `ignorePaths`   | `[]`           | Paths (strings or RegExp) to skip logging entirely. |
+| `logBody`       | `true`         | Persist `req.body` on the request row. |
+| `logResponse`   | `true`         | Capture response body (via `res.send`/`res.json`) and persist on the request row. |
+| `databasePath`  | `'./logs.sqlite'` | Path to the SQLite file. |
+| `databaseUrl`   | —              | Alternative: e.g. `'file:./logs.sqlite'` (parsed to a path). |
+
+### 2. Request-scoped logger
+
+Inside any route or downstream middleware, get the logger for the current request:
+
+```js
+const { getRequestLogger } = require('lazylog');
+
+app.post('/login', (req, res) => {
+  const log = getRequestLogger();
+  log.info('Login attempt');
+  log.error('Invalid password');
+  // All of these are stored with the same request_id
+  res.json({ ok: false });
+});
+```
+
+Logger methods: **`.log()`**, **`.info()`**, **`.warn()`**, **`.error()`**. Each accepts a message string and an optional metadata object:
+
+```js
+log.info('User action', { actionId: 42 });
+```
+
+If called **outside** a request (e.g. in a cron job), `getRequestLogger()` returns a logger that only writes to the console (no DB).
+
+### 3. Add context
+
+Attach extra fields to every subsequent log for that request:
+
+```js
+const log = getRequestLogger();
+log.addContext({ userId: 123, email: 'u@example.com' });
+log.info('User action'); // stored with userId and email in context
+```
+
+### 4. Retrieve logs by request
+
+Use the stored data in your app or a simple admin route:
+
+```js
+const { getLogsByRequestId, getRequest } = require('lazylog');
+
+// All log entries for a request
+const logs = getLogsByRequestId(requestId);
+
+// Request row plus its logs
+const data = getRequest(requestId);
+// data.request: { id, method, path, body, response, response_status, started_at, finished_at }
+// data.logs: array of { id, request_id, level, message, context, created_at }
+```
+
+Storage is the one from the last-configured `requestLogger()` middleware. If the middleware has never been mounted, `getLogsByRequestId` returns `[]` and `getRequest` returns `null`.
+
+## Storage schema (SQLite)
+
+- **requests**: `id` (UUID), `method`, `path`, `body` (JSON/text), `response` (text), `response_status` (int), `started_at`, `finished_at`.
+- **logs**: `id`, `request_id` (FK to requests), `level`, `message`, `context` (JSON), `created_at`.
+
+Index on `logs.request_id` for fast lookups.
+
+## Best practices
+
+- Use `getRequestLogger()` for request-scoped logs instead of `console.log`, so everything is tied to the request and stored.
+- Use `ignorePaths` for health checks or noisy endpoints you don’t need to log.
+- Use `addContext()` after auth so every log for that request includes user id or email.
+
+## Publishing to npm
+
+Before publishing:
+
+1. **Set repo URLs** in `package.json`: replace `YOUR_USERNAME` in `repository`, `bugs`, and `homepage` with your GitHub username (or org).
+2. **Set author** in `package.json`, e.g. `"author": "Your Name <you@example.com>"` or `"author": "https://github.com/YOUR_USERNAME"`.
+3. **Check the package name**: `lazylog` may be taken on npm. Use `npm search lazylog` or pick a scoped name, e.g. `@yourusername/lazylog`.
+4. **Log in**: `npm login`
+5. **Dry run**: `npm publish --dry-run` to see what will be published (only `src/`, `README.md`, and `LICENSE` are included via the `files` field).
+6. **Publish**: `npm publish` (or `npm publish --access public` if using a scoped package like `@yourusername/lazylog`).

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "lazylog-trace",
+  "version": "1.0.0",
+  "description": "Request-scoped logging for Express with SQLite persistence. Tie logs to each request and retrieve them by request id.",
+  "main": "src/index.js",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "scripts": {
+    "test": "node test/integration.js",
+    "prepublishOnly": "npm test"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "express",
+    "logging",
+    "request-scoped",
+    "sqlite",
+    "middleware",
+    "request-id",
+    "persistence"
+  ],
+  "author": "Chomas_dev ",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChomasDev/lazylog.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ChomasDev/lazylog/issues"
+  },
+  "homepage": "https://github.com/ChomasDev/lazylog#readme",
+  "dependencies": {
+    "better-sqlite3": "^11.0.0"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "express": "^4.21.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,43 @@
+const middleware = require('./middleware.js');
+const { noopLogger } = require('./logger.js');
+
+/**
+ * Returns the request-scoped logger for the current request.
+ * If called outside a request (no middleware context), returns a no-op logger that only writes to console.
+ * @returns {{ log: function, info: function, warn: function, error: function, addContext: function }}
+ */
+function getRequestLogger() {
+  const store = middleware.getStore();
+  if (!store || !store.logger) return noopLogger;
+  return store.logger;
+}
+
+/**
+ * Returns all log entries for the given request id.
+ * Uses the storage from the last-configured requestLogger middleware.
+ * @param {string} requestId
+ * @returns {Array<{ id: number, request_id: string, level: string, message: string, context: object, created_at: string }>}
+ */
+function getLogsByRequestId(requestId) {
+  const storage = middleware.defaultStorage;
+  if (!storage) return [];
+  return storage.getLogsByRequestId(requestId);
+}
+
+/**
+ * Returns the request row and its logs, or null if not found.
+ * @param {string} requestId
+ * @returns {{ request: object, logs: array } | null}
+ */
+function getRequest(requestId) {
+  const storage = middleware.defaultStorage;
+  if (!storage) return null;
+  return storage.getRequest(requestId);
+}
+
+module.exports = {
+  requestLogger: middleware.requestLogger,
+  getRequestLogger,
+  getLogsByRequestId,
+  getRequest,
+};

package/src/logger.js

@@ -0,0 +1,60 @@
+/**
+ * Request-scoped logger. Writes to storage with request_id and optional context.
+ * addContext() merges into a shared context object; every log includes that context.
+ */
+
+function createRequestLogger(requestId, storage, contextRef) {
+  function write(level, message, meta = {}) {
+    const context = { ...contextRef };
+    const payload = { ...context, ...meta };
+    storage.saveLog(requestId, level, message, payload);
+    const out = payload && Object.keys(payload).length ? ` ${JSON.stringify(payload)}` : '';
+    console[level === 'log' ? 'log' : level](`[${requestId}] ${level}: ${message}${out}`);
+  }
+
+  return {
+    addContext(obj) {
+      if (obj && typeof obj === 'object') {
+        Object.assign(contextRef, obj);
+      }
+    },
+
+    log(message, meta) {
+      write('log', message, meta);
+    },
+
+    info(message, meta) {
+      write('info', message, meta);
+    },
+
+    warn(message, meta) {
+      write('warn', message, meta);
+    },
+
+    error(message, meta) {
+      write('error', message, meta);
+    },
+  };
+}
+
+/**
+ * No-op logger for use outside a request (e.g. getRequestLogger() when not in middleware).
+ * Logs to console only, no DB.
+ */
+const noopLogger = {
+  addContext() {},
+  log(msg, meta) {
+    console.log(msg, meta != null ? meta : '');
+  },
+  info(msg, meta) {
+    console.info(msg, meta != null ? meta : '');
+  },
+  warn(msg, meta) {
+    console.warn(msg, meta != null ? meta : '');
+  },
+  error(msg, meta) {
+    console.error(msg, meta != null ? meta : '');
+  },
+};
+
+module.exports = { createRequestLogger, noopLogger };

package/src/middleware.js

@@ -0,0 +1,112 @@
+const { AsyncLocalStorage } = require('async_hooks');
+const crypto = require('crypto');
+const { createRequestLogger } = require('./logger.js');
+const { createSqliteStorage } = require('./sqlite.js');
+
+const asyncLocalStorage = new AsyncLocalStorage();
+
+/** Default storage instance; set when requestLogger is first used. */
+let defaultStorage = null;
+
+function generateRequestId() {
+  if (crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return crypto.randomBytes(16).toString('hex');
+}
+
+function matchesIgnore(path, ignorePaths) {
+  if (!ignorePaths || !ignorePaths.length) return false;
+  for (const p of ignorePaths) {
+    if (typeof p === 'string' && path === p) return true;
+    if (p instanceof RegExp && p.test(path)) return true;
+  }
+  return false;
+}
+
+/**
+ * @param {object} options
+ * @param {string[]|RegExp[]} [options.ignorePaths]
+ * @param {boolean} [options.logBody=true]
+ * @param {boolean} [options.logResponse=true]
+ * @param {string} [options.databasePath]
+ * @param {string} [options.databaseUrl]
+ */
+function requestLogger(options = {}) {
+  const {
+    ignorePaths = [],
+    logBody = true,
+    logResponse = true,
+    databasePath,
+    databaseUrl,
+  } = options;
+
+  const storage = createSqliteStorage({ databasePath, databaseUrl });
+  defaultStorage = storage;
+
+  return function lazylogMiddleware(req, res, next) {
+    const path = req.path || req.url?.split('?')[0] || '';
+    if (matchesIgnore(path, ignorePaths)) {
+      return next();
+    }
+
+    const requestId = generateRequestId();
+    const startedAt = new Date().toISOString();
+    const context = {};
+    const logger = createRequestLogger(requestId, storage, context);
+
+    storage.saveRequest(requestId, {
+      method: req.method,
+      path,
+      body: logBody ? req.body : null,
+      response: null,
+      response_status: null,
+      started_at: startedAt,
+      finished_at: null,
+    });
+
+    let responseBody = null;
+    let responseStatus = null;
+
+    if (logResponse) {
+      const originalSend = res.send.bind(res);
+      const originalJson = res.json.bind(res);
+
+      res.send = function (body) {
+        responseBody = typeof body === 'string' ? body : JSON.stringify(body);
+        return originalSend(body);
+      };
+      res.json = function (body) {
+        responseBody = JSON.stringify(body);
+        return originalJson(body);
+      };
+
+      res.on('finish', () => {
+        responseStatus = res.statusCode;
+        storage.updateRequest(requestId, {
+          response: responseBody,
+          response_status: responseStatus,
+          finished_at: new Date().toISOString(),
+        });
+      });
+    } else {
+      res.on('finish', () => {
+        storage.updateRequest(requestId, {
+          response: null,
+          response_status: res.statusCode,
+          finished_at: new Date().toISOString(),
+        });
+      });
+    }
+
+    res.setHeader('X-Request-Id', requestId);
+    const store = { requestId, logger, context };
+    asyncLocalStorage.run(store, () => next());
+  };
+}
+
+function getStore() {
+  return asyncLocalStorage.getStore();
+}
+
+module.exports = { requestLogger, getStore, get defaultStorage() { return defaultStorage; } };

package/src/sqlite.js

@@ -0,0 +1,139 @@
+const Database = require('better-sqlite3');
+const path = require('path');
+
+const DEFAULT_DB_PATH = './logs.sqlite';
+
+/**
+ * Resolve database path from options (databasePath or databaseUrl).
+ * databaseUrl like 'file:./logs.sqlite' is parsed to a path.
+ * @param {{ databasePath?: string, databaseUrl?: string }} options
+ * @returns {string}
+ */
+function resolveDbPath(options = {}) {
+  if (options.databasePath) {
+    return path.resolve(process.cwd(), options.databasePath);
+  }
+  if (options.databaseUrl) {
+    const url = options.databaseUrl;
+    if (url.startsWith('file:')) {
+      return path.resolve(process.cwd(), url.slice(5).replace(/^\/+/, ''));
+    }
+    return path.resolve(process.cwd(), url);
+  }
+  return path.resolve(process.cwd(), DEFAULT_DB_PATH);
+}
+
+/**
+ * Create SQLite storage and ensure tables exist.
+ * @param {{ databasePath?: string, databaseUrl?: string }} options
+ * @returns {import('./storage.js')}
+ */
+function createSqliteStorage(options = {}) {
+  const dbPath = resolveDbPath(options);
+  const db = new Database(dbPath);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS requests (
+      id TEXT PRIMARY KEY,
+      method TEXT NOT NULL,
+      path TEXT NOT NULL,
+      body TEXT,
+      response TEXT,
+      response_status INTEGER,
+      started_at TEXT NOT NULL,
+      finished_at TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS logs (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      request_id TEXT NOT NULL,
+      level TEXT NOT NULL,
+      message TEXT NOT NULL,
+      context TEXT,
+      created_at TEXT NOT NULL,
+      FOREIGN KEY (request_id) REFERENCES requests(id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_logs_request_id ON logs(request_id);
+  `);
+
+  return {
+    saveRequest(requestId, data) {
+      const stmt = db.prepare(`
+        INSERT INTO requests (id, method, path, body, response, response_status, started_at, finished_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+      const bodyStr = data.body != null ? JSON.stringify(data.body) : null;
+      stmt.run(
+        requestId,
+        data.method,
+        data.path,
+        bodyStr,
+        data.response ?? null,
+        data.response_status ?? null,
+        data.started_at,
+        data.finished_at ?? null
+      );
+    },
+
+    saveLog(requestId, level, message, context) {
+      const stmt = db.prepare(`
+        INSERT INTO logs (request_id, level, message, context, created_at)
+        VALUES (?, ?, ?, ?, ?)
+      `);
+      const contextStr = context && Object.keys(context).length > 0 ? JSON.stringify(context) : null;
+      stmt.run(requestId, level, message, contextStr, new Date().toISOString());
+    },
+
+    getLogsByRequestId(requestId) {
+      const stmt = db.prepare(`
+        SELECT id, request_id, level, message, context, created_at
+        FROM logs WHERE request_id = ? ORDER BY created_at ASC
+      `);
+      const rows = stmt.all(requestId);
+      return rows.map((row) => ({
+        id: row.id,
+        request_id: row.request_id,
+        level: row.level,
+        message: row.message,
+        context: row.context ? JSON.parse(row.context) : {},
+        created_at: row.created_at,
+      }));
+    },
+
+    updateRequest(requestId, data) {
+      const stmt = db.prepare(`
+        UPDATE requests SET response = ?, response_status = ?, finished_at = ?
+        WHERE id = ?
+      `);
+      stmt.run(
+        data.response ?? null,
+        data.response_status ?? null,
+        data.finished_at ?? null,
+        requestId
+      );
+    },
+
+    getRequest(requestId) {
+      const reqStmt = db.prepare('SELECT * FROM requests WHERE id = ?');
+      const requestRow = reqStmt.get(requestId);
+      if (!requestRow) return null;
+
+      const request = {
+        id: requestRow.id,
+        method: requestRow.method,
+        path: requestRow.path,
+        body: requestRow.body ? JSON.parse(requestRow.body) : null,
+        response: requestRow.response,
+        response_status: requestRow.response_status,
+        started_at: requestRow.started_at,
+        finished_at: requestRow.finished_at,
+      };
+
+      const logs = this.getLogsByRequestId(requestId);
+      return { request, logs };
+    },
+  };
+}
+
+module.exports = { createSqliteStorage, resolveDbPath };

package/src/storage.js

@@ -0,0 +1,41 @@
+/**
+ * Abstract storage interface for request and log persistence.
+ * Implementations (e.g. sqlite.js) provide: saveRequest, saveLog, getLogsByRequestId, getRequest.
+ */
+
+/**
+ * @typedef {Object} RequestRow
+ * @property {string} id
+ * @property {string} method
+ * @property {string} path
+ * @property {string|object|null} body
+ * @property {string|null} response
+ * @property {number|null} response_status
+ * @property {string} started_at
+ * @property {string|null} finished_at
+ */
+
+/**
+ * @typedef {Object} LogEntry
+ * @property {number} id
+ * @property {string} request_id
+ * @property {string} level
+ * @property {string} message
+ * @property {object} context
+ * @property {string} created_at
+ */
+
+/**
+ * @typedef {Object} RequestWithLogs
+ * @property {RequestRow} request
+ * @property {LogEntry[]} logs
+ */
+
+/**
+ * Storage interface. Implementations must provide:
+ * - saveRequest(requestId, data)
+ * - saveLog(requestId, level, message, context)
+ * - getLogsByRequestId(requestId) -> LogEntry[]
+ * - getRequest(requestId) -> RequestWithLogs | null
+ */
+module.exports = {};