# @garjs/parser

A streaming parser for Russian State Address Register (GAR) ZIP exports, providing async iterable access to structured address data.

## Installation

```bash
npm install @garjs/parser
```

## Usage

### Read from file

```ts
import { createReadStream } from 'node:fs'
import { GarTransform } from '@garjs/parser'

const source = createReadStream('path/to/gar_xml.zip')
const out = new GarTransform()

source.pipe(out)

for await (const item of out) {
  console.log(item)
}

// or

out.on('data', item => {
  console.log(item)
})
```

### Read from fetch response

```ts
import { Readable } from 'node:stream'
import { GarTransform } from '@garjs/parser'

const response = await fetch(
  'https://fias-file.nalog.ru/downloads/2025.11.04/gar_xml.zip',
)

const source = response.body && Readable.from(response.body)
const out = new GarTransform()

source?.pipe(out)

for await (const item of out) {
  console.log(item)
}

// or

out.on('data', item => {
  console.log(item)
})
```

## API

### `GarTransform`

```ts
class GarTransform extends Transform {
  constructor(options?: GarTransformOptions)

  on(event: 'data', listener: (item: GarItem) => void): this
  on(event: 'error', listener: (error: Error | GarTransformError) => void): this

  [Symbol.asyncIterator](): AsyncIterator<GarItem>
}
```

### `GarTransformOptions`

- `filter` — a predicate that allows filtering data by the path of a file in the archive, skipping the processing of unnecessary data.

### GarItem API

The `GarItem` is an abstract base class for all GAR data objects. Each specific type of GAR object extends this class with its own data structure and validation schema.

#### Properties

- `type`: The type of GAR object (e.g., 'AddressObject', 'House', 'Apartment', etc.)
- `filePath`: The path to the XML file this item was parsed from
- `raw`: The raw attributes from the XML element as a key-value record
- `data`: The parsed and validated data specific to this GAR object type

#### Methods

- `toJSON()`: Returns a simplified object with just the type and data properties

#### Available GAR Object Types

The parser supports the following GAR object types:

- [`AddressObject`](src/dto/gar-item/address-object.ts): Address objects (streets, cities, districts, etc.)
- [`AddressObjectDivision`](src/dto/gar-item/address-object-division.ts): Address object divisions
- [`AddressObjectType`](src/dto/gar-item/address-object-type.ts): Address object types
- [`AdmHierarchyItem`](src/dto/gar-item/adm-hierarchy-item.ts): Administrative hierarchy items
- [`Apartment`](src/dto/gar-item/apartment.ts): Apartments
- [`ApartmentType`](src/dto/gar-item/apartment-type.ts): Apartment types
- [`CarPlace`](src/dto/gar-item/car-place.ts): Car places
- [`ChangeHistoryItem`](src/dto/gar-item/change-history-item.ts): Change history items
- [`House`](src/dto/gar-item/house.ts): Houses
- [`HouseType`](src/dto/gar-item/house-type.ts): House types
- [`MunHierarchyItem`](src/dto/gar-item/mun-hierarchy-item.ts): Municipal hierarchy items
- [`NormDoc`](src/dto/gar-item/norm-doc.ts): Normative documents
- [`NormDocKind`](src/dto/gar-item/norm-doc-kind.ts): Normative document kinds
- [`NormDocType`](src/dto/gar-item/norm-doc-type.ts): Normative document types
- [`ObjectLevel`](src/dto/gar-item/object-level.ts): Object levels
- [`OperationType`](src/dto/gar-item/operation-type.ts): Operation types
- [`Param`](src/dto/gar-item/param.ts): Parameters
  - `AddressObjectParam`: Information about parameter of address-forming elements
  - `HouseParam`: Information about house parameters
  - `ApartmentParam`: Information about apartment parameter
  - `RoomParam`: Information about room parameter
  - `SteadParam`: Information about land plot parameter
  - `CarPlaceParam`: Information about car place parameter
- [`ParamType`](src/dto/gar-item/param-type.ts): Parameter types
- [`RegistryObjectsItem`](src/dto/gar-item/registry-item.ts): Registry objects
- [`Room`](src/dto/gar-item/room.ts): Rooms
- [`RoomType`](src/dto/gar-item/room-type.ts): Room types
- [`Stead`](src/dto/gar-item/stead.ts): Steads

Each object type has its own specific data structure with typed properties that match the GAR XML schema.

```

```