@matheusvcouto/debug 1.0.3 → 1.0.4

package/README.md

@@ -1,11 +1,132 @@
 # @matheusvcouto/debug
 
-no description
+A simple, extensible, and type-safe debugging utility for TypeScript/JavaScript applications. It provides categorized logging and flexible control over debug output using tags and environment variables, supporting hierarchical namespaces.
 
-## Instalação
+## Features
+
+-   **Categorized Logging:** `log`, `warn`, `error`, `info`, `success` methods for different log levels.
+-   **Colored Output:** Automatically formats logs with colors for better readability in the console.
+-   **Tag-Based Control:** Enable or disable specific debug outputs using descriptive tags.
+-   **Hierarchical Namespaces:** Granular control over logs using a colon-separated namespace system (e.g., `API:FETCH` can be controlled by enabling `API`).
+-   **Environment Variable Integration:** Control which tags are active via a `DEBUG` environment variable.
+
+## Installation
+
+You can install `@matheusvcouto/debug` using your preferred package manager:
 
 ```bash
+# Using bun
 bun add @matheusvcouto/debug
-# ou
+
+# Using npm
 npm install @matheusvcouto/debug
+
+# Using yarn
+yarn add @matheusvcouto/debug
+```
+
+## Usage
+
+### Basic Example
+
+First, import `createDebug` and define your debug environment variable (e.g., `process.env.DEBUG`).
+
+```typescript
+// src/my-module.ts
+import { createDebug } from '@matheusvcouto/debug';
+
+// Define known tags for type safety and autocompletion
+const knownTags = ["API", "DB", "AUTH", "SERVICE:USER"] as const;
+
+// Initialize the debug utility.
+// The first argument is typically an environment variable (e.g., process.env.DEBUG)
+// The second argument is an array of known tags for type inference and autocompletion.
+const { debug, DEBUG } = createDebug(process.env.DEBUG || "", knownTags);
+
+// Create a debugger instance for a specific tag
+const apiDebug = debug("API");
+const userDebug = debug("SERVICE:USER");
+const authDebug = debug("AUTH");
+
+apiDebug.log("Starting API call...");
+userDebug.info("Fetching user data for ID:", 123);
+
+if (DEBUG.API) { // Check if a tag is enabled for conditional logic
+  apiDebug.success("API call completed successfully.");
+}
+
+authDebug.error("Authentication failed for user 'testuser'.");
+
+// Extending a debugger for sub-modules
+const dbDebug = debug("DB");
+const queryDebug = dbDebug.extend("QUERY"); // This creates a debugger for "DB:QUERY"
+
+queryDebug.log("Executing complex query...");
+```
+
+### Controlling Debug Output
+
+The output of your debug messages is controlled by the `DEBUG` environment variable.
+Separate multiple tags with commas. Use `*` to enable all tags.
+
+| `DEBUG` Value       | Description                                                | Example Output Enabled          |
+| :------------------ | :--------------------------------------------------------- | :------------------------------ |
+| `API`               | Enables logs only for the `API` tag.                       | `API`                           |
+| `API,AUTH`          | Enables logs for `API` and `AUTH` tags.                    | `API`, `AUTH`                   |
+| `API:*`             | Enables `API` and all its hierarchical children (e.g., `API:FETCH`, `API:AUTH`). | `API`, `API:FETCH`, `API:AUTH` |
+| `*`                 | Enables all debug tags.                                    | All                             |
+| (empty or undefined) | Disables all debug output.                                 | None                            |
+
+**Example of running your application with debug enabled:**
+
+```bash
+# On Linux/macOS
+DEBUG="API,DB:QUERY" bun run src/index.ts
+
+# On Windows (Command Prompt)
+set DEBUG=API,DB:QUERY && bun run src/index.ts
+
+# On Windows (PowerShell)
+$env:DEBUG="API,DB:QUERY"; bun run src/index.ts
+```
+
+### API Reference
+
+#### `createDebug(debugEnvVar: string, knownTags: readonly string[]): { debug: DebuggerFactory, DEBUG: TagStatus, isEnabled: (tag: string) => boolean }`
+
+-   `debugEnvVar`: A string usually sourced from an environment variable (e.g., `process.env.DEBUG`) that dictates which debug tags are enabled.
+-   `knownTags`: A `readonly` array of strings representing all known debug tags in your application. This is used for type inference and autocompletion.
+
+Returns an object containing:
+-   `debug`: A function to create `Debugger` instances for specific tags.
+-   `DEBUG`: A proxy object where you can check the enabled status of any tag (e.g., `if (DEBUG.API) { ... }`).
+-   `isEnabled`: A utility function to programmatically check if a given tag is enabled.
+
+#### `Debugger` Interface
+
+Each `Debugger` instance provides the following logging methods:
+
+-   `log(...args: any[]): void`
+-   `warn(...args: any[]): void`
+-   `error(...args: any[]): void`
+-   `info(...args: any[]): void`
+-   `success(...args: any[]): void`
+-   `extend(subtag: string): Debugger`: Creates a new `Debugger` instance with an extended tag (e.g., `debug("API").extend("FETCH")` results in `API:FETCH`).
+
+## Development
+
+This project uses `bun` for development and building.
+
+### Building the project
+
+```bash
+bun run build
+```
+
+This will compile the TypeScript source code into the `dist` directory and generate declaration files.
+
+### Running tests
+
+```bash
+bun test
 ```

package/index.js

@@ -1 +1 @@
-var{Deno:k}=globalThis,v=typeof k?.noColor==="boolean"?k.noColor:!1,w=!v;function Q(q,J){return{open:`\x1B[${q.join(";")}m`,close:`\x1B[${J}m`,regexp:new RegExp(`\\x1b\\[${J}m`,"g")}}function W(q,J){return w?`${J.open}${q.replace(J.regexp,J.open)}${J.close}`:q}function C(q){return W(q,Q([1],22))}function G(q){return W(q,Q([31],39))}function I(q){return W(q,Q([32],39))}function L(q){return W(q,Q([33],39))}function M(q){return W(q,Q([34],39))}function _(q){return W(q,Q([36],39))}var h=new RegExp(["[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]+)*|[a-zA-Z\\d]+(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)","(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TXZcf-nq-uy=><~]))"].join("|"),"g");var B="",F=0;function D(){let q=Date.now();if(q-F>=1000)B=new Date(q).toLocaleTimeString("pt-BR",{hour:"2-digit",minute:"2-digit",second:"2-digit"}),F=q;return B}function P(q,J){function Z(H,K){if(K.has("*"))return!0;let X=H.toUpperCase();if(K.has(X))return!0;let O=X.split(":");for(let z=1;z<O.length;z++){let Y=O.slice(0,z).join(":");if(K.has(Y))return!0}return!1}let $=new Set(q.split(",").map((H)=>H.trim().toUpperCase()).filter(Boolean)),R=new Proxy({},{get:(H,K)=>{if(typeof K!=="string")return!1;return Z(K,$)}});function j(H){let K=Z(H,$),X=(z)=>j(`${H}:${z}`);if(!K)return{log:()=>{},warn:()=>{},error:()=>{},info:()=>{},success:()=>{},extend:X};let O=(z,Y)=>{let S=`[${D()}]`,V=`[${H}]`,N=Y(z);return`${S} ${V} ${N}`};return{log:(...z)=>console.log(O("log",_),...z),warn:(...z)=>console.warn(O("warn",L),...z),error:(...z)=>console.error(O("error",(Y)=>G(C(Y))),...z),info:(...z)=>console.info(O("info",M),...z),success:(...z)=>console.log(O("success",I),...z),extend:X}}return{DEBUG:R,debug:j,isEnabled:(H)=>Z(H,$)}}export{P as createDebug};
+var{Deno:k}=globalThis,v=typeof k?.noColor==="boolean"?k.noColor:!1,w=!v;function Q(q,J){return{open:`\x1B[${q.join(";")}m`,close:`\x1B[${J}m`,regexp:new RegExp(`\\x1b\\[${J}m`,"g")}}function W(q,J){return w?`${J.open}${q.replace(J.regexp,J.open)}${J.close}`:q}function C(q){return W(q,Q([1],22))}function G(q){return W(q,Q([31],39))}function I(q){return W(q,Q([32],39))}function L(q){return W(q,Q([33],39))}function M(q){return W(q,Q([34],39))}function _(q){return W(q,Q([36],39))}var h=new RegExp(["[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]+)*|[a-zA-Z\\d]+(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)","(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TXZcf-nq-uy=><~]))"].join("|"),"g");var B="",F=0;function D(){let q=Date.now();if(q-F>=1000)B=new Date(q).toLocaleTimeString("pt-BR",{hour:"2-digit",minute:"2-digit",second:"2-digit"}),F=q;return B}function P(q,J){function Z(H,K){if(K.has("*"))return!0;let X=H.toUpperCase();if(K.has(X))return!0;let O=X.split(":");for(let z=1;z<O.length;z++){let Y=O.slice(0,z).join(":");if(K.has(Y))return!0}return!1}let $=new Set(q.split(",").map((H)=>H.trim().toUpperCase()).filter(Boolean)),R=new Proxy({},{get:(H,K)=>{if(typeof K!=="string")return!1;return Z(K,$)}});function j(H){let K=Z(H,$),X=(z)=>j(`${H}:${z}`);if(!K)return{log:()=>{},warn:()=>{},error:()=>{},info:()=>{},success:()=>{},extend:X};let O=(z,Y)=>{let S=`[${D()}]`,V=`[${H}]`,N=Y(z);return`${S} ${N} ${V}`};return{log:(...z)=>console.log(O("log",_),...z),warn:(...z)=>console.warn(O("warn",L),...z),error:(...z)=>console.error(O("error",(Y)=>G(C(Y))),...z),info:(...z)=>console.info(O("info",M),...z),success:(...z)=>console.log(O("success",I),...z),extend:X}}return{DEBUG:R,debug:j,isEnabled:(H)=>Z(H,$)}}export{P as createDebug};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matheusvcouto/debug",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "no description",
   "type": "module",
   "main": "./index.js",
@@ -26,6 +26,7 @@
   "author": "Matheus Couto",
   "license": "MIT",
   "repository": "",
+  "readme": "./README.md",
   "peerDependencies": {
     "typescript": "^5.7.0"
   }