Add logging functions

package.json

@@ -27,6 +27,7 @@
     "docs:publish": "typedoc --cleanOutputDir false --gitRevision \"v$(jq -r .version < ./package.json)\""
   },
   "dependencies": {
+    "debug": "^4.3.4",
     "fast-deep-equal": "^3.1.3",
     "superstruct": "^0.16.0"
   },
@@ -37,7 +38,8 @@
     "@metamask/eslint-config-jest": "^9.0.0",
     "@metamask/eslint-config-nodejs": "^9.0.0",
     "@metamask/eslint-config-typescript": "^9.0.1",
-    "@types/jest": "^26.0.13",
+    "@types/debug": "^4.1.7",
+    "@types/jest": "^28.1.7",
     "@typescript-eslint/eslint-plugin": "^4.21.0",
     "@typescript-eslint/parser": "^4.21.0",
     "eslint": "^7.23.0",
@@ -47,13 +49,14 @@
     "eslint-plugin-jsdoc": "^36.1.0",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^3.3.1",
-    "jest": "^26.4.2",
+    "jest": "^28.1.0",
     "prettier": "^2.2.1",
     "prettier-plugin-packagejson": "^2.2.11",
     "rimraf": "^3.0.2",
-    "ts-jest": "^26.3.0",
+    "stdio-mock": "^1.2.0",
+    "ts-jest": "^28.0.8",
     "typedoc": "^0.22.15",
-    "typescript": "^4.2.4"
+    "typescript": "~4.2.4"
   },
   "engines": {
     "node": ">=14.0.0"

src/index.ts

@@ -1,4 +1,5 @@
 export * from './collections';
 export * from './json';
+export * from './logging';
 export * from './misc';
 export * from './time';

src/logging.test.ts

@@ -0,0 +1,49 @@
+import { MockWritable } from 'stdio-mock';
+import { createProjectLogger, createModuleLogger } from './logging';
+
+describe('logging', () => {
+  beforeEach(() => {
+    jest.useFakeTimers({ now: new Date('2022-01-01') });
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  describe('createProjectLogger', () => {
+    it('returns an object that can be used for logging', () => {
+      const writer = new MockWritable();
+      const log = createProjectLogger('some-project');
+      log.log = writer.write.bind(writer);
+      log.enabled = true;
+      // Typecast: The Debugger type is wrong and does not include a `useColors`
+      // property.
+      (log as any).useColors = false;
+
+      log('Some message');
+
+      expect(writer.data()).toStrictEqual([
+        '2022-01-01T00:00:00.000Z metamask:some-project Some message',
+      ]);
+    });
+  });
+
+  describe('createModuleLogger', () => {
+    it('returns an object that can be used for logging', () => {
+      const writer = new MockWritable();
+      const projectLogger = createProjectLogger('some-project');
+      const log = createModuleLogger(projectLogger, 'some-module');
+      log.log = writer.write.bind(writer);
+      log.enabled = true;
+      // Typecast: The Debugger type is wrong and does not include a `useColors`
+      // property.
+      (log as any).useColors = false;
+
+      log('Some message');
+
+      expect(writer.data()).toStrictEqual([
+        '2022-01-01T00:00:00.000Z metamask:some-project:some-module Some message',
+      ]);
+    });
+  });
+});

src/logging.ts

@@ -0,0 +1,40 @@
+import debug, { Debugger } from 'debug';
+
+const globalLogger = debug('metamask');
+
+/**
+ * Creates a logger via the `debug` library whose log messages will be tagged
+ * using the name of your project. By default, such messages will be
+ * suppressed, but you can reveal them by setting the `DEBUG` environment
+ * variable to `metamask:<projectName>`. You can also set this variable to
+ * `metamask:*` if you want to see log messages from all MetaMask projects that
+ * are also using this function to create their loggers.
+ *
+ * @param projectName - The name of your project. This should be the name of
+ * your NPM package if you're developing one.
+ * @returns An instance of `debug`.
+ */
+export function createProjectLogger(projectName: string): Debugger {
+  return globalLogger.extend(projectName);
+}
+
+/**
+ * Creates a logger via the `debug` library which is derived from the logger for
+ * the whole project whose log messages will be tagged using the name of your
+ * module. By default, such messages will be suppressed, but you can reveal them
+ * by setting the `DEBUG` environment variable to
+ * `metamask:<projectName>:<moduleName>`. You can also set this variable to
+ * `metamask:<projectName>:*` if you want to see log messages from the project,
+ * or `metamask:*` if you want to see log messages from all MetaMask projects.
+ *
+ * @param projectLogger - The logger created via {@link createProjectLogger}.
+ * @param moduleName - The name of your module. You could use the name of the
+ * file where you're using this logger or some other name.
+ * @returns An instance of `debug`.
+ */
+export function createModuleLogger(
+  projectLogger: Debugger,
+  moduleName: string,
+): Debugger {
+  return projectLogger.extend(moduleName);
+}