[RFC]: Bringing the `debug` Dependency In-House
Maintainer antworten meist innerhalb von 1 Tag
Dieses Issue hat noch niemand übernommen.
Bewertung
- Schwierigkeit
- 5/5
- Geschätzter Aufwand
- Über eine Woche
- Anfängerfreundlichkeit
- 25/100
- Issue-Typ
- Feature
- Klarheit
- Größtenteils klar
- Aktivitätsstatus
- Ruhig
- Tech-Stack
- javascript, node.js
Rechercherichtung
Beginne damit, die vorgeschlagenen Paketlayouts von @stdlib/time/ms und @stdlib/console/debug zu prüfen, und untersuche anschließend die bestehende Verwendung von require('debug') in den aufgeführten Consumer-Bereichen. Führe die Befehle mit dem jeweiligen TESTS_FILTER aus, um die Konventionen des Projekts zu verstehen. Als abgeschlossen gilt die Aufgabe, wenn die Ersetzungen, Tests, Dokumentation und die phasenweise Migration vollständig sind und die vollständige Testsuite sowie die manuellen Prüfungen auf DEBUG-Basis erfolgreich sind.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Beschreibung
Bringing the debug Dependency In-House
Replacing the external debug npm package (v2.6.9) with stdlib-native equivalents to eliminate a supply-chain risk and align all production code with stdlib's quality standards (docs, tests, examples, benchmarks, backward compatibility).
A key improvement: the in-house replacement will leverage @stdlib/string/format for string interpolation, providing significantly richer formatting capabilities than the external debug package's limited %s/%d placeholders
Background
What debug v2.6.9 Does
A tiny JavaScript debugging utility modelled after Node.js core's debugging technique. Works in Node.js and web browsers.
More here: https://github.com/debug-js/debug
Its sole dependency
msv2.0.0: Converts milliseconds to/from human-readable strings (e.g.,1500→"1.5s"). Used only for the+1.5sdiff suffix in log output.
How stdlib uses it
- 680+ files across:
@stdlib/random/streams/*,@stdlib/plot/*,@stdlib/streams/*,@stdlib/math/base/special/*,@stdlib/fs/*,@stdlib/repl/*,@stdlib/_tools/*, and more. - Only the factory function is used:
var logger = require('debug'); var debug = logger('namespace');thendebug('message: %s.', val);. - No advanced API usage: none of the 680+ files call
enable(),disable(),enabled(), or register custom formatters.
Proposed Changes
The plan creates 2 new packages mirroring stdlib's decomposable architecture, with each package being independently consumable. The implementation leverages the existing @stdlib/string/format package for string interpolation for richer debug messages — e.g., debug( 'Value: %.6f, Index: %03d', 3.14, 7 ) → 'Value: 3.140000, Index: 007'
Component 1: @stdlib/time/ms
Replaces the
msnpm dependency (transitive viadebug).
A utility to convert between millisecond values and human-readable time strings.
Scope: Only the ms → string direction is needed by the debug logger (e.g., 1500 → "1.5s"). Optionally support string → ms for completeness.
@stdlib/time/ms/
├── lib/
│ ├── index.js # re-export main
│ └── main.js # ms(val) → string or number
├── test/
│ └── test.js
├── benchmark/
│ └── benchmark.js
├── docs/
│ ├── repl.txt
│ └── types/
│ ├── index.d.ts
│ └── test.ts
├── examples/
│ └── index.js
├── README.md
└── package.json
API:
var ms = require( '@stdlib/time/ms' );
ms( 1500 ); // => '1.5s'
ms( 60000 ); // => '1m'
ms( 3600000 ); // => '1h'
ms( 86400000 ); // => '1d'
ms( 500 ); // => '500ms'
Component 2: @stdlib/console/debug
The core package — the direct replacement for
require('debug').
A namespace-based diagnostic logging utility. This is the main factory function that all 680+ files will switch to.
@stdlib/console/debug/
├── lib/
│ ├── index.js # re-export main
│ ├── main.js # createDebug(namespace) factory (core logic)
│ ├── enable.js # enable(namespaces) — parse glob patterns
│ ├── disable.js # disable()
│ ├── enabled.js # enabled(name) → boolean
│ ├── format_args.js # environment-specific argument formatting
│ ├── colors.js # ANSI color selection (Node.js)
│ └── defaults.js # default options
├── test/
│ ├── test.js # main export tests
│ ├── test.enable.js # enable/disable/enabled tests
│ ├── test.format.js # format string placeholder tests
│ └── test.colors.js # color selection tests
├── benchmark/
│ ├── benchmark.js # benchmark: logger creation
│ └── benchmark.disabled.js # benchmark: no-op when disabled (perf)
├── docs/
│ ├── repl.txt
│ └── types/
│ ├── index.d.ts
│ └── test.ts
├── examples/
│ └── index.js
├── README.md
└── package.json
API (drop-in compatible with current usage):
var logger = require( '@stdlib/console/debug' );
// Create a namespaced logger:
var debug = logger( 'sparkline:unicode:main' );
// Log messages (no-op when disabled):
debug( 'Creating an instance with config: %s.', JSON.stringify( opts ) );
debug( 'Current value: %s.', this._yMin );
// Now with richer formatting via @stdlib/string/format:
debug( 'Computed value: %.6f at index %03d.', 3.14159, 7 );
debug( 'Hex: %x, Binary: %b, Octal: %o.', 255, 255, 255 );
debug( 'Padded: %10s | %-10s.', 'right', 'left' );
// Programmatic control (used internally, not by consumers):
logger.enable( 'sparkline:*' );
logger.disable();
logger.enabled( 'sparkline:unicode:main' ); // => true/false
Key implementation details:
- Reads
DEBUGenv var (Node.js) orlocalStorage.debug(browser) on load - Supports glob patterns:
*matches any characters,-prefix excludes - When disabled (the default), the function is a no-op with zero cost (early return)
- Format placeholders:
%s(string),%d(number),%o(inspect compact),%O(inspect multiline),%j(JSON),%%(escaped %) - ANSI colors in Node.js via deterministic namespace hashing
- Appends
+Xmsdiff timestamp between successive calls - Output target:
stderrin Node.js,console.login browsers - Internal dependencies only:
@stdlib/string/format,@stdlib/time/ms
Component 3: Migration — Updating All Consumers
This is the mechanical bulk change, done after the new packages are created and verified.
[MODIFY] All 680+ files using require( 'debug' )
There are two primary usage patterns across the codebase:
-
Pattern 1: Dedicated Wrapper Files (53 Packages) Files like
@stdlib/random/streams/arcsine/lib/debug.jswhose sole purpose is to initialize and export a namespaced logger. -
Pattern 2: Direct Imports (645 Files) Implementation files like
@stdlib/fs/read-file-list/lib/async.jsthat import the utility directly alongside other modules.
In both patterns, only a single line changes:
-var logger = require( 'debug' );
+var logger = require( '@stdlib/console/debug' );
Migration strategy ((phased to account for both patterns)::
| Phase | Scope | Files |
|---|---|---|
| Phase 1 | @stdlib/random/streams/* |
~200 files (all have identical debug.js pattern) |
| Phase 2 | @stdlib/plot/* and @stdlib/streams/* |
~150 files |
| Phase 3 | @stdlib/math/base/special/* |
~100 files |
| Phase 4 | @stdlib/fs/*, @stdlib/repl/*, @stdlib/_tools/*, and remaining |
~200+ files |
Each phase follows the same process:
- Run
find+sedto replacerequire( 'debug' )→require( '@stdlib/console/debug' ) - Run existing tests for the affected module area
- Verify with
DEBUG='*' node <example>that output matches current behavior
Uninstall the dependancy
After all phases are complete:
npm uninstall debug
Verification Plan
Automated Tests
1. Unit tests for @stdlib/time/ms
make TESTS_FILTER=".*/time/ms/.*" test
Tests should cover:
- Millisecond → string conversion for all ranges (ms, seconds, minutes, hours, days)
- Edge cases: 0, negative values, Infinity, NaN
- Type validation: non-numeric input throws
2. Unit tests for @stdlib/console/debug
make TESTS_FILTER=".*/console/debug/.*" test
Tests should cover:
- Factory returns a function
- Logger is a no-op when
DEBUGis unset - Logger outputs when
DEBUGmatches namespace enable()/disable()/enabled()work correctly- Glob matching:
*,-prefixexclusion, multiple comma-separated patterns - Format strings are processed via
@stdlib/string/format(all specifiers:%s,%d,%f,%e,%x,%b, etc.) - Width/precision/flags are correctly passed through (e.g.,
%.2f,%05d,%-10s) - Color assignment is deterministic per namespace
- Diff timestamp is appended
3. Regression tests for migrated modules
Run the full test suite for each phase:
# Phase 1:
make TESTS_FILTER=".*/random/streams/.*" test
# Phase 2:
make TESTS_FILTER=".*/plot/.*" test
make TESTS_FILTER=".*/streams/.*" test
# Phase 3:
make TESTS_FILTER=".*/math/base/special/.*" test
# Phase 4: Full suite
make test
Manual Verification
After migration, verify that debug output works end-to-end:
-
Create a test script that uses
@stdlib/random/streams/t(or any migrated module) -
Run without
DEBUG:node test_script.js→ Verify: no debug output appears (silent by default)
-
Run with
DEBUG:DEBUG='random:streams:*' node test_script.js→ Verify: colored namespace-prefixed debug messages appear on stderr, with
+Xmsdiff timestamps -
Run with exclusion:
DEBUG='*,-random:*' node test_script.js→ Verify: excluded namespaces produce no output
- Vorherrschende Sprache
- JavaScript
- Sterne
- 6k
- Forks
- 1.3k
- Ø Merge
- 1 T. 21 Std.
- Gemergte PRs (30 T.)
- 224
Entwicklungsumgebung
Startet den Dev-Container des Projekts im Browser, mit Ihrem eigenen GitHub-Konto.
- Kein Dockerfile und keine Docker-Compose-Datei
- Hat eine Pull-Request-Vorlage
- Beitragsleitfaden lesen
Erste Schritte
- Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
- Forken Sie das Repository und arbeiten Sie in einem Branch.
- Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.
Mehr aus stdlib-js/stdlib
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 72/100
stdlib-js/stdlib#16655 · 1 Kommentar ·
Maintainer antworten meist innerhalb von 1 Tag
-
Fix JavaScript lint errorsEvtl. vergeben @protestershankar hat das vor 5 Tagen übernommen. OffenGood First Issue
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 82/100
stdlib-js/stdlib#16563 · 3 Kommentare ·
Maintainer antworten meist innerhalb von 1 Tag
-
Fix C lint errorsEvtl. vergeben @raus7n hat das vor 14 Tagen übernommen. OffenGood First Issue
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 82/100
stdlib-js/stdlib#16454 · 1 Kommentar ·
Maintainer antworten meist innerhalb von 1 Tag
-
Fix JavaScript lint errorsEvtl. vergeben @Devansh-18155 hat das vor 39 Tagen übernommen. OffenGood First Issue
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 82/100
stdlib-js/stdlib#15970 · 1 Kommentar ·
Maintainer antworten meist innerhalb von 1 Tag
-
Fix JavaScript lint errorsEvtl. vergeben @lb1192176991-lab hat das vor 44 Tagen übernommen. OffenGood First Issue
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 90/100
stdlib-js/stdlib#15831 · 2 Kommentare ·
Maintainer antworten meist innerhalb von 1 Tag
Alle Issues in stdlib-js/stdlib
Ähnliche Issues
-
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 69/100
Maintainer antworten meist innerhalb von 1 Tag
-
automation chore ci-cd consistency developer-experience difficulty: easy discoverability documentation enhancement github-actions good first issue help wanted hygiene priority: P3 seo shell yaml
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 76/100
-
bug
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 84/100
swc-project/swc-next-issues#394 ·
-
Schwierigkeit 1/5 1-3 Stunden Anfängerfreundlichkeit 88/100
githubnext/gh-aw-workshop#5790 ·
Maintainer antworten meist innerhalb von 1 Tag
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 68/100
adobe/helix-tools-website#480 ·
Maintainer antworten meist innerhalb von 1 Tag