Disclaimer

This software is developed solely for integration with Russian government IT systems, so the Cyrillic script is widely used in its documentation.

Описание

ru-nalog-fias-gar - библиотека для чтения в приложениях на основе node.js файлов Федеральной информационной адресной системы (ФИАС) в формате Государственного адресного реестра (ГАР), доступных на официальном сайте .

Чтение происходит непосредственно из ZIP-архива, не требуя предварительной распаковки в файловую систему.

Извлечение списков, содержащих многие сотни тысяч записей (дома, улицы и т. п.) реализовано в виде потока объектов.

Отдельные записи представляются в виде объектов типа Map. Все ключи и все значения в этих Map (в том числе такие, как "1", "true", "2079-06-06") являются примитивными строками, непосредственно вырезанными из XML-текста, без дополнительных преобразований.

Предусмотрена опция преобразования этих записей в строки с разделителями-символами табуляции - для массовой загрузки в БД.

Для отслеживания обработанного объёма данных в реальном времени подключён модуль progress-stream.

Установка

npm i ru-nalog-fias-gar

Как использовать

// Инициализация
const {GarXmlZip} = require ('ru-nalog-fias-gar')
const garXmlZip = new GarXmlZip ('~/gar_xml.zip')

// Выяснение даты архива
const date = await garXmlZip.getDate () // 'YYYY-MM-DD'

// Извлечение общей таблицы-справочника
const houseTypes = await garXmlZip.getDataDictionary ({
    name: 'HOUSE_TYPES',
  filter: r => r.get ('ISACTIVE') === 'true',
     map: r => r.get ('SHORTNAME'),
}) // Map {"2" => "д.", ...}

// Извлечение таблицы данных региона
const houses = await garXmlZip.createReadStream ({
    name: 'HOUSES',
  region: 77,
  filter: r => r.get ('ISACTUAL') === '1',
     map: r => {r.set ('ADDRESS', ...) ...; return r},
    join: ['OBJECTGUID', 'ADDRESS'],
progress: [  
             p => console.log (p.percentage + '%'),
             {time: 2000},
          ],
})

  // ...и дальше

for await (const house of houses) {
  // обработать `house`
}

  // ...либо

houses.pipe (new Transformer (...)).pipe (destination)

API

Общие замечания

Предполагается, что имя каждого файла в ZIP-архиве имеет формат AS_${name}_${YYYY}${MM}${DD}_${UUID}.XML, где:

• ${YYYY}${MM}${DD} у всех элементов архива совпадают;
• ${name} различается у любых двух файлов внутри одной директории;
• ${UUID} имеет длину 36 символов.

Выполнение этих условий не проверяется. При их нарушении результат вызова нижеописанных методов непредсказуем.

Конструктор

const garXmlZip = new GarXmlZip ('~/gar_xml.zip')

Параметры: |Имя|Тип|Описание| |-|-|-| |path|string|Путь к файлу gar_xml.zip||

Сам по себе конструктор не производит никаких действий с файлом, в том числе не проверяет его доступность. Однако при вызове всех методов файл должен быть доступен на чтение по указанному пути.

getDate

const date = await garXmlZip.getDate ()

Асинхронный метод определения даты архива.

Дата возвращается в виде строки формата YYYY-MM-DD (НЕ объекта Date).

Значение, возвращаемое методом, формируется из подстроки длины 8, находящейся на расстоянии 41 символ от конца имени первого попавшегося в архиве файла.

getDataDictionary

const houseTypes = await garXmlZip.getDataDictionary ({
    name: 'HOUSE_TYPES',
  filter: r => r.get ('ISACTIVE') === 'true',
     map: r => r.get ('SHORTNAME'),
}) // Map {"2" => "д.", ...}

Асинхронный метод, извлекающий содержимое одного из файлов в корне архива. Такие файлы содержат справочники данных: типы документов и т. п.

Опции: |Имя|Тип|Обязательность|По умолчанию|Описание| |-|-|-|-|-| |name|string|Да||Часть имени файла от AS_ до _YYYYMMDD| |filter|Map => Boolean|Нет|r => true|Если эта функция определена, она вызывается для каждой записи и в результат попадают только те из них, для которых функция вернёт значение, приводимое к true| |map|Map => any|Нет|r => r|Если эта функция определена, результат формируется из результатов её вызова|

В результате выдаётся Map, у которого:

• ключи - значения атрибутов ID элементов, найденных в файле;
• значения - результаты применения функции, заданной как опция map, к Map-наборам атрибутов
  • если map не задана - сами записи в виде Map (в том числе содержащие ключи ID, по которым они индексированы).

createReadStream

const houses = await garXmlZip.createReadStream ({
    name: 'HOUSES',
  region: 77,
  filter: r => r.get ('ISACTUAL') === '1',
     map: r => {r.set ('ADDRESS', ...) ...; return r},
    join: ['OBJECTGUID', 'ADDRESS'],
progress: [  
             p => console.log (p.percentage + '%'),
             {time: 2000},
          ],


})

Асинхронный метод, извлекающий содержимое одного из файлов в региональной директории в виде потока.

Если задана опция join, поток обычный, если не задана - объектный.

Опции: |Имя|Тип|Обязательность|По умолчанию|Описание| |-|-|-|-|-| |name|string|Да||Часть имени файла от AS_ до _YYYYMMDD| |region|string или Number|Да||Код региона, он же имя директории архива, в которой расположен файл| |filter|Map => Boolean|Нет|r => true|Если эта функция определена, она вызывается для каждой записи и в результат попадают только те из них, для которых функция вернёт значение, приводимое к true| |map|Map => any|Нет|r => r|Если эта функция определена, то каждая исходная запись заменяется на результат её вызова| |join|Array|Нет||Если этот массив определён, то каждая запись (после map) заменяется на строку, составленную из значений перечисленных в join полей, через \t, оканчивающуюся на \n| |progress|Array[2]|Нет||Если этот массив определён, то для входящего потока создаётся счётчик прочитанных байт из модуля progress-stream, при этом первый элемент массива - функция, устанавливаемая on ('progress'), а второй - набор опций объекта-счётчика|