[RFC]: Bringing the `debug` Dependency In-House
Mantenedores costumam responder em até 1 dia
Ninguém assumiu esta issue ainda.
Avaliação
- Dificuldade
- 5/5
- Tempo estimado
- Mais de uma semana
- Facilidade para iniciantes
- 25/100
- Tipo de issue
- Funcionalidade
- Clareza
- Razoavelmente clara
- Status de atividade
- Pouca atividade
- Stack de tecnologia
- javascript, node.js
Direção de pesquisa
Comece revisando os layouts de pacote propostos para @stdlib/time/ms e @stdlib/console/debug e, em seguida, inspecione o uso existente de require('debug') nas áreas consumidoras listadas. Execute os comandos TESTS_FILTER com o escopo correspondente para entender as convenções do projeto. Considera-se concluído quando as substituições, os testes, a documentação e a migração em fases estiverem completos, e a suíte completa e as verificações manuais baseadas em DEBUG forem aprovadas.
Escrita pelo modelo de indexação a partir do texto da issue.
Descrição
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
- Linguagem predominante
- JavaScript
- Estrelas
- 6k
- Forks
- 1.3k
- Merge médio
- 1d 21h
- PRs com merge (30d)
- 224
Preparar o ambiente
Inicia o contêiner de desenvolvimento do projeto no navegador, com a sua própria conta do GitHub.
- Sem Dockerfile nem arquivo Docker Compose
- Tem um modelo de pull request
- Ler o guia de contribuição
Primeiros passos
- Leia a issue inteira e depois o guia de contribuição do projeto.
- Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
- Faça um fork do repositório e trabalhe em uma branch.
- Abra um pull request que referencie o número da issue.
Mais de stdlib-js/stdlib
-
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 72/100
stdlib-js/stdlib#16655 · 1 comentário ·
Mantenedores costumam responder em até 1 dia
-
Fix JavaScript lint errorsTalvez já em andamento @protestershankar assumiu há 5 dias. AbertaGood First Issue
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 82/100
stdlib-js/stdlib#16563 · 3 comentários ·
Mantenedores costumam responder em até 1 dia
-
Fix C lint errorsTalvez já em andamento @raus7n assumiu há 14 dias. AbertaGood First Issue
Dificuldade 1/5 Menos de uma hora Facilidade para iniciantes 82/100
stdlib-js/stdlib#16454 · 1 comentário ·
Mantenedores costumam responder em até 1 dia
-
Fix JavaScript lint errorsTalvez já em andamento @Devansh-18155 assumiu há 39 dias. AbertaGood First Issue
Dificuldade 1/5 Menos de uma hora Facilidade para iniciantes 82/100
stdlib-js/stdlib#15970 · 1 comentário ·
Mantenedores costumam responder em até 1 dia
-
Fix JavaScript lint errorsTalvez já em andamento @lb1192176991-lab assumiu há 44 dias. AbertaGood First Issue
Dificuldade 1/5 Menos de uma hora Facilidade para iniciantes 90/100
stdlib-js/stdlib#15831 · 2 comentários ·
Mantenedores costumam responder em até 1 dia
Todas as issues de stdlib-js/stdlib
Issues semelhantes
-
Dificuldade 1/5 Menos de uma hora Facilidade para iniciantes 69/100
Mantenedores costumam responder em até 1 dia
-
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
Dificuldade 1/5 Menos de uma hora Facilidade para iniciantes 76/100
-
bug
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 84/100
swc-project/swc-next-issues#394 ·
-
Dificuldade 1/5 1-3 horas Facilidade para iniciantes 88/100
githubnext/gh-aw-workshop#5790 ·
Mantenedores costumam responder em até 1 dia
-
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 68/100
adobe/helix-tools-website#480 ·
Mantenedores costumam responder em até 1 dia