snapshot of https://github.com/toeverything/AFFiNE.git (canary, 2026-09-16; blobs > 131072B omitted)

packages/common/debug/README.md

@@ -0,0 +1,3 @@
+# @affine/debug
+
+A common debug interface for packages in this repository.

packages/common/debug/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@affine/debug",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "debug": "^4.4.0"
+  },
+  "devDependencies": {
+    "@types/debug": "^4.1.12",
+    "vitest": "^4.1.8"
+  },
+  "version": "0.27.5"
+}

packages/common/debug/src/__tests__/index.spec.ts

@@ -0,0 +1,34 @@
+/**
+ * @vitest-environment happy-dom
+ */
+import { describe, expect, test, vi } from 'vitest';
+
+import { DebugLogger } from '..';
+
+describe('debug', () => {
+  test('disabled', () => {
+    const logger = new DebugLogger('test');
+    logger.enabled = false;
+    for (const level of ['debug', 'info', 'warn', 'error'] as const) {
+      const fn = vi.fn();
+      vi.spyOn(globalThis.console, level).mockImplementation(fn);
+      expect(logger.enabled).toBe(false);
+      expect(fn).not.toBeCalled();
+      logger[level]('test');
+      expect(fn, level).not.toBeCalled();
+    }
+  });
+
+  test('log', () => {
+    const logger = new DebugLogger('test');
+    logger.enabled = true;
+    for (const level of ['debug', 'info', 'warn', 'error'] as const) {
+      const fn = vi.fn();
+      vi.spyOn(globalThis.console, level).mockImplementation(fn);
+      expect(logger.enabled).toBe(true);
+      expect(fn).not.toBeCalled();
+      logger[level]('test');
+      expect(fn, level).toBeCalled();
+    }
+  });
+});

packages/common/debug/src/index.ts

@@ -0,0 +1,82 @@
+import debug from 'debug';
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const SESSION_KEY = 'affine:debug';
+
+if (typeof window !== 'undefined') {
+  const getSessionValue = (key: string) => {
+    try {
+      return sessionStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  };
+
+  const setSessionValue = (key: string, value: string) => {
+    try {
+      sessionStorage.setItem(key, value);
+    } catch {
+      // ignore if storage is not accessible (e.g., sandboxed renderer)
+    }
+  };
+
+  // enable debug logs if the URL search string contains `debug`
+  // e.g. http://localhost:3000/?debug
+  if (window.location.search.includes('debug')) {
+    // enable debug logs for the current session
+    // since the query string may be removed by the browser after navigations,
+    // we need to store the debug flag in sessionStorage
+    setSessionValue(SESSION_KEY, 'true');
+  }
+  if (getSessionValue(SESSION_KEY) === 'true') {
+    // enable all debug logs by default
+    debug.enable('*');
+    console.warn('Debug logs enabled');
+  }
+  if (BUILD_CONFIG.debug) {
+    debug.enable('*,-micromark');
+    console.warn('Debug logs enabled');
+  }
+}
+
+export class DebugLogger {
+  private readonly _debug: debug.Debugger;
+
+  constructor(namespace: string) {
+    this._debug = debug(namespace);
+  }
+
+  set enabled(enabled: boolean) {
+    this._debug.enabled = enabled;
+  }
+
+  get enabled() {
+    return this._debug.enabled;
+  }
+
+  debug(message: string, ...args: any[]) {
+    this.log('debug', message, ...args);
+  }
+
+  info(message: string, ...args: any[]) {
+    this.log('info', message, ...args);
+  }
+
+  warn(message: string, ...args: any[]) {
+    this.log('warn', message, ...args);
+  }
+
+  error(message: string, ...args: any[]) {
+    this.log('error', message, ...args);
+  }
+
+  log(level: LogLevel, message: string, ...args: any[]) {
+    this._debug.log = console[level].bind(console);
+    this._debug(`[${level.toUpperCase()}] ${message}`, ...args);
+  }
+
+  namespace(extra: string) {
+    const currentNamespace = this._debug.namespace;
+    return new DebugLogger(`${currentNamespace}:${extra}`);
+  }
+}

packages/common/debug/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.web.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "tsBuildInfoFile": "./dist/tsconfig.tsbuildinfo"
+  },
+  "include": ["./src"],
+  "references": []
+}