Tiny OSMPBF Parser

Common errors

• TypeError: tinyosmpbf is not a function

  cause The module's default export (the parsing function) was imported incorrectly, often by attempting a named import (e.g., `import { tinyosmpbf } from '...'`) or destructuring a `require` call.
  fix Ensure you are using a default import for ES Modules (`import tinyosmpbf from 'tiny-osmpbf';`) or a direct `require` assignment for CommonJS (`const tinyosmpbf = require('tiny-osmpbf');`).

• Error: PBF data must be a Buffer

  cause The `dataBuffer` argument provided to the `tinyosmpbf` function was not a Node.js `Buffer` or a compatible `Uint8Array` object.
  fix Verify that your input data is correctly read into a `Buffer` instance, for example, by using `fs.readFileSync(filePath)` in Node.js, which returns a Buffer.

• RangeError: Array buffer allocation failed

  cause Processing a very large PBF file with `tiny-osmpbf`'s synchronous, in-memory parsing approach caused the Node.js process to exceed its allocated memory or available system RAM.
  fix Reduce the size of the PBF file being processed, or switch to a streaming PBF parser if you need to handle extremely large datasets without loading them entirely into memory.

Warnings

• gotcha The library's core API is synchronous and requires loading the entire PBF file into memory before parsing. This can lead to high memory consumption and potential `OutOfMemoryError` for large datasets (e.g., entire continent or planet files).
  Fix: For very large PBF files, consider using streaming parsers like `osm-pbf-parser-node` or `node-osmium` to process data incrementally and manage memory more efficiently.
• breaking As the package is currently in a `1.0.0-beta` state, users should anticipate that API details or behavior might undergo breaking changes before a stable `1.0.0` release. Features and interfaces are subject to modification.
  Fix: Monitor release notes closely for updates and thoroughly test your application with each new beta version to identify and adapt to any breaking changes.
• gotcha The library is primarily optimized for a small code footprint and ease-of-use rather than maximum parsing speed. For applications requiring the highest parsing throughput, alternatives built for performance might be more suitable.
  Fix: Benchmark `tiny-osmpbf` against performance-focused alternatives like `node-osmium` or `osm-pbf-parser-node` if parsing speed is a critical requirement for your use case.

Install

• npm install tiny-osmpbf npm
• yarn add tiny-osmpbf yarn
• pnpm add tiny-osmpbf pnpm

Imports

• tinyosmpbf
  wrong:

  import { tinyosmpbf } from 'tiny-osmpbf';

  correct:

  import tinyosmpbf from 'tiny-osmpbf';

  This is the correct way to import the default function export in ES Modules. The library is a single-function export, not an object with named exports.
• tinyosmpbf
  wrong:

  const { tinyosmpbf } = require('tiny-osmpbf');

  correct:

  const tinyosmpbf = require('tiny-osmpbf');

  This is the standard CommonJS way to import the default function export. Attempting to destructure for a non-object default export will result in `undefined`.
• tinyosmpbf
  wrong:

  import * as tinyosmpbf from 'tiny-osmpbf';

  correct:

  import tinyosmpbf from 'tiny-osmpbf';

  While `import * as` might seem to work, it wraps the default export in an object `{ default: Function }`. Direct default import is preferred for direct function calls (e.g., `tinyosmpbf(data)` instead of `tinyosmpbf.default(data)`).

Quickstart

Demonstrates how to read an OSM PBF file synchronously from disk using Node.js's `fs` module and then parse it with `tiny-osmpbf`, logging basic information and the first two parsed elements.

import * as fs from 'node:fs';
import tinyosmpbf from 'tiny-osmpbf';

// Assuming you have an osm.pbf file. Replace with your file path.
const filePath = 'path/to/your/map.osm.pbf';

try {
  const dataBuffer = fs.readFileSync(filePath);
  console.log(`Successfully read ${dataBuffer.length} bytes from ${filePath}`);

  // Parse the PBF data synchronously
  const osmData = tinyosmpbf(dataBuffer);

  console.log('Parsed OSM Data (first few elements):', osmData.elements.slice(0, 2));
  console.log('Total OSM elements:', osmData.elements.length);
  console.log('OSM Generator:', osmData.osm3s.generator);
} catch (error) {
  console.error('Error parsing PBF file:', error);
}