xport-js

Library to read in v5/v6 XPORT files using Node.js .

Installation

npm install xport-js

Usage

import Library from 'xport-js';

const lib = new Library('/path/to/file.xpt');

Named exports

import Library, { Member, Variable } from 'xport-js';
export type { Options, Header, UniqueValues, VariableMetadata } from 'xport-js';

API

new Library(filePath)

Creates a library instance associated with the XPORT file.

getMetadata(format?)

Parses and returns metadata. Default format is dataset-json1.1.

// Variable metadata (xport format)
const vars = await lib.getMetadata('xport');
// vars: Array<{ dataset, name, label, length, type, format?, informat? }>

// Dataset-JSON 1.1 metadata
const meta = await lib.getMetadata();
// meta: { name, label, records, columns, datasetJSONCreationDateTime, ... }

Returns a Promise resolving to metadata in one of the following formats:

• format = 'xport' — returns VariableMetadata[]
• format = 'dataset-json1.1' (default) — returns DatasetJsonMetadata (per the Dataset-JSON 1.1 spec)

read(options?)

Async generator that yields observations row-by-row without loading the entire dataset into memory.

for await (const row of lib.read({ rowFormat: 'object' })) {
  console.log(row);
}

Returns an async generator that yields rows in the specified format.

| Option | Type | Default | Description | |--------|------|---------|-------------| | dsNames | string[] | all datasets | Dataset names to read | | rowFormat | 'array' \| 'object' | 'array' | Output format — array of values or key-value object | | keep | string[] | [] | Variables to include (case-insensitive) | | skipHeader | boolean | false | Omit the header row | | encoding | BufferEncoding | 'binary' | String encoding (see Node.js encodings) | | filter | Filter \| BasicFilter | — | Filter observations using js-array-filter | | roundPrecision | number | — | Round numeric values to N decimal places |

getData(props)

Reads all observations into memory (for large datasets prefer read).

Returns a Promise resolving to an object containing:

• data: Array of rows in the specified format.
• lastRow: Index of the last row returned (useful for pagination).
• endReached: Boolean indicating if the end of the dataset has been reached.

const result = await lib.getData({
  start: 0,              // first row to return
  length: 100,           // max rows to return
  type: 'object',        // 'array' | 'object'
  filterColumns: [],     // only these columns
  filter: { ... },       // js-array-filter filter
  skipHeader: true,
  roundPrecision: 2,
});
// result: { data: Array<row>, lastRow: number, endReached: boolean }

| Option | Type | Default | Description | |--------|------|---------|-------------| | start | number | 0 | Index of the first row to return (0-based) | | length | number | all rows | Maximum number of rows to return | | type | 'array' \| 'object' | | 'array' | Output format — array of values or key-value object | | filterColumns | string[] | [] | Only include these columns (case-insensitive) | | filter | Filter \| BasicFilter | — | Filter observations using js-array-filter | | skipHeader | boolean | false | Omit the header row | | roundPrecision | number | — | Round numeric values to N decimal places (optional) |

getUniqueValues(props)

Returns unique values for specified columns.

const unique = await lib.getUniqueValues({
  columns: ['AGE', 'SEX', 'RACE'],
  limit: 10,            // max unique values per column (0 = no limit)
  addCount: true,       // include value counts
  sort: true,           // sort values
  roundPrecision: 0,    // round numeric values to integer
});
// { AGE: { values: [...], counts: { '45': 3, ... } }, ... }

Returns a Promise resolving to an object where each key is a column name and the value is an object with:

• values: Array of unique values for that column.
• counts: (if addCount is true) Object mapping value to count.

| Option | Type | Default | Description | |--------|------|---------|-------------| | columns | string[] | — | List of variable names to get unique values for | | limit | number | 0 | Maximum number of unique values per column (0 = no limit) | | addCount | boolean | false | Whether to include counts for each unique value | | sort | boolean | false | Whether to sort the unique values | | roundPrecision | number | — | Rounds numeric values to the specified precision (optional) |

toCsv(outDir, options?)

Writes each dataset to a separate CSV file in outDir.

await lib.toCsv('./output', { skipHeader: false });

Authors

• Dmitry Kolosov
• Sergei Krivtcov

License

This project is licensed under the MIT License - see the LICENSE file for details.