{"id":22356321,"url":"https://github.com/do-/node-ru-nalog-fias-gar","last_synced_at":"2025-07-03T15:12:56.864Z","repository":{"id":57355786,"uuid":"430587211","full_name":"do-/node-ru-nalog-fias-gar","owner":"do-","description":"Tools for reading gar_xml.zip from fias.nalog.ru","archived":false,"fork":false,"pushed_at":"2024-11-25T17:38:54.000Z","size":251,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-08T21:40:19.369Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/do-.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}},"created_at":"2021-11-22T06:22:32.000Z","updated_at":"2025-03-27T08:52:51.000Z","dependencies_parsed_at":"2024-11-25T18:36:59.934Z","dependency_job_id":null,"html_url":"https://github.com/do-/node-ru-nalog-fias-gar","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/do-/node-ru-nalog-fias-gar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/do-%2Fnode-ru-nalog-fias-gar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/do-%2Fnode-ru-nalog-fias-gar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/do-%2Fnode-ru-nalog-fias-gar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/do-%2Fnode-ru-nalog-fias-gar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/do-","download_url":"https://codeload.github.com/do-/node-ru-nalog-fias-gar/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/do-%2Fnode-ru-nalog-fias-gar/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263348437,"owners_count":23452887,"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","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":[],"created_at":"2024-12-04T14:09:54.248Z","updated_at":"2025-07-03T15:12:56.813Z","avatar_url":"https://github.com/do-.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![workflow](https://github.com/do-/node-ru-nalog-fias-gar/actions/workflows/main.yml/badge.svg)\n![Jest coverage](./badges/coverage-jest%20coverage.svg)\n\n# Disclaimer\n\nThis software is developed solely for integration with Russian government IT systems, so the Cyrillic script is widely used in its documentation.\n\n# Описание\n\n`ru-nalog-fias-gar` - библиотека для чтения в приложениях на основе node.js файлов Федеральной информационной адресной системы (ФИАС) в формате Государственного адресного реестра (ГАР), доступных на [официальном сайте](https://fias.nalog.ru/Updates) .\n\nЧтение происходит непосредственно из ZIP-архива, не требуя предварительной распаковки в файловую систему.\n\nИзвлечение списков, содержащих многие сотни тысяч записей (дома, улицы и т. п.) реализовано в виде [потока](https://nodejs.org/docs/latest/api/stream.html#readable-streams) [объектов](https://nodejs.org/docs/latest/api/stream.html#object-mode).\n\nОтдельные записи представляются в виде объектов типа [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map). Все ключи и все значения в этих Map (в том числе такие, как `\"1\"`, `\"true\"`, `\"2079-06-06\"`) являются примитивными строками, непосредственно вырезанными из XML-текста, без дополнительных преобразований.\n\nПредусмотрена опция преобразования этих записей в строки с разделителями-символами табуляции - для массовой загрузки в БД.\n\nДля отслеживания обработанного объёма данных в реальном времени подключён модуль [`progress-stream`](https://www.npmjs.com/package/progress-stream).\n\n# Установка\n```shell\nnpm i ru-nalog-fias-gar\n```\n# Как использовать\n\n```js\n// Инициализация\nconst {GarXmlZip} = require ('ru-nalog-fias-gar')\nconst garXmlZip = new GarXmlZip ('~/gar_xml.zip')\n\n// Выяснение даты архива\nconst date = await garXmlZip.getDate () // 'YYYY-MM-DD'\n\n// Извлечение общей таблицы-справочника\nconst houseTypes = await garXmlZip.getDataDictionary ({\n    name: 'HOUSE_TYPES',\n  filter: r =\u003e r.get ('ISACTIVE') === 'true',\n     map: r =\u003e r.get ('SHORTNAME'),\n}) // Map {\"2\" =\u003e \"д.\", ...}\n\n// Извлечение таблицы данных региона\nconst houses = await garXmlZip.createReadStream ({\n    name: 'HOUSES',\n  region: 77,\n  filter: r =\u003e r.get ('ISACTUAL') === '1',\n     map: r =\u003e {r.set ('ADDRESS', ...) ...; return r},\n    join: ['OBJECTGUID', 'ADDRESS'],\nprogress: [  \n             p =\u003e console.log (p.percentage + '%'),\n             {time: 2000},\n          ],\n})\n\n  // ...и дальше\n\nfor await (const house of houses) {\n  // обработать `house`\n}\n\n  // ...либо\n\nhouses.pipe (new Transformer (...)).pipe (destination)\n```\n# API\n## Общие замечания\nПредполагается, что имя каждого файла в ZIP-архиве имеет формат `AS_${name}_${YYYY}${MM}${DD}_${UUID}.XML`, где:\n* `${YYYY}${MM}${DD}` у всех элементов архива совпадают;\n* `${name}` различается у любых двух файлов внутри одной директории;\n* `${UUID}` имеет длину 36 символов.\n\nВыполнение этих условий не проверяется. При их нарушении результат вызова нижеописанных методов непредсказуем.\n\n## Конструктор\n```js\nconst garXmlZip = new GarXmlZip ('~/gar_xml.zip')\n```\nПараметры: \n|Имя|Тип|Описание|\n|-|-|-|\n|path|string|Путь к файлу `gar_xml.zip`||\n\nСам по себе конструктор не производит никаких действий с файлом, в том числе не проверяет его доступность. Однако при вызове всех методов файл должен быть доступен на чтение по указанному пути.\n\n## `getDate`\n```js\nconst date = await garXmlZip.getDate ()\n```\nАсинхронный метод определения даты архива.\n\nДата возвращается в виде **строки** формата `YYYY-MM-DD` (НЕ объекта `Date`).\n\nЗначение, возвращаемое методом, формируется из подстроки длины 8, находящейся на расстоянии 41 символ от конца имени первого попавшегося в архиве файла.\n\n## `getDataDictionary`\n\n```js\nconst houseTypes = await garXmlZip.getDataDictionary ({\n    name: 'HOUSE_TYPES',\n  filter: r =\u003e r.get ('ISACTIVE') === 'true',\n     map: r =\u003e r.get ('SHORTNAME'),\n}) // Map {\"2\" =\u003e \"д.\", ...}\n```\nАсинхронный метод, извлекающий содержимое одного из файлов в корне архива. Такие файлы содержат справочники данных: типы документов и т. п.\n\nОпции:\n|Имя|Тип|Обязательность|По умолчанию|Описание|\n|-|-|-|-|-|\n|name|string|Да||Часть имени файла от `AS_` до `_YYYYMMDD`|\n|filter|Map =\u003e Boolean|Нет|r =\u003e true|Если эта функция определена, она вызывается для каждой записи и в результат попадают только те из них, для которых функция вернёт значение, [приводимое](https://262.ecma-international.org/12.0/#sec-toboolean) к `true`|\n|map|Map =\u003e any|Нет|r =\u003e r|Если эта функция определена, результат формируется из результатов её вызова|\n\nВ результате выдаётся [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), у которого:\n* ключи - значения атрибутов `ID` элементов, найденных в файле;\n* значения - результаты применения функции, заданной как опция `map`, к Map-наборам атрибутов\n  * если `map` не задана - сами записи в виде Map (в том числе содержащие ключи `ID`, по которым они индексированы).\n\n## `createReadStream`\n\n```js\nconst houses = await garXmlZip.createReadStream ({\n    name: 'HOUSES',\n  region: 77,\n  filter: r =\u003e r.get ('ISACTUAL') === '1',\n     map: r =\u003e {r.set ('ADDRESS', ...) ...; return r},\n    join: ['OBJECTGUID', 'ADDRESS'],\nprogress: [  \n             p =\u003e console.log (p.percentage + '%'),\n             {time: 2000},\n          ],\n\n\n})\n```\nАсинхронный метод, извлекающий содержимое одного из файлов в региональной директории в виде потока.\n\nЕсли задана опция `join`, поток обычный, если не задана - [объектный](https://nodejs.org/docs/latest/api/stream.html#object-mode).\n\nОпции:\n|Имя|Тип|Обязательность|По умолчанию|Описание|\n|-|-|-|-|-|\n|name|string|Да||Часть имени файла от `AS_` до `_YYYYMMDD`|\n|region|string или Number|Да||Код региона, он же имя директории архива, в которой расположен файл|\n|filter|Map =\u003e Boolean|Нет|r =\u003e true|Если эта функция определена, она вызывается для каждой записи и в результат попадают только те из них, для которых функция вернёт значение, [приводимое](https://262.ecma-international.org/12.0/#sec-toboolean) к `true`|\n|map|Map =\u003e any|Нет|r =\u003e r|Если эта функция определена, то каждая исходная запись заменяется на результат её вызова|\n|join|Array|Нет||Если этот массив определён, то каждая запись (после `map`) заменяется на строку, составленную из значений перечисленных в `join` полей, через `\\t`, оканчивающуюся на `\\n`|\n|progress|Array[2]|Нет||Если этот массив определён, то для входящего потока создаётся счётчик прочитанных байт из модуля [`progress-stream`](https://www.npmjs.com/package/progress-stream), при этом первый элемент массива - функция, устанавливаемая `on ('progress')`, а второй - набор [опций](https://www.npmjs.com/package/progress-stream#options) объекта-счётчика|\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdo-%2Fnode-ru-nalog-fias-gar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdo-%2Fnode-ru-nalog-fias-gar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdo-%2Fnode-ru-nalog-fias-gar/lists"}