doc, include ms

Author: nichoth

.github/workflows/nodejs.yml

@@ -10,10 +10,10 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18.x]
+        node-version: [22.x]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
     - name: Use Node.js ${{ matrix.node-version }}
       uses: actions/setup-node@v4
       with:

README.md

@@ -1,5 +1,5 @@
 # debug
-![tests](https://github.com/substrate-system/debug/actions/workflows/nodejs.yml/badge.svg)
+[![tests](https://img.shields.io/github/actions/workflow/status/substrate-system/debug/nodejs.yml?style=flat-square)](https://github.com/substrate-system/debug/actions/workflows/nodejs.yml)
 [![module](https://img.shields.io/badge/module-ESM-blue?style=flat-square)](README.md)
 [![types](https://img.shields.io/npm/types/@substrate-system/debug?style=flat-square)](README.md)
 [![semantic versioning](https://img.shields.io/badge/semver-2.0.0-blue?logo=semver&style=flat-square)](https://semver.org/)
@@ -8,15 +8,15 @@
 
 
 A tiny JavaScript debugging utility that works in Node.js and browsers.
-Use environment variables to control logging, so there are no ridiculous
-console log statements in production.
+Use environment variables to control logging in Node.js, and localStorage
+to control logging in browsers, so there are no ridiculous console log 
+statements in production.
 
 This is based on [debug](https://github.com/debug-js/debug).
 It's been rewritten to use contemporary JS.
 
-In the browser, this should work well with [vite](https://vite.dev/). As is
-convention, this will look for an env variable prefixed with `VITE_`. So pass
-env variables like `VITE_DEBUG="foo"`.
+In the browser, this uses localStorage to control debug output.
+In Node.js, it uses the environmen variable `DEBUG`.
 
 **Featuring:**
 * Use [exports](https://github.com/substrate-system/debug/blob/main/package.json#L31)
@@ -30,154 +30,116 @@ generated by typescript.
 
 <!-- toc -->
 
+- [Install](#install)
 - [Browser](#browser)
-- [config](#config)
-  * [namespace](#namespace)
-  * [NODE_ENV + Vite](#node_env--vite)
-- [install](#install)
 - [Node JS](#node-js)
-  * [NODE_ENV](#node_env)
-- [develop](#develop)
+- [Config](#config)
+  * [Namespace](#namespace)
+  * [Enable all namespaces](#enable-all-namespaces)
+  * [Enable specific namespaces](#enable-specific-namespaces)
+  * [Force logging with boolean true](#force-logging-with-boolean-true)
+- [Develop](#develop)
   * [browser](#browser)
-- [test](#test)
-  * [node](#node)
+- [Test](#test)
+  * [Node](#node)
 
 <!-- tocstop -->
 
-## Browser
-
-In the browser, this will look for `VITE_DEBUG` import.meta variable,
-and `DEBUG` in `localStorage`.
-
-```js
-import Debug from '@substrate-system/debug'
-
-localStorage.setItem('DEBUG', 'browser:123')
+## Install
 
-const debug = Debug('browser:*')
-
-debug('hello logs')
-// will log, b/c DEBUG in localStorage is browser:123
+```sh
+npm i -D @substrate-system/debug
 ```
 
+**Browser usage**: Use `localStorage` `DEBUG` key.
+**Node.js usage**: Use environment variable `DEBUG`.
 
-## config
-
-### namespace
-Works with `vite` or other systems. This will look at `import.meta.env`, or
-an arbitrary object you can pass in, or `localStorage` in the browser.
-
-```js
-import Debug from '@substrate-system/debug'
-
-// look at `import.meta.env.VITE_DEBUG`
-const debug = Debug('example')
-
-// or call with your own env object
-const debug = Debug('example', { DEBUG: 'example' })
-```
+## Browser
 
-If you create an instance without passing in a `namespace` string, then this
-will log iff anything other than `false` is passed as an argument.
+In the browser, this looks for the `DEBUG` key in `localStorage`.
 
 ```js
 import Debug from '@substrate-system/debug'
 
-// log b/c we are not calling with `false`
-const debug = Debug()
+// Set DEBUG in localStorage
+localStorage.setItem('DEBUG', 'myapp:*')
 
-debug('hello')
+const debug = Debug('myapp:component')
+debug('hello logs')
+// will log, because DEBUG in localStorage matches 'myapp:*'
 ```
 
-You can use any variable as debug status:
+## Node JS
+Run your script with an env variable, `DEBUG`.
 
 ```js
-import Debug from '@substrate-system/debug'
-
-// in Vite
-const debug = Debug(!!(import.meta.env && import.meta.env.DEV))
-
-// in an arbitrary server
-const debug = Debug(window.EXAMPLE_DEBUG_MODE)
+// in node JS
+import createDebug from '@substrate-system/debug/node'
+const debug = createDebug('fooo')
+debug('testing')
 ```
 
-Use an env variable of `*` to log everything.
-
-
-### NODE_ENV + Vite
-
-Build the site with a `NODE_ENV` variable to set `import.meta.env.DEV`:
-
+Call this with an env var of `DEBUG=fooo`
 ```sh
-NODE_ENV=development vite build
+DEBUG=fooo node ./test/fixture/node.js
 ```
 
-Any value of `NODE_ENV`, except `production`, wil equate to
-`import.meta.env.DEV` being true.
+## Config
 
-```sh
-NODE_ENV=staging vite build
-```
+### Namespace
+In browsers, this checks `localStorage` for `DEBUG` key. In Node.js, this checks
+the environment variable `DEBUG`.
 
-----------------------------------------------------------------------
+```js
+import Debug from '@substrate-system/debug'
 
-## install
+// In browser: checks localStorage.getItem('DEBUG')
+const debug = Debug('example')
 
-```sh
-npm i -D @substrate-system/debug
+// Log if no namespace is set in localStorage
+const debug = Debug(import.meta.env.DEV)
 ```
 
-Use this with [vite](https://vitejs.dev/) in the [browser](#browser), or
-in [node](#node-JS).
-
-
-------------------------------------------------------------------
-
-
-## Node JS
-Run your script with an env variable, `DEBUG`.
+### Enable all namespaces
 
 ```js
-// in node JS
-import createDebug from '@substrate-system/debug/node'
-const debug = createDebug('fooo')
-debug('testing')
+localStorage.setItem('DEBUG', '*')
 ```
 
-Call this with an env var of `DEBUG=fooo`
-```sh
-DEBUG=fooo node ./test/fixture/node.js
+### Enable specific namespaces
+```js
+localStorage.setItem('DEBUG', 'myapp:auth,myapp:api')
 ```
 
-### NODE_ENV
-If you are in dev mode (`process.env.NODE_ENV === 'development'`), then this will log things in a random color if you don't initialize it with a namespace --
+### Force logging with boolean true
+
+You can also pass `true` to force logging regardless of `localStorage`.
+For example, in Vite, this will log on your localhost server, but not
+in production:
 
 ```js
-import createDebug from '@substrate-system/debug'
-const debug = createDebug()
-debug('hello')
+const debug = Debug(import.meta.env.DEV)
+debug('This logs')
 ```
 
-Run the script like this:
-```sh
-NODE_ENV=development node ./my-script.js
-```
+------------------------------------------------------------------
 
--------------------------------------------------------------------
 
-## develop
+## Develop
 
 ### browser
-Start a `vite` server and log some things. This uses [the example directory](./example/).
+Start a `vite` server and log some things. This uses
+[the example directory](./example/).
 
 ```sh
 npm start
 ```
 
 
-## test
+## Test
+
+### Node
 
-### node
 Run tests:
 
 ```sh

example/index.ts

@@ -31,3 +31,11 @@ debug7('hello quxxx')
 const debug8 = Debug('foo-bar')
 
 debug8('hello eight')
+
+// testing boolean true - should always log regardless of localStorage
+const debugForced = Debug(true)
+debugForced('This should always log because we passed boolean true!')
+
+// testing boolean false - should return noop
+const debugNoop = Debug(false)
+debugNoop('This should never log because we passed boolean false!')

package.json

@@ -44,7 +44,6 @@
   },
   "dependencies": {
     "@substrate-system/util": "^0.1.19",
-    "ms": "2.1.3",
     "supports-color": "^10.0.0"
   },
   "devDependencies": {

src/browser/index.ts

@@ -15,33 +15,32 @@ export default createDebug
 /**
  * Check if the given namespace is enabled.
  * `namespace` is the name that is passed into debug.
- * Need to check it against the env var.
+ * `forcedEnabled` is a boolean that forces logging when true.
+ * Only checks localStorage for the DEBUG key, unless forced.
  */
-function isEnabled (
-    namespace:string,
-    env?:ImportMetaEnv|Record<string, string>
-):boolean {
+function isEnabled (namespace:string, forcedEnabled?:boolean):boolean {
+    // If explicitly forced to be enabled via boolean true
+    if (forcedEnabled === true) return true
+
     const DEBUG = localStorage.getItem('DEBUG')
-    if (
-        (env && (env.VITE_DEBUG === '*' || env.DEBUG === '*')) ||
-        DEBUG === '*'
-    ) return true
+
+    // Check for wildcard
+    if (DEBUG === '*') return true
 
     // if we were not called with a namespace
     if (namespace === 'DEV') {
         // We want to log iff there is no DEBUG variable.
-        if (!env || (!env.VITE_DEBUG && !DEBUG)) {
+        if (!DEBUG) {
             return true
         }
-
         return false
     }
 
-    env = env || {}
+    // No DEBUG variable set
+    if (!DEBUG) return false
 
-    if (!DEBUG && (!env || (!env.VITE_DEBUG && !env.DEBUG))) return false
-    const envVars = createRegexFromEnvVar(namespace)
-    return envVars.some(regex => regex.test(env.VITE_DEBUG || env.DEBUG || DEBUG))
+    const envVars = createRegexFromEnvVar(DEBUG)
+    return envVars.some(regex => regex.test(namespace))
 }
 
 /**
@@ -63,10 +62,10 @@ function logger (
     namespace:string,
     args:any[],
     { prevTime, color },
-    env?:Record<string, string>
+    forcedEnabled?:boolean
 ) {
     args = args || []
-    if (!isEnabled(namespace, env)) return
+    if (!isEnabled(namespace, forcedEnabled)) return
 
     // Set `diff` timestamp
     const curr = Number(new Date())
@@ -153,7 +152,7 @@ function formatArgs ({ diff, color, namespace, useColors }:{
         (useColors ? ' %c' : ' ') +
         args[0] +
         (useColors ? '%c ' : ' ') +
-        '+' + humanize(diff)
+        '+' + humanize(diff, {})
 
     if (!useColors) return
 
@@ -182,20 +181,24 @@ function formatArgs ({ diff, color, namespace, useColors }:{
     return args
 }
 
-function createDebug (namespace?:string|boolean, env?:Record<string, string>) {
+function createDebug (namespace?:string|boolean) {
     if (namespace === false) return noop
     const prevTime = Number(new Date())
     const color = selectColor(
         typeof namespace === 'string' ? namespace : generateRandomString(10),
         colors
     )
 
+    // Determine if this is a boolean true passed as the namespace
+    const forcedEnabled = namespace === true
+    const actualNamespace = typeof namespace === 'string' ? namespace : 'DEV'
+
     const debug:(...args:any[])=>void = function (...args:any[]) {
         return logger(
-            typeof namespace === 'string' ? namespace : 'DEV',
+            actualNamespace,
             args,
             { prevTime, color },
-            env
+            forcedEnabled
         )
     }