[RFC]: Bringing the `debug` Dependency In-House
メンテナーはふだん 1 日以内に返信
まだ誰も着手していません。
評価
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 初心者へのやさしさ
- 25/100
- issue の種類
- 機能追加
- 明瞭さ
- おおむね明確
- 活発さ
- 静か
- 技術スタック
- javascript, node.js
調査の方向性
まず、提案されている @stdlib/time/ms と @stdlib/console/debug のパッケージ構成を確認し、次に一覧にある利用側の領域全体で既存の require('debug') の使用箇所を調査します。プロジェクトの慣例を把握するため、対象を絞った TESTS_FILTER コマンドを実行します。置き換え、テスト、ドキュメント、段階的な移行が完了し、フルスイートと DEBUG ベースの手動チェックが通れば完了です。
索引モデルが issue の本文から書いたものです。
説明
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
- 主要言語
- JavaScript
- スター
- 6k
- フォーク
- 1.3k
- 平均マージ
- 1日 21時間
- マージ済み PR(30日)
- 224
環境構築
このプロジェクトの開発コンテナを、あなたの GitHub アカウントでブラウザ上に起動します。
- Dockerfile・Docker Compose ファイルなし
- プルリクエストのテンプレートあり
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
stdlib-js/stdlib のほかの issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
stdlib-js/stdlib#16655 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
Fix JavaScript lint errors対応中かも @protestershankar が 5 日前に担当しました。 オープンGood First Issue
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
stdlib-js/stdlib#16563 · コメント 3 件 ·
メンテナーはふだん 1 日以内に返信
-
Fix C lint errors対応中かも @raus7n が 14 日前に担当しました。 オープンGood First Issue
難易度 1/5 1時間未満 初心者へのやさしさ 82/100
stdlib-js/stdlib#16454 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
Fix JavaScript lint errors対応中かも @Devansh-18155 が 39 日前に担当しました。 オープンGood First Issue
難易度 1/5 1時間未満 初心者へのやさしさ 82/100
stdlib-js/stdlib#15970 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
Fix JavaScript lint errors対応中かも @lb1192176991-lab が 44 日前に担当しました。 オープンGood First Issue
難易度 1/5 1時間未満 初心者へのやさしさ 90/100
stdlib-js/stdlib#15831 · コメント 2 件 ·
メンテナーはふだん 1 日以内に返信
stdlib-js/stdlib の issue をすべて見る
似ている issue
-
難易度 1/5 1時間未満 初心者へのやさしさ 69/100
メンテナーはふだん 1 日以内に返信
-
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
難易度 1/5 1時間未満 初心者へのやさしさ 76/100
-
bug
難易度 2/5 1〜3時間 初心者へのやさしさ 84/100
swc-project/swc-next-issues#394 ·
-
難易度 1/5 1〜3時間 初心者へのやさしさ 88/100
githubnext/gh-aw-workshop#5790 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
adobe/helix-tools-website#480 ·
メンテナーはふだん 1 日以内に返信