logs-gateway 3.2.0 → 3.5.0

package/dist/utils/package-logs-level.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Package-level log threshold via `<packagePrefix>_LOGS_LEVEL` (canonical contract).
+ * See docs/package-usage.md in this package.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageLogsLevelEnvKey = packageLogsLevelEnvKey;
+exports.legacyPackageLogLevelEnvKey = legacyPackageLogLevelEnvKey;
+exports.parsePackageLogsLevelString = parsePackageLogsLevelString;
+exports.resolvePackageLogsLevel = resolvePackageLogsLevel;
+const OFF_SYNONYMS = new Set(['off', 'none', 'silent']);
+const LEVEL_ALIASES = {
+    verbose: 'verbose',
+    debug: 'debug',
+    info: 'info',
+    warn: 'warn',
+    error: 'error'
+};
+/**
+ * Environment variable name for the canonical package log threshold: `<PREFIX>_LOGS_LEVEL`.
+ */
+function packageLogsLevelEnvKey(envPrefix) {
+    return `${envPrefix}_LOGS_LEVEL`;
+}
+/**
+ * Legacy env var: `<PREFIX>_LOG_LEVEL` (still supported when `_LOGS_LEVEL` is unset).
+ */
+function legacyPackageLogLevelEnvKey(envPrefix) {
+    return `${envPrefix}_LOG_LEVEL`;
+}
+/**
+ * Parse a single value (case-insensitive). Unknown values are treated as disabled (off).
+ * Empty or whitespace-only string is treated as off.
+ */
+function parsePackageLogsLevelString(raw) {
+    if (raw === undefined) {
+        return { packageLogsDisabled: true };
+    }
+    const n = raw.trim().toLowerCase();
+    if (n.length === 0 || OFF_SYNONYMS.has(n)) {
+        return { packageLogsDisabled: true };
+    }
+    const level = LEVEL_ALIASES[n];
+    if (level) {
+        return { packageLogsDisabled: false, logLevel: level };
+    }
+    return { packageLogsDisabled: true };
+}
+/**
+ * Resolve package log threshold for a logger instance.
+ *
+ * Precedence: `userLogLevel` → `<PREFIX>_LOGS_LEVEL` (if set in env) → `<PREFIX>_LOG_LEVEL` (legacy, if set) → **`warn`** (neither key set in env).
+ *
+ * When silent, `logLevel` in the result is `'error'` as a placeholder for internal storage; emission is gated by `packageLogsDisabled`.
+ */
+function resolvePackageLogsLevel(options) {
+    const { envPrefix, userLogLevel, env = process.env } = options;
+    if (userLogLevel !== undefined) {
+        return { packageLogsDisabled: false, logLevel: userLogLevel };
+    }
+    const logsKey = packageLogsLevelEnvKey(envPrefix);
+    const legacyKey = legacyPackageLogLevelEnvKey(envPrefix);
+    if (Object.prototype.hasOwnProperty.call(env, logsKey)) {
+        const parsed = parsePackageLogsLevelString(env[logsKey]);
+        if (parsed.packageLogsDisabled || !parsed.logLevel) {
+            return { packageLogsDisabled: true, logLevel: 'error' };
+        }
+        return { packageLogsDisabled: false, logLevel: parsed.logLevel };
+    }
+    if (Object.prototype.hasOwnProperty.call(env, legacyKey)) {
+        const parsed = parsePackageLogsLevelString(env[legacyKey]);
+        if (parsed.packageLogsDisabled || !parsed.logLevel) {
+            return { packageLogsDisabled: true, logLevel: 'error' };
+        }
+        return { packageLogsDisabled: false, logLevel: parsed.logLevel };
+    }
+    return { packageLogsDisabled: false, logLevel: 'warn' };
+}
+//# sourceMappingURL=package-logs-level.js.map

package/dist/utils/package-logs-level.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-logs-level.js","sourceRoot":"","sources":["../../src/utils/package-logs-level.ts"],"names":[],"mappings":"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"}

package/docs/package-usage.md

@@ -0,0 +1,155 @@
+# Package logging via `.env` (logs-gateway)
+
+**Canonical contract** for npm packages that emit diagnostics through **[logs-gateway](https://www.npmjs.com/package/logs-gateway)**.
+
+- **Per package:** only **logs level** is configured with that package’s **package prefix** on the variable name.
+- **Cross-cutting (once per app / process):** where logs go (console, file, unified, …) and **format** are **not** repeated per package—they are shared for the whole host. Downstream wiring implements that split; this doc defines the **package-level** part only.
+
+**Default when neither `<packagePrefix>_LOGS_LEVEL` nor `<packagePrefix>_LOG_LEVEL` is set in the environment:** **`warn`** (emit **`warn`** and **`error`** only). To silence a package, set **`off`** (or synonyms **`none`** / **`silent`**). To see **`info`**, **`debug`**, or **`verbose`**, raise the level explicitly.
+
+**Package prefix** is the short token a package owns for its **single** logs-gateway-related variable in this contract (illustrative examples: **`MY_LIB`**, **`EXAMPLE_SVC`**). Each package documents its own prefix in its README.
+
+**logs-gateway** implements this contract inside `createLogger` / `LogsGateway`. It also exposes **`resolvePackageLogsLevel`**, **`parsePackageLogsLevelString`**, **`packageLogsLevelEnvKey`**, and **`legacyPackageLogLevelEnvKey`** for the same rules outside the gateway if needed.
+
+---
+
+## For package authors — how to implement
+
+1. **Depend on** `logs-gateway` (normal `dependencies` for a library that logs).
+2. **Choose a stable prefix** (short acronym, not the full scoped npm name). Use the same string for **`envPrefix`** and for documenting the env var (e.g. **`MY_LIB`** → **`MY_LIB_LOGS_LEVEL`**).
+3. **Create one logger** (or one per logical surface, each with its own prefix if you truly need separate toggles—usually one prefix per package):
+
+   ```typescript
+   import { createLogger } from 'logs-gateway';
+
+   export const logger = createLogger({
+     packageName: 'MyLib',        // label in log lines
+     envPrefix: 'MY_LIB',         // reads MY_LIB_LOGS_LEVEL / MY_LIB_LOG_LEVEL
+     debugNamespace: 'my-lib'     // optional: DEBUG namespace
+   });
+   ```
+
+4. **Emit using gateway levels** — `logger.error`, `logger.warn`, `logger.info`, `logger.debug`, `logger.verbose`. What actually appears is filtered by the resolved **minimum level** (see table below).
+5. **Document for consumers** in your README: the prefix, the exact key **`<prefix>_LOGS_LEVEL`**, allowed values, and that **default is `warn`** if the variable is not set (and legacy **`_LOG_LEVEL`** is not set).
+6. **Optional programmatic default** — pass **`logLevel`** in the second argument to **`createLogger`** only when you need a non-env default (it overrides env for that instance).
+
+You do **not** need to read **`process.env`** for the level yourself if you use **`createLogger`** / **`LogsGateway`**; resolution is built in.
+
+---
+
+## For apps and operators — downstream (different levels per package)
+
+Integrators tune **verbosity per dependency** by setting **one variable per package prefix** in **`.env`** (or the host’s secret/config store). That flows **downstream** into each library’s logger without code changes:
+
+```dotenv
+# Quieter third-party package; louder in-house library
+EXAMPLE_GATEWAY_LOGS_LEVEL=error
+MY_LIB_LOGS_LEVEL=info
+
+# Turn one package off entirely
+OTHER_PKG_LOGS_LEVEL=off
+```
+
+Cross-cutting knobs (**where** logs go, **format**, file paths, unified sink, etc.) are configured **once** for the host (see logs-gateway README), not duplicated per package prefix.
+
+---
+
+## 1. Package-level variable (only): `<packagePrefix>_LOGS_LEVEL`
+
+```dotenv
+MY_LIB_LOGS_LEVEL=warn
+```
+
+Pattern: **`<packagePrefix>_LOGS_LEVEL`**.
+
+- If **both** **`<packagePrefix>_LOGS_LEVEL`** and **`<packagePrefix>_LOG_LEVEL`** are **absent** from the environment, **logs-gateway** uses **`warn`** as the effective threshold.
+- **`off`** (or **`none`** / **`silent`**) means that package does **not** emit diagnostic logs (regardless of cross-cutting sink configuration).
+
+No other **package-prefixed** `.env` keys are part of this contract—**not** `<packagePrefix>_LOG_TO_CONSOLE`, `<packagePrefix>_LOG_TO_FILE`, `<packagePrefix>_LOG_FORMAT`, etc. Those belong to **cross-cutting** configuration.
+
+---
+
+## 2. Allowed values for `<packagePrefix>_LOGS_LEVEL`
+
+| Value | Meaning |
+|--------|---------|
+| **`off`** | Package diagnostics disabled (`none` / `silent` are synonyms). |
+| **`error`** | Emit **`error`** only. |
+| **`warn`** | Emit **`warn`** and **`error`**. |
+| **`info`** | Emit **`info`** and above. |
+| **`debug`** | Emit **`debug`** and above. |
+| **`verbose`** | Most verbose. |
+
+**Default when the env keys are not set:** **`warn`** (see §1).
+
+Case-insensitive values are recommended; **logs-gateway** normalizes case when parsing.
+
+Unknown values are treated as **`off`** (silent) in **logs-gateway**.
+
+**Precedence in env:** if **both** **`_LOGS_LEVEL`** and **`_LOG_LEVEL`** are set, **`_LOGS_LEVEL`** wins. If only **`_LOG_LEVEL`** is set (legacy), it is used the same way as **`_LOGS_LEVEL`**.
+
+---
+
+## 3. Cross-cutting configuration (shared across packages)
+
+**Console, file, log file path, text/json/table format, unified logger, and similar** are **application- or host-level** concerns. They apply **once** to the process, not once per library prefix.
+
+- A package with **`_LOGS_LEVEL=off`** must not emit diagnostics; host settings do not override that.
+- When the package level is not **`off`**, lines use the **same** shared sinks and format as other packages that are allowed to emit.
+
+Exact host variable names are in **logs-gateway** and application docs; they are not **`<packagePrefix>_…`** patterns in this contract.
+
+---
+
+## 4. Choosing the package prefix
+
+- Prefer a **stable acronym or short name**, not the full scoped npm name.
+- Example (illustrative): **`@acme/example-lib`** might use **`EXAMPLE_LIB`**—pick one and keep it.
+
+Document the prefix and **`<prefix>_LOGS_LEVEL`** in the package README.
+
+---
+
+## 5. Example `.env` (placeholders)
+
+**Per package (levels only):**
+
+```dotenv
+MY_LIB_LOGS_LEVEL=warn
+EXAMPLE_GATEWAY_LOGS_LEVEL=info
+
+# Silence or debug one layer
+OTHER_PKG_LOGS_LEVEL=off
+MY_LIB_LOGS_LEVEL=debug
+```
+
+**Cross-cutting (illustrative—host / logs-gateway global keys):**
+
+```dotenv
+# LOG_TO_CONSOLE=true
+# LOG_FORMAT=json
+```
+
+---
+
+## 6. Interaction with process-wide `DEBUG`
+
+Some stacks use **`DEBUG`** (comma-separated namespaces). That is separate from this contract:
+
+- **`_LOGS_LEVEL=off`** stays authoritative: the package stays silent in **logs-gateway**.
+- **`DEBUG`** can still allow **`verbose`** / **`debug`** lines **only when the package is not silent** (`packageLogsDisabled` is false). See **logs-gateway** README for details.
+
+---
+
+## 7. Summary
+
+| Layer | What is configured |
+|--------|-------------------|
+| **Per package** | **Only** `<packagePrefix>_LOGS_LEVEL` (default **`warn`** when both `_LOGS_LEVEL` and `_LOG_LEVEL` are unset in the environment) |
+| **Cross-cutting** | Console, file, format, unified sink, etc.—**once** for the app / process |
+
+---
+
+## 8. Migration note
+
+If you relied on older behavior where **no** env vars implied **silent** output, set **`{PREFIX}_LOGS_LEVEL=off`** explicitly, or **`{PREFIX}_LOG_LEVEL=off`** if you only use the legacy key.

package/docs/package.md

@@ -0,0 +1,48 @@
+**don’t use CommonJS** 🙂
+
+### Use **ESM only**
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext"
+  }
+}
+```
+
+### Why this is the *right* choice **now**
+
+* **Native ESM everywhere** (Node 18/20+, Bun, Deno, modern bundlers)
+* Clean `import` / `export`, no interop hacks
+* Future-proof for:
+
+  * tree-shaking
+  * edge / workers
+  * package `exports`
+* Matches how *new* libraries are written in 2025–2026
+
+### What *not* to do
+
+* ❌ `"module": "commonjs"` → legacy, friction, dead-end
+* ❌ `"module": "ES2020"` without `NodeNext` → subtle resolution bugs with Node ESM
+
+### Minimal `package.json` you should use
+
+```json
+{
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  }
+}
+```
+
+### One important rule (don’t trip on this)
+
+* Use **explicit file extensions** in imports:
+
+  ```ts
+  import { x } from "./utils.js";
+  ```

package/package.json

@@ -1,94 +1,95 @@
-{
-  "name": "logs-gateway",
-  "version": "3.2.0",
-  "description": "Standardized logging gateway for Node.js with PII sanitization, correlation trails, Shadow Logging for test/debug capture, scoping with text filters, story output, troubleshooting integration, and multi-format output (JSON/YAML/text)",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "clean": "rimraf dist",
-    "test": "vitest",
-    "prepublishOnly": "npm run clean && npm run build",
-    "generate-erc": "tsx scripts/generate-erc-manifest.ts"
-  },
-  "keywords": [
-    "logging",
-    "logger",
-    "typescript",
-    "node",
-    "console",
-    "file",
-    "json",
-    "yaml",
-    "sanitization",
-    "pii",
-    "security",
-    "privacy",
-    "shadow-logging",
-    "debug-capture",
-    "test-logging",
-    "correlation",
-    "tracing",
-    "opentelemetry",
-    "trails",
-    "scoping",
-    "troubleshooting",
-    "story-output",
-    "scope-record"
-  ],
-  "author": "nx-morpheus",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/nx-intelligence/logs-gateway.git"
-  },
-  "homepage": "https://github.com/nx-intelligence/logs-gateway#readme",
-  "bugs": {
-    "url": "https://github.com/nx-intelligence/logs-gateway/issues"
-  },
-  "files": [
-    "dist/**/*",
-    "README.md",
-    "LICENSE"
-  ],
-  "dependencies": {
-    "@cdssnc/sanitize-pii": "^2.0.3",
-    "@x-developer/unified-logger": "^1.0.15",
-    "consola": "^3.4.2",
-    "fast-redact": "^3.5.0",
-    "js-yaml": "^4.1.0",
-    "micro-logs": "^1.0.0",
-    "nanoid": "^5.1.6",
-    "nx-config2": "^3.5.0",
-    "pino": "^10.1.0",
-    "pino-http": "^11.0.0",
-    "pino-pretty": "^13.1.2",
-    "rotating-file-stream": "^3.2.7",
-    "validator": "^13.15.15",
-    "winston-daily-rotate-file": "^5.0.0",
-    "xss": "^1.0.15"
-  },
-  "devDependencies": {
-    "@types/fast-redact": "^3.0.4",
-    "@types/js-yaml": "^4.0.9",
-    "@types/nanoid": "^2.1.0",
-    "@types/node": "^20.0.0",
-    "@types/pino": "^7.0.4",
-    "@types/validator": "^13.15.3",
-    "rimraf": "^6.0.1",
-    "tsx": "^4.7.0",
-    "typescript": "^5.0.0",
-    "vitest": "^4.0.3"
-  },
-  "peerDependencies": {
-    "nx-troubleshooting": "^2.0.1"
-  },
-  "optionalDependencies": {
-    "nx-troubleshooting": "^2.0.1"
-  },
-  "engines": {
-    "node": ">=16.0.0"
-  },
-  "type": "commonjs"
-}
+{
+  "name": "logs-gateway",
+  "version": "3.5.0",
+  "description": "Standardized logging gateway for Node.js with PII sanitization, correlation trails, Shadow Logging for test/debug capture, scoping with text filters, story output, troubleshooting integration, and multi-format output (JSON/YAML/text)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rimraf dist",
+    "test": "vitest",
+    "prepublishOnly": "npm run clean && npm run build",
+    "generate-erc": "tsx scripts/generate-erc-manifest.ts"
+  },
+  "keywords": [
+    "logging",
+    "logger",
+    "typescript",
+    "node",
+    "console",
+    "file",
+    "json",
+    "yaml",
+    "sanitization",
+    "pii",
+    "security",
+    "privacy",
+    "shadow-logging",
+    "debug-capture",
+    "test-logging",
+    "correlation",
+    "tracing",
+    "opentelemetry",
+    "trails",
+    "scoping",
+    "troubleshooting",
+    "story-output",
+    "scope-record"
+  ],
+  "author": "nx-morpheus",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nx-intelligence/logs-gateway.git"
+  },
+  "homepage": "https://github.com/nx-intelligence/logs-gateway#readme",
+  "bugs": {
+    "url": "https://github.com/nx-intelligence/logs-gateway/issues"
+  },
+  "files": [
+    "dist/**/*",
+    "docs/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@cdssnc/sanitize-pii": "^2.0.3",
+    "@x-developer/unified-logger": "^1.0.15",
+    "consola": "^3.4.2",
+    "fast-redact": "^3.5.0",
+    "js-yaml": "^4.1.0",
+    "micro-logs": "^1.0.0",
+    "nanoid": "^5.1.6",
+    "nx-config2": "^3.5.0",
+    "pino": "^10.1.0",
+    "pino-http": "^11.0.0",
+    "pino-pretty": "^13.1.2",
+    "rotating-file-stream": "^3.2.7",
+    "validator": "^13.15.15",
+    "winston-daily-rotate-file": "^5.0.0",
+    "xss": "^1.0.15"
+  },
+  "devDependencies": {
+    "@types/fast-redact": "^3.0.4",
+    "@types/js-yaml": "^4.0.9",
+    "@types/nanoid": "^2.1.0",
+    "@types/node": "^20.0.0",
+    "@types/pino": "^7.0.4",
+    "@types/validator": "^13.15.3",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.3"
+  },
+  "peerDependencies": {
+    "nx-troubleshooting": "^2.0.1"
+  },
+  "optionalDependencies": {
+    "nx-troubleshooting": "^2.0.1"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "type": "commonjs"
+}