{"id":27108643,"url":"https://github.com/e22m4u/js-debug","last_synced_at":"2025-10-09T04:42:07.771Z","repository":{"id":286358350,"uuid":"961178733","full_name":"e22m4u/js-debug","owner":"e22m4u","description":"Утилита вывода сообщений отладки для JavaScript","archived":false,"fork":false,"pushed_at":"2025-09-30T12:58:46.000Z","size":71,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-30T14:50:17.969Z","etag":null,"topics":["debugger","interpolation","javascript","logging","typescript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/e22m4u.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-05T23:30:45.000Z","updated_at":"2025-09-30T12:58:46.000Z","dependencies_parsed_at":"2025-06-01T09:35:36.007Z","dependency_job_id":"7b51c45d-4516-4588-8712-2649e6c762fd","html_url":"https://github.com/e22m4u/js-debug","commit_stats":null,"previous_names":["e22m4u/js-debug"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/e22m4u/js-debug","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e22m4u%2Fjs-debug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e22m4u%2Fjs-debug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e22m4u%2Fjs-debug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e22m4u%2Fjs-debug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/e22m4u","download_url":"https://codeload.github.com/e22m4u/js-debug/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e22m4u%2Fjs-debug/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000706,"owners_count":26082921,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debugger","interpolation","javascript","logging","typescript"],"created_at":"2025-04-06T22:21:34.240Z","updated_at":"2025-10-09T04:42:07.765Z","avatar_url":"https://github.com/e22m4u.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## @e22m4u/js-debug\n\nУтилита вывода сообщений отладки для JavaScript.\n      \n## Содержание\n\n* [Установка](#установка)\n* [Использование](#использование)\n* [Управление выводом](#управление-выводом)\n  * [Node.js: Переменная окружения DEBUG](#nodejs-переменная-окружения-debug)\n  * [Браузер: localStorage.debug](#браузер-localstoragedebug)\n  * [Синтаксис паттернов](#синтаксис-паттернов)\n* [Класс Debuggable](#класс-debuggable)\n* [Тесты](#тесты)\n* [Лицензия](#лицензия)\n\n## Установка\n\n```bash\nnpm install @e22m4u/js-debug\n```\n\nПоддержка ESM и CommonJS стандартов.\n\n*ESM*\n\n```js\nimport {createDebugger} from '@e22m4u/js-debug';\n```\n\n*CommonJS*\n\n```js\nconst {createDebugger} = require('@e22m4u/js-debug');\n```\n\n## Использование\n\nИнтерполяция строк (см. спецификаторы [@e22m4u/js-format](https://www.npmjs.com/package/@e22m4u/js-format)).\n\n```js\nimport {createDebugger} from '@e22m4u/js-debug';\n\nconst debug = createDebugger();\ndebug('Got value %v.', 100);\ndebug('Got values %l.', ['foo', 10, true]);\n// Got value 100.\n// Got values \"foo\", 10, true.\n```\n\nДамп значений.\n\n```js\nimport {createDebugger} from '@e22m4u/js-debug';\n\nconst debug = createDebugger();\n// (!) используется метод inspect\ndebug.inspect({\n  email: 'john.doe@example.com',\n  phone: {\n    mobile: '+1-555-123-4567',\n    home: '+1-555-987-6543'\n  },\n});\n// {\n//   email: 'john.doe@example.com',\n//   phone: {\n//     mobile: '+1-555-123-4567',\n//     home: '+1-555-987-6543'\n//   }\n// }\n```\n\nЗаголовочное сообщение над дампом.\n\n```js\nimport {createDebugger} from '@e22m4u/js-debug';\n\nconst debug = createDebugger();\n// заголовочное сообщение передается\n// в метод inspect первым аргументом\ndebug.inspect('Order details:', {\n  orderId: 988,\n  date: '2023-10-27',\n  totalAmount: 120.50,\n});\n\n// Order details:\n//   {\n//     orderId: 988,\n//     date: '2023-10-27',\n//     totalAmount: 120.50,\n//   }\n```\n\nОпределение пространства имен.\n\n```js\nimport {createDebugger} from '@e22m4u/js-debug';\n\n// вызов createDebugger() без аргументов создает\n// отладчик с пустым пространством имен\nconst debug1 = createDebugger();\ndebug1('Hello world');\n// Hello world\n\n// пространство имен можно передать в первом\n// аргументе фабрики, как это показано ниже\nconst debug2 = createDebugger('myApp');\nconst debug3 = createDebugger('myApp', 'myService');\nconst debug4 = createDebugger('myApp:myService');\ndebug2('Hello world');\ndebug3('Hello world');\ndebug4('Hello world');\n// myApp Hello world\n// myApp:myService Hello world\n// myApp:myService Hello world\n```\n\nОпределение глобального пространства имен в переменной окружения.\n\n```js\nimport {createDebugger} from '@e22m4u/js-debug';\n\nprocess.env['DEBUGGER_NAMESPACE'] = 'myApp';\n\nconst debug = createDebugger();\ndebug('Hello world');\n// myApp Hello world\n```\n\nОтключение глобального пространства имен из переменной окружения.\n\n```js\nimport {createDebugger} from '@e22m4u/js-debug';\n\nprocess.env['DEBUGGER_NAMESPACE'] = 'myApp';\n\nconst debug1 = createDebugger();\nconst debug2 = debug1.withoutEnvNs();\ndebug1('Hello world');\ndebug2('Hello world');\n// myApp Hello world\n// Hello world\n```\n\nРасширение сегментов пространства имен.\n\n```js\nimport {createDebugger} from '@e22m4u/js-debug';\n\nconst debug1 = createDebugger();\nconst debug2 = debug1.withNs('myApp');\nconst debug3 = debug2.withNs('myService');\ndebug1('Hello world');\ndebug2('Hello world');\ndebug3('Hello world');\n// Hello world\n// myApp Hello world\n// myApp:myService Hello world\n```\n\nИспользование статичного хэша.\n\n```js\nimport {createDebugger} from '@e22m4u/js-debug';\n\nconst debug1 = createDebugger().withHash();\ndebug1('Hi John');\ndebug1('Hi Tommy');\n// r34s Hi John\n// r34s Hi Tommy\n\nconst debug2 = createDebugger().withHash();\ndebug2('Hi John');\ndebug2('Hi Tommy');\n// ier0 Hi John\n// ier0 Hi Tommy\n```\n\nОпределение длины хэша.\n\n```js\nimport {createDebugger} from '@e22m4u/js-debug';\n\nconst debug = createDebugger().withHash(15);\ndebug('Hi John');\ndebug('Hi Tommy');\n// we1gf4uyc4dj8f0 Hi John\n// we1gf4uyc4dj8f0 Hi Tommy\n```\n\nИспользование смещений.\n\n```js\nimport {createDebugger} from '@e22m4u/js-debug';\n\nconst debug1 = createDebugger().withOffset(1);\nconst debug2 = createDebugger().withOffset(2);\nconst debug3 = createDebugger().withOffset(3);\nconst debug4 = createDebugger('myApp').withOffset(3);\ndebug1('Hello world');\ndebug2('Hello world');\ndebug3('Hello world');\ndebug4('Hello world');\n// Hello world\n//    Hello world\n//        Hello world\n// myApp       Hello world\n```\n\nКомбинирование методов.\n\n```js\nimport {createDebugger} from '@e22m4u/js-debug';\n\nconst debug = createDebugger('myApp').withNs('myService').withHash();\nconst debugWo1 = debug.withOffset(1);\n\nconst contact = {\n  email: 'john.doe@example.com',\n  phone: {\n    mobile: '+1-555-123-4567',\n    home: '+1-555-987-6543'\n  },\n}\n\ndebug('Iterating over %v participants.', 10);\ndebugWo1('Looking for contacts of %v participant.', 1);\ndebugWo1.inspect('Participant contacts found:', contact);\n\n// myApp:myService:o3pk Iterating over 10 participants.\n// myApp:myService:o3pk   Looking for contacts of 1 participant.\n// myApp:myService:o3pk   Participant contacts found:\n// myApp:myService:o3pk     {\n// myApp:myService:o3pk       email: 'john.doe@example.com',\n// myApp:myService:o3pk       phone: {\n// myApp:myService:o3pk         mobile: '+1-555-123-4567',\n// myApp:myService:o3pk         home: '+1-555-987-6543'\n// myApp:myService:o3pk       },\n// myApp:myService:o3pk     }\n```\n\n## Управление выводом\n\nПо умолчанию вызовы функции `debug` ничего не выводят. Чтобы увидеть отладочные\nсообщения, необходимо указать, какие именно пространства имен вас интересуют.\nЭто делается с помощью специального паттерна (шаблона). Механизм включения\nзависит от среды выполнения.\n\n### Node.js: Переменная окружения `DEBUG`\n\nВ среде Node.js используется переменная окружения DEBUG. Вы можете установить\nеё при запуске вашего скрипта.\n\n```bash\n# включить конкретное пространство имен\nDEBUG=myApp node your_script.js\n\n# включить все пространства имен, начинающиеся с 'myApp:'\nDEBUG=myApp:* node your_script.js\n\n# включить несколько пространств имен через запятую\nDEBUG=myApp:service,lib:utils node your_script.js\n# если используете пробелы, нужны кавычки\nDEBUG=\"myApp:service lib:utils\" node your_script.js\n\n# включить ВСЕ пространства имен\nDEBUG=* node your_script.js\n```\n\n### Браузер: localStorage.debug\n\nВ веб-браузерах для управления выводом используется ключ debug в localStorage.\nВы можете установить его значение через консоль разработчика.\n\n```js\n// включить конкретное пространство имен\nlocalStorage.debug = 'myApp';\n\n// включить все пространства имен, начинающиеся с 'myApp:'\nlocalStorage.debug = 'myApp:*';\n\n// включить несколько (через запятую или пробел)\nlocalStorage.debug = 'myApp:service,lib:utils';\n// или\nlocalStorage.debug = 'myApp:service lib:utils';\n\n// включить ВСЕ\nlocalStorage.debug = '*';\n\n// отключить вывод\nlocalStorage.removeItem('debug');\n// или\nlocalStorage.debug = '';\n```\n\n*i. После изменения `localStorage.debug` обычно требуется перезагрузить\nстраницу, чтобы изменения вступили в силу.*\n\n### Синтаксис паттернов\n\n- Точное совпадение (например, `myApp:myService`);\n- Wildcard (\\*): `myApp*` соответствует `myApp`, `myApp:myService` и т.д.;\n- Несколько паттернов можно указать разделив их запятой или пробелом;\n- Включить всё: `*` включает вывод для всех пространств имен;\n\nПримеры шаблонов в окружении Node.js:\n\n```bash\nnode main.js # ничего не выведет\nDEBUG=* node main.js # выведет все сообщения\nDEBUG=app node main.js # только пространство имен app\nDEBUG=app:* node main.js # пространства имен с префиксом app:\nDEBUG=app:worker,legacy node main.js # только app:worker и legacy\n```\n\n## Класс Debuggable\n\nКласс реализует метод `getDebuggerFor(method: Function)`, который принимает\nлюбой другой метод потомка данного класса и возвращает новый отладчик,\nсконфигурированный так, чтобы пространство имен отладчика содержало название\nкласса, название метода и хэш, позволяющий различать сообщения отладки\nодного и того же метода в разных вызовах.\n\n```\n┌────────────────────────────────────┐\n│ класс      | метод    | хэш вызова │\n\" calculator : multiply : ds83       \"\n└────────────────────────────────────┘\n```\n\nСоздание экземпляра автоматически логируется.\n\n```js\nimport {Debuggable} from '@e22m4u/js-debug';\n\nclass MyClass extends Debuggable {}\n\nnew MyClass();\n// myClass:constructor:f12s Instantiated.\n```\n\nПример вывода сообщений отладки двух методов одного класса.\n\n```js\nimport {Debuggable} from '@e22m4u/js-debug';\n\nprocess.env['DEBUG'] = '*';\n\nclass Calculator extends Debuggable {\n  multiply(a, b) {\n    const debug = this.getDebuggerFor(this.multiply); // \u003c=\n    debug('Multiplying %v by %v.');\n    const res = a * b;\n    debug('Result %v.');\n    return res;\n  }\n\n  divide(a, b) {\n    const debug = this.getDebuggerFor(this.divide); // \u003c=\n    debug('Dividing %v by %v.');\n    const res = a / b;\n    debug('Result %v.');\n    return res;\n  }\n}\n\nconst calculator = new Calculator();\ncalculator.multiply(4, 8);  // первый вызов (хэш: 4d8w)\ncalculator.multiply(6, 10); // повторный вызов (хэш: v54w)\ncalculator.divide(32, 8);\ncalculator.divide(60, 10);\n// calculator:constructor:ds83 Instantiated.\n// calculator:multiply:4d8w Multiplying 4 by 8.\n// calculator:multiply:4d8w Result 32.\n// calculator:multiply:v54w Multiplying 6 by 10.\n// calculator:multiply:v54w Result 60.\n// calculator:divide:c9ew Dividing 32 by 8.\n// calculator:divide:c9ew Result 4.\n// calculator:divide:twq2 Dividing 60 by 10.\n// calculator:divide:twq2 Result 6.\n```\n\nИспользование переменной окружения `DEBUGGER_NAMESPACE`.\n\n```js\nimport {Debuggable} from '@e22m4u/js-debug';\n\nprocess.env['DEBUGGER_NAMESPACE'] = 'myApp'; // \u003c=\nprocess.env['DEBUG'] = 'myApp*';\n\nclass Calculator extends Debuggable {\n  multiply(a, b) {\n    const debug = this.getDebuggerFor(this.multiply);\n    debug('Multiplying %v by %v.');\n    const res = a * b;\n    debug('Result %v.');\n    return res;\n  }\n}\n\nconst calculator = new Calculator();\ncalculator.multiply(4, 8);\n// myApp:calculator:constructor:ds83 Instantiated.\n// myApp:calculator:multiply:4d8w Multiplying 4 by 8.\n// myApp:calculator:multiply:4d8w Result 32.\n```\n\n### DebuggableOptions\n\nПервый аргумент класса `Debuggable` принимает объект со следующими свойствами.\n\n- `namespace?: string` - префиксное пространство имен;\n- `noEnvironmentNamespace?: boolean` - игнорировать переменную `DEBUGGER_NAMESPACE`;\n- `noInstantiationMessage?: boolean` - не выводить сообщение о создании экземпляра;\n\n#### DebuggableOptions.namespace\n\nЗначение опции `namespace` добавляет префиксное пространство имен.\n\n```js\nimport {Debuggable} from '@e22m4u/js-debug';\n\nprocess.env['DEBUG'] = 'myApp*';\n\nclass Calculator extends Debuggable {\n  constructor() {\n    super({namespace: 'myApp'}); // \u003c=\n  }\n\n  multiply(a, b) {\n    const debug = this.getDebuggerFor(this.multiply);\n    debug('Multiplying %v by %v.');\n    const res = a * b;\n    debug('Result %v.');\n    return res;\n  }\n}\n\nconst calculator = new Calculator();\ncalculator.multiply(4, 8);\n// myApp:calculator:constructor:ds83 Instantiated.\n// myApp:calculator:multiply:4d8w Multiplying 4 by 8.\n// myApp:calculator:multiply:4d8w Result 32.\n```\n\n#### DebuggableOptions.noEnvironmentNamespace\n\nЗначение `true` опции `noEnvironmentNamespace` позволяет игнорировать\nпеременную окружения `DEBUGGER_NAMESPACE`, устанавливающую префиксное\nпространство имен.\n\n```js\nimport {Debuggable} from '@e22m4u/js-debug';\n\nprocess.env['DEBUGGER_NAMESPACE'] = 'myApp'; // \u003c=\nprocess.env['DEBUG'] = '*';\n\nclass Calculator extends Debuggable {\n  constructor() {\n    super({noEnvironmentNamespace: true}); // \u003c=\n  }\n\n  multiply(a, b) {\n    const debug = this.getDebuggerFor(this.multiply);\n    debug('Multiplying %v by %v.');\n    const res = a * b;\n    debug('Result %v.');\n    return res;\n  }\n}\n\nconst calculator = new Calculator();\ncalculator.multiply(4, 8);\n// calculator:constructor:ds83 Instantiated.\n// calculator:multiply:4d8w Multiplying 4 by 8.\n// calculator:multiply:4d8w Result 32.\n```\n\n## Тесты\n\n```bash\nnpm run test\n```\n\n## Лицензия\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe22m4u%2Fjs-debug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fe22m4u%2Fjs-debug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe22m4u%2Fjs-debug/lists"}