From 9c2777c2ced3f66e3df19e8740862547fcfec9f8 Mon Sep 17 00:00:00 2001
From: Kevin Deng <sxzz@sxzz.moe>
Date: Wed, 12 Nov 2025 21:51:12 +0800
Subject: [PATCH] docs: add v2 design [ci skip]

---
 README.md       | 51 +++++++++++++++++++++++++++++++++++++++++++++++++
 src/types-v2.ts | 48 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 99 insertions(+)
 create mode 100644 src/types-v2.ts

diff --git a/README.md b/README.md
index 6367067..b49e845 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,11 @@
 
 A lightweight JavaScript debugging utility, forked from [debug](https://www.npmjs.com/package/debug), featuring TypeScript and ESM support.
 
+> [!NOTE]
+> obug v1 retains most of the compatibility with [debug](https://github.com/debug-js/debug), but drops support for older browsers and Node.js, making it a drop-in replacement.
+>
+> The upcoming v2 refactors some API imports and usage for better support of ESM and TypeScript, easier customization, and an even smaller package size.
+
 ## Key Differences from `debug`
 
 - ✨ Minimal footprint
@@ -26,6 +31,52 @@ npm install obug
 
 Please refer to the original [debug](https://github.com/debug-js/debug#usage) package for usage instructions.
 
+## Refactor Plan
+
+The obug package is currently a direct fork of the debug package with minimal modifications. The following refactor plan outlines the intended changes to be made in future releases.
+
+```ts
+import { createDebug, disable, enable, enabled, namespaces } from 'obug'
+
+// Get the currently enabled namespaces
+console.log(namespaces())
+
+// createDebug has no extra properties or methods.
+const debug = createDebug('my-namespace', {
+  // All options are optional
+
+  useColors: true, // false, true, 'auto'
+  color: 2, // custom color
+  // custom formatArgs
+  formatArgs(args) {},
+  formatters: {},
+  // Node.js only
+  inspectOpts: {},
+
+  // custom log
+  log: console.log,
+})
+
+debug('This is a debug message')
+console.log(
+  debug.namespace, // 'my-namespace'
+  debug.enabled, // Check if enabled
+  debug.useColors, // true
+  debug.color, // 2
+  debug.formatArgs, // custom formatArgs
+  debug.formatters, // {}
+  debug.inspectOpts, // {}
+  debug.log, // implemented log function
+)
+
+// Create a sub-namespace, and it will inherit options from the parent debugger
+const sub = debug.extend('sub-namespace')
+sub('This is a sub-namespace debug message')
+console.log(sub.namespace) // 'my-namespace:sub-namespace'
+```
+
+For more details, please refer to the [src/types-v2.ts](./src/types-v2.ts).
+
 ## Original Authors
 
 As obug is a fork of debug, we would like to acknowledge the original authors:
diff --git a/src/types-v2.ts b/src/types-v2.ts
new file mode 100644
index 0000000..24974bc
--- /dev/null
+++ b/src/types-v2.ts
@@ -0,0 +1,48 @@
+import type { InspectOptions as NodeInspectOptions } from 'node:util'
+
+/**
+ * Disable debug output.
+ */
+export declare function disable(): string
+/**
+ * Enables a debug mode by namespaces. This can include modes
+ * separated by a colon and wildcards.
+ */
+export declare function enable(namespaces: string): void
+/**
+ * Returns true if the given mode name is enabled, false otherwise.
+ */
+export declare function enabled(namespaces: string): boolean
+/**
+ * Returns an array of the currently enabled debug namespaces.
+ */
+export declare function namespaces(): string[]
+
+export interface InspectOptions extends NodeInspectOptions {
+  hideDate?: boolean
+}
+
+export interface Formatters {
+  [formatter: string]: (this: Debugger, v: any) => string
+}
+
+export interface Debugger extends Required<DebugOptions> {
+  (formatter: any, ...args: any[]): void
+
+  namespace: string
+  enabled: boolean
+
+  extend: (namespace: string, delimiter?: string) => Debugger
+}
+
+export interface DebugOptions {
+  useColors?: boolean
+  color?: string | number
+
+  formatArgs?: (this: Debugger, diff: number, args: [string, ...any[]]) => void
+  formatters?: Formatters
+  /** Node.js only */
+  inspectOpts?: InspectOptions
+
+  log?: (this: Debugger, ...args: any[]) => void
+}
-- 
2.51.2