@darksheep/logger 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 1.0.0 (2024-07-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* Drop node@^18
+
+### 💡 Features
+
+* Bump to latest node lts versions ([#196](https://github.com/DarkSheepSoftware/node-packages/issues/196)) ([60a95cc](https://github.com/DarkSheepSoftware/node-packages/commit/60a95cc41b22c39428d35814c0d5e85830052a14))
+* Drop node@^18 ([5f809a6](https://github.com/DarkSheepSoftware/node-packages/commit/5f809a6b2737db425cde55d58c22375ebcded687))
+
+
+### 📦 Dependencies
+
+* **dev:** update dependency @types/node to v20.14.1 ([#207](https://github.com/DarkSheepSoftware/node-packages/issues/207)) ([5ad7a75](https://github.com/DarkSheepSoftware/node-packages/commit/5ad7a75b29cf1fe8710a70f4179027ff7f156611))
+* **dev:** update dependency eslint to v9 ([#139](https://github.com/DarkSheepSoftware/node-packages/issues/139)) ([a01a119](https://github.com/DarkSheepSoftware/node-packages/commit/a01a119642704615386e37f2092801e08cf2f1b7))
+* **dev:** update dependency eslint to v9 ([#252](https://github.com/DarkSheepSoftware/node-packages/issues/252)) ([7473b18](https://github.com/DarkSheepSoftware/node-packages/commit/7473b18e59c132f41e03cd6237842205bc23d08e))
+* **dev:** update dependency typescript to ~5.5.0 ([#242](https://github.com/DarkSheepSoftware/node-packages/issues/242)) ([68413b5](https://github.com/DarkSheepSoftware/node-packages/commit/68413b57ef85df879c33243566618a2ecb700051))
+* **pkg:** update dependency deepmerge-ts to v6 ([#189](https://github.com/DarkSheepSoftware/node-packages/issues/189)) ([23a4575](https://github.com/DarkSheepSoftware/node-packages/commit/23a4575e4405034d3562a90d6c706cab07d62ce5))
+* **pkg:** update dependency deepmerge-ts to v7 ([#191](https://github.com/DarkSheepSoftware/node-packages/issues/191)) ([717aca5](https://github.com/DarkSheepSoftware/node-packages/commit/717aca519c6114b35be756dcae225e92dafc7ff4))
+* **pkg:** update dependency deepmerge-ts to v7.0.1 ([#192](https://github.com/DarkSheepSoftware/node-packages/issues/192)) ([bb7557a](https://github.com/DarkSheepSoftware/node-packages/commit/bb7557a533b033e54b4498b524ea90195878c8f7))
+* **pkg:** update dependency deepmerge-ts to v7.0.2 ([#210](https://github.com/DarkSheepSoftware/node-packages/issues/210)) ([109f763](https://github.com/DarkSheepSoftware/node-packages/commit/109f763411f7b825cf4cd9c1d92741e737a0bdd6))
+* **pkg:** update dependency deepmerge-ts to v7.0.3 ([#217](https://github.com/DarkSheepSoftware/node-packages/issues/217)) ([ea218ab](https://github.com/DarkSheepSoftware/node-packages/commit/ea218ab9496532721d99d402de7200488a8bfd16))
+
+
+### 🧹 Miscellaneous Chores
+
+* Prepare "Logger" for publishing ([b14b4af](https://github.com/DarkSheepSoftware/node-packages/commit/b14b4af7278eca60156169155a98519985771270))

package/README.md

@@ -0,0 +1,191 @@
+# @darksheep/logger
+Log configuration for NodeJS repos
+
+This repo contains environment aware logging configurations for our NodeJS modules that use Winston.
+
+This can be added using `yarn add @darksheep/logger` how ever you require a valid npm token for github packages!
+
+### Quick start
+#### Get something logging:
+```js
+const { createLogger } = require('@darksheep/logger');
+const logger = createLogger('some-identifier');
+
+logger.info('something');
+```
+For ESM
+```js
+import { createLogger } from '@darksheep/logger';
+const logger = createLogger('some-identifier');
+
+logger.info('something');
+```
+
+### Utilities
+#### `.context(context: Object, filterLevel?: string)`
+This will make a new logger instance combining the old context with the context provided.
+In the event that `filterLevel` is provided the context may be dropped using the same logic as normal logs.
+
+#### `.channel(channel: string)`
+This will make a new logger with the new specifyed channel. for example:
+```js
+logger.info('something')
+// INFO: something
+logger.channel('somewhere').info('test');
+// somewhere.INFO: test
+```
+
+#### `.trail(?string)`
+This will make a new logger for following a specific request though routers, for example:
+
+```js
+const app = express()
+
+app.use((request, response, next) => {
+    request.logger = logger.trail();
+    return next();
+});
+
+app.get('/', (request, response) => {
+    request.logger.warning('I logged a thing');
+    response.send('I sent a thing');
+});
+```
+
+### Environment variables:
+| Environment variable | Description |
+| --- | --- |
+| `NODE_ENV` | The deployment location |
+| `LOG_LEVEL` | Overrides the log level set by the detected environment |
+| `LOG_FILTERS` | This allows you to allow/block specific channels |
+| `LOG_SECRETS` | This allows you to hide or remove secrets in an object |
+| `LOG_CALLSITES` | Include the callsite of the log |
+
+#### `NODE_ENV`
+
+| Value | Formatter | Level |
+| --- | --- | --- |
+| `development` | `console` | `debug` |
+| `test` | `json` | `warning` |
+| `production` | `json` | `info` |
+
+#### `LOG_LEVEL`
+
+Allowed values:
+- `critical` or `crit`
+- `error`
+- `warning` or `warn`
+- `notice`
+- `info`
+- `debug` or `verbose`
+- `silly`
+
+#### `LOG_FILTERS`
+
+This allows you to filter specific channels from the logs.
+Filters are separated by commas, and negative filters are marked using a leading `-`.
+
+Special characters:
+| Character | Meaning |
+| :-: | :-- |
+| `.` | Channel separator |
+| `+` | One level channel wildcard |
+| `*` | Multi level channel wildcard |
+
+The following filter means that all calls to the `router` channel will be removed.
+
+```shell
+LOG_FILTERS="-router"
+```
+
+The following filter means that ONLY `router` gets logged
+
+```shell
+LOG_FILTERS="router"
+```
+
+The following filter means that ONLY `router` gets logged, except for the `router.ok` message.
+
+```shell
+LOG_FILTERS="router,-router.ok"
+```
+
+#### `LOG_SECRETS`
+
+Secrets also use a filter, if you use a standard filter the secret key is displayed, if you use a negate the key and value are deleted.
+
+The following means that `password` is deleted, and `token` is obscured.
+
+```js
+// LOG_SECRETS="-password,token"
+
+// Given the following context
+const context = {
+  password: '1234',
+  token: 'asdf',
+};
+
+// Then the following will be logged
+const output = {
+  token: '[secret #/token]'
+};
+```
+
+Wild cards are also permitted.
+
+For example, using a positive (obscure) wildcard
+
+```js
+// LOG_SECRETS="*.token"
+
+// Given the following context
+const context = {
+  user: {
+    id: '1234',
+    token: 'asdf',
+  },
+  api: {
+    name: 'fred',
+    token: 'asdf',
+  }
+};
+
+// Then the following will be logged
+const output = {
+  user: {
+    id: '1234',
+    token: '[secret #/user/token]'
+  },
+  api: {
+    name: 'fred',
+    token: '[secret #/api/token]'
+  }
+};
+```
+
+For example, using a negative (delete) wildcard:
+```js
+// LOG_SECRETS="-*.token"
+
+// Given the following context
+const context = {
+  user: {
+    id: '1234',
+    token: 'asdf',
+  },
+  api: {
+    name: 'fred',
+    token: 'asdf',
+  }
+};
+
+// Then the following will be logged
+const output = {
+  user: { id: '1234' },
+  api: { name: 'fred' }
+};
+```
+
+#### `LOG_CALLSITES`
+
+This is simply a boolean to indicate whether or not the location of the place calling the log should be added to the context

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@darksheep/logger",
+  "version": "1.0.0",
+  "description": "Logging your stuff to where ever you want it",
+  "license": "UNLICENCED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "types",
+    "!*.test.js",
+    "!assert.zod.js"
+  ],
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "prepack": "tsc",
+    "test": "node --test src/**/*.test.js",
+    "test:watch": "node --watch --test src/**/*.test.js"
+  },
+  "dependencies": {
+    "deepmerge-ts": "7.0.3",
+    "stacktrace-parser": "0.1.10",
+    "traverse": "0.6.9"
+  },
+  "devDependencies": {
+    "@darksheep/eslint": "~4.4.0",
+    "@types/eslint": "~8.56.0",
+    "@types/node": "~20.14.0",
+    "@types/traverse": "~0.6.33",
+    "eslint": "~9.6.0",
+    "nock": "~13.5.0",
+    "typescript": "~5.5.0",
+    "zod": "~3.23.0"
+  },
+  "engines": {
+    "node": "^20.13.1 || ^22.2.0"
+  }
+}

package/src/create-logger.js

@@ -0,0 +1,36 @@
+import { Logger } from './logger.js';
+
+import {
+  SecretDelete,
+  SecretObscure,
+  BufferReplacer,
+  ErrorReplacer,
+  HttpClientRequestReplacer,
+  HttpIncomingMessageReplacer,
+  HttpServerResponseReplacer,
+  LongStringReplacer,
+  NetSocketReplacer,
+} from './replacers/index.js';
+
+/**
+ * @param {string} [channel] The logging channel
+ * @returns {import('./logger.js').Logger}
+ */
+export function createLogger(channel) {
+  return new Logger(
+    typeof channel === 'string' ? { channel } : {},
+    { replacers: [
+      // Always run the secret replacer first.
+      SecretDelete,
+      SecretObscure,
+
+      ErrorReplacer,
+      HttpClientRequestReplacer,
+      HttpIncomingMessageReplacer,
+      HttpServerResponseReplacer,
+      LongStringReplacer,
+      NetSocketReplacer,
+      BufferReplacer,
+    ] },
+  );
+}

package/src/formatter.js

@@ -0,0 +1,14 @@
+import { environment } from './utilities/environment.js';
+import { formatterJson } from './formatters/formatter-json.js';
+import { formatterConsole } from './formatters/formatter-console.js';
+
+const isConsole = (
+  process.stdout.isTTY === true &&
+  environment.isDevelopment === true
+);
+
+/**
+ * @typedef {(logEntry: import('./utilities/log-types.js').LogEntry) => string} Formatter
+ */
+/** @type {Formatter} */
+export const formatter = isConsole === true ? formatterConsole : formatterJson;

package/src/formatters/formatter-console.js

@@ -0,0 +1,243 @@
+import { inspect } from 'node:util';
+import { LogNames } from '../utilities/log-types.js';
+import { colourString, shouldColour } from '../utilities/colour.js';
+
+/** @typedef {import('../utilities/log-types.js').LogContext} LogContext */
+/** @typedef {import('../utilities/log-types.js').LogEntry} LogEntry */
+/** @typedef {import('../utilities/log-types.js').LogLevel} LogLevel */
+/** @typedef {import('../utilities/log-types.js').Callsite} Callsite */
+
+/**
+ * @param {string} [channel] The channel string
+ * @param {LogLevel} [level] The LogLevel number
+ * @returns {string}
+ */
+function flattenChannelLevel(channel, level) {
+  let output = '';
+
+  if (channel == null && level == null) {
+    return output;
+  }
+
+  if (channel != null) {
+    output += channel;
+  }
+
+  if (channel != null && level != null) {
+    output += '.';
+  }
+
+  if (level != null) {
+    output += `${LogNames[level].toUpperCase()}`;
+  }
+
+  output += ': ';
+
+  return output;
+}
+
+/**
+ * @param {string} _match The whole match
+ * @param {string} type The module type
+ * @param {string} name The module name
+ * @returns {string}
+ */
+function underlineName(_match, type, name) {
+  const moduleName = colourString(name, { effects: [ 'underline' ] });
+
+  return `${type}${moduleName}`;
+}
+
+/**
+ * @param {Callsite} callsite The callsite to underline
+ * @returns {string}
+ */
+function formatFileSegment(callsite) {
+  let { file } = callsite;
+
+  file = file
+    .replace(/^((?:node:)?internal\/)([^/]+)/g, underlineName)
+    .replace(/^(\w+:)([a-z]\w+)$/g, underlineName)
+    .replace(/(node_modules\/)(@[^/]+\/[^/]+|[^/]+)/g, underlineName);
+
+  if (typeof callsite.line === 'number') {
+    file += `:${callsite.line}`;
+  }
+
+  if (typeof callsite.column === 'number') {
+    file += `:${callsite.column}`;
+  }
+
+  return file;
+}
+
+/**
+ * @param {Callsite} callsite The node module callsite to format
+ * @returns {string}
+ */
+function stackLineModule(callsite) {
+  const file = colourString(
+    formatFileSegment(callsite),
+    { effects: [ 'faint' ] },
+  );
+
+  return colourString(
+    `at ${callsite.methodName} (${file})`,
+    { foreground: 'yellow' },
+  );
+}
+
+/**
+ * @param {Callsite} callsite The internal callsite to format
+ * @returns {string}
+ */
+function stackLineInternal(callsite) {
+  const file = formatFileSegment(callsite);
+  return colourString(
+    `at ${callsite.methodName} (${file})`,
+    { foreground: 'black', foregroundMode: 'bright' },
+  );
+}
+
+/**
+ * @param {Callsite} callsite The callsite to format
+ * @returns {string}
+ */
+function stackLine(callsite) {
+  if (callsite.file.startsWith('node_modules')) {
+    return stackLineModule(callsite);
+  }
+
+  if (
+    callsite.file === '<anonymous>' ||
+    callsite.file.startsWith('node:') ||
+    callsite.file.startsWith('internal')
+  ) {
+    return stackLineInternal(callsite);
+  }
+
+  let file = colourString(callsite.file, {
+    foreground: 'green',
+    foregroundMode: 'bright',
+  });
+
+  file += `:${callsite.line}`;
+  if (typeof callsite.column === 'number') {
+    file += colourString(
+      `:${callsite.column}`,
+      { foreground: 'black', foregroundMode: 'bright' },
+    );
+  }
+
+  return `at ${callsite.methodName} (${file})`;
+}
+
+const fixEmpties = /^\{\s*\}$/;
+
+/**
+ * @param {LogContext} entry The entry we're going to convert
+ * @returns {string}
+ */
+function splatify(entry) {
+  const object = { ...entry };
+
+  delete object.timestamp;
+  delete object.channel;
+  delete object.level;
+  delete object.type;
+  delete object.message;
+  delete object.stack;
+  delete object.cause;
+
+  return inspect(object, {
+    colors: shouldColour(),
+    getters: true,
+    depth: null,
+  })
+    .replace(fixEmpties, '')
+    .trim();
+}
+
+/**
+ * @param {Callsite[] | string | undefined} stack The stack trace to format
+ * @param {number} indent The indent to render from
+ * @returns {string}
+ */
+function formatStack(stack, indent) {
+  const pad = ' '.repeat(indent + 2);
+  if (Array.isArray(stack)) {
+    return stack
+      .map(stackLine)
+      .map((line) => `${pad}${line.trim()}`)
+      .join('\n');
+  }
+
+  return (stack ?? '')
+    .split(/\r?\n|\r/)
+    .map((line) => `${pad}${line.trim()}`)
+    .join('\n');
+}
+
+/**
+ * @param {Error} error The error to render
+ * @param {number} [indent] The indent to render from
+ * @returns {string}
+ */
+function formatError(error, indent = 0) {
+  const pad = ' '.repeat(indent);
+  let output = pad;
+
+  output +=
+    indent > 0
+      ? colourString(
+        error.message,
+        { foreground: 'red', effects: [ 'bold' ] },
+      )
+      : `${error.message}`;
+
+  const stack = formatStack(error.stack, indent);
+  if (stack.trim().length > 0) {
+    output += `\n${stack}`;
+  }
+
+  if (error?.cause != null) {
+    const cause = formatError(
+      /** @type {Error} */ (error?.cause),
+      indent + 2,
+    );
+    output += `\n${cause}`;
+  }
+
+  return output;
+}
+
+/**
+ * @param {LogEntry} logEntry the Log entry which we're going to convert to a splatted string
+ * @returns {string}
+ */
+export function formatterConsole(logEntry) {
+  const {
+    timestamp,
+    channel,
+    level,
+    message,
+    stack,
+    cause,
+    ...entry
+  } = logEntry;
+
+  let output = '';
+
+  if (timestamp instanceof Date) {
+    output += `[${timestamp.toISOString()}] `;
+  }
+
+  output += flattenChannelLevel(channel, level);
+
+  output += formatError(/** @type {Error} */ ({ message, stack, cause }));
+
+  const context = splatify(entry)
+    .replace(/\r?\n|\r/g, '\n  ');
+
+  return `${output}\n  ${context}`.trim();
+}

package/src/formatters/formatter-json.js

@@ -0,0 +1,7 @@
+/**
+ * @param {import('../utilities/log-types.js').LogEntry} logEntry the Log entry which we're going to convert to JSON
+ * @returns {string}
+ */
+export function formatterJson(logEntry) {
+  return JSON.stringify(logEntry);
+}

package/src/index.js

@@ -0,0 +1,25 @@
+import { createLogger } from './create-logger.js';
+
+/** @typedef {import('./utilities/log-types.js').LogContext} LogContext */
+/** @typedef {import('./utilities/log-types.js').LogEntry} LogEntry */
+/** @typedef {import('./utilities/log-types.js').LogLevel} LogLevel */
+/** @typedef {import('./formatter.js').Formatter} Formatter */
+/** @typedef {import('./replacer.js').Replacer} Replacer */
+
+export { Logger } from './logger.js';
+export const logger = createLogger();
+
+export { environment } from './utilities/environment.js';
+export { createLogger } from './create-logger.js';
+export { LogLevels } from './utilities/log-types.js';
+export {
+  SecretDelete,
+  SecretObscure,
+  BufferReplacer,
+  ErrorReplacer,
+  HttpClientRequestReplacer,
+  HttpIncomingMessageReplacer,
+  HttpServerResponseReplacer,
+  LongStringReplacer,
+  NetSocketReplacer,
+} from './replacers/index.js';