[RFC]: Bringing the `debug` Dependency In-House
Maintainer thường phản hồi trong vòng 1 ngày
Chưa có ai nhận issue này.
Đánh giá
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức phù hợp với người mới
- 25/100
- Loại issue
- Tính năng
- Độ rõ ràng
- Khá rõ ràng
- Mức độ hoạt động
- Ít trao đổi
- Công nghệ
- javascript, node.js
Hướng nghiên cứu
Bắt đầu bằng cách xem xét bố cục gói được đề xuất của @stdlib/time/ms và @stdlib/console/debug, sau đó kiểm tra việc sử dụng require('debug') hiện có trong các khu vực sử dụng được liệt kê. Chạy các lệnh TESTS_FILTER theo phạm vi tương ứng để hiểu các quy ước của dự án. Công việc được xem là hoàn tất khi các thay thế, kiểm thử, tài liệu và quá trình di chuyển theo giai đoạn đã hoàn thành, đồng thời toàn bộ bộ kiểm thử và các kiểm tra thủ công dựa trên DEBUG đều vượt qua.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
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
- Ngôn ngữ chính
- JavaScript
- Star
- 6k
- Fork
- 1.3k
- Merge trung bình
- 1 ngày 21 giờ
- Pull request đã merge (30 ngày)
- 224
Chuẩn bị môi trường
Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.
- Không có Dockerfile hay tệp Docker Compose
- Có mẫu pull request
- Đọc hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của stdlib-js/stdlib
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 72/100
stdlib-js/stdlib#16655 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Fix JavaScript lint errorsCó thể đã có người làm @protestershankar đã nhận 5 ngày trước. Đang mởGood First Issue
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 82/100
stdlib-js/stdlib#16563 · 3 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Fix C lint errorsCó thể đã có người làm @raus7n đã nhận 14 ngày trước. Đang mởGood First Issue
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 82/100
stdlib-js/stdlib#16454 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Fix JavaScript lint errorsCó thể đã có người làm @Devansh-18155 đã nhận 39 ngày trước. Đang mởGood First Issue
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 82/100
stdlib-js/stdlib#15970 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Fix JavaScript lint errorsCó thể đã có người làm @lb1192176991-lab đã nhận 44 ngày trước. Đang mởGood First Issue
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 90/100
stdlib-js/stdlib#15831 · 2 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
Tất cả issue của stdlib-js/stdlib
Issue tương tự
-
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 69/100
Maintainer thường phản hồi trong vòng 1 ngày
-
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
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 76/100
-
bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 84/100
swc-project/swc-next-issues#394 ·
-
Độ khó 1/5 1-3 giờ Mức phù hợp với người mới 88/100
githubnext/gh-aw-workshop#5790 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 68/100
adobe/helix-tools-website#480 ·
Maintainer thường phản hồi trong vòng 1 ngày