feat: Allow enabling/disabling debug logging via BravoClient methods,…

… allowing finer control over what gets logged.

README.md

@@ -301,7 +301,7 @@ To help diagnose problems in various contexts, Bravo provides a few useful mecha
 
 - **Custom Errors:** If you have a custom Error class you want to use instead of the Bravo one (e.g. if your error class is hooked up to your logging utilities), you can provide that class as an option when setting up your `BravoClient`.
 - **Custom Console:** If you have a custom drop-in replacement for Node's `console` object, you can also provide that object as an option when setting up your `BravoClient`. You can use this with custom loggers, or to divert logs to a file or other I/O mechanism.
-- **DEBUG:** In addition to regular logging (for warnings, errors, and info), you can get more verbose logging by setting the `DEBUG` environment variable. Bravo uses the popular [debug](https://www.npmjs.com/package/debug) package for this, with the following namespaces:
+- **DEBUG:** In addition to regular logging (for warnings, errors, and info), you can get more verbose logging by setting the `DEBUG` environment variable and/or by using `enableDebugLogging()` and `disableDebugLogging()` BravoClient methods. Bravo uses the popular [debug](https://www.npmjs.com/package/debug) package for this, with the following namespaces:
   - `bravo:*`: Everything below.
   - `bravo:http:*`: HTTP requests and responses (maximally verbose)
   - `bravo:http:basic`: HTTP requests and responses (simple summaries of requests and responses, like URLs, methods, and status codes)

src/lib/BravoClient.ts

@@ -33,6 +33,7 @@ import type { BravoEntity } from './BravoEntity.js';
 import type { FavroApi } from '$types/FavroApi.js';
 import { BravoWebhookDefinition } from './entities/BravoWebhook.js';
 import { BravoGroup } from '$/types/Bravo.js';
+import { DebugPath, Logger } from './Logger.js';
 
 export { FavroClientAuth as BravoClientAuth } from './clientLib/FavroClient.js';
 
@@ -80,6 +81,14 @@ export class BravoClient extends FavroClient {
     return new BravoResponseEntities(this, entityClass, res);
   }
 
+  enableDebugLogging(debugNamespace: DebugPath) {
+    Logger.enableDebug(debugNamespace);
+  }
+
+  disableDebugLogging() {
+    Logger.disableDebug();
+  }
+
   /** Get the hydrated Organization model that this client is using. */
   async getCurrentOrganization() {
     return findByField(

src/lib/Logger.ts

@@ -1,3 +1,4 @@
+import type { DebugPaths } from '$/types/ObjectPaths.js';
 import type { AnyFunction } from '$/types/Utility.js';
 import debug from 'debug';
 import { sortPaths } from './utility.js';
@@ -15,12 +16,35 @@ export type LoggerUtility = {
     [RequiredLoggerName in RequiredLogLevel]: AnyFunction;
   };
 
+export type DebugPath = DebugPaths<typeof Logger['debugHeirarchy']>;
+
 export class Logger {
   private static _debuggers: { [namePath: string]: debug.Debugger } = {};
   private static _utility: LoggerUtility = console;
 
   private static _debuggerPaths: Set<string> = new Set();
 
+  static get debugHeirarchy() {
+    return {
+      bravo: {
+        http: {
+          basic: null,
+          headers: null,
+          bodies: null,
+          stats: null,
+        },
+      },
+    } as const;
+  }
+
+  static enableDebug(debugNamespace: DebugPath) {
+    debug.enable(debugNamespace);
+  }
+
+  static disableDebug() {
+    debug.disable();
+  }
+
   /**
    * Always log something using the provided logging utility's `log` method,
    * without using `DEBUG` environment variable settings.

src/test/client.test.ts

@@ -191,6 +191,7 @@ describe('BravoClient', function () {
     }
     testWebhookSecret = await generateRandomString(32, 'base64');
     client.clearCache();
+    client.disableDebugLogging();
   });
 
   it('utility functions behave', async function () {
@@ -488,6 +489,7 @@ describe('BravoClient', function () {
       const newDescription = '# New Description\n\nHello!';
       const testDate = new Date();
       const tagName = 'totally-real-tag';
+      client.enableDebugLogging('bravo:http:*');
       let updateBuilder = testCard.createNewUpdateBuilder();
       updateBuilder
         .setName(newName)
@@ -505,6 +507,7 @@ describe('BravoClient', function () {
         .setDueDate(testDate)
         .archive();
       await testCard.update(updateBuilder);
+      client.disableDebugLogging();
       expect(testCard.detailedDescription).to.equal(newDescription);
       expect(testCard.name).to.equal(newName);
       let userAssignment = testCard.assignments.find(

src/types/ObjectPaths.ts

@@ -0,0 +1,59 @@
+type Prev = [
+  never,
+  0,
+  1,
+  2,
+  3,
+  4,
+  5,
+  6,
+  7,
+  8,
+  9,
+  10,
+  11,
+  12,
+  13,
+  14,
+  15,
+  16,
+  17,
+  18,
+  19,
+  20,
+  ...0[]
+];
+
+type Join<K, P, Sep extends string = ':'> = K extends string
+  ? P extends string
+    ? `${K}${'' extends P ? '' : Sep}${P}`
+    : never
+  : never;
+
+export type DebugPaths<T, Depth extends number = 10> = [Depth] extends [never]
+  ? never
+  : T extends Record<string, any>
+  ? {
+      [K in keyof T]-?: K extends string
+        ?
+            | (T[K] extends null ? `${K}` : `${K}:*`)
+            | Join<K, DebugPaths<T[K], Prev[Depth]>>
+        : never;
+    }[keyof T]
+  : '';
+
+// type Paths<T, Depth extends number = 10> = [Depth] extends [never]
+//   ? never
+//   : T extends Record<string, any>
+//   ? {
+//       [K in keyof T]-?: K extends string
+//         ? `${K}` | Join<K, Paths<T[K], Prev[Depth]>>
+//         : never;
+//     }[keyof T]
+//   : '';
+
+// type Leaves<T, D extends number = 10> = [D] extends [never]
+//   ? never
+//   : T extends Record<string, any>
+//   ? { [K in keyof T]-?: Join<K, Leaves<T[K], Prev[D]>> }[keyof T]
+//   : '';