tiny-osmpbf

library1.0.0-beta.1jsnpmunverified

tiny-osmpbf is a lightweight JavaScript library designed for parsing OpenStreetMap PBF (Protocol Buffer Binary) format files. It targets environments including Node.js and web browsers, offering a pure JavaScript implementation. The current development is in a beta phase, with version 1.0.0-beta.2 being the latest as of recent releases, indicating active refinement towards a stable 1.0.0. Unlike many other PBF parsers, tiny-osmpbf prioritizes ease-of-use and a small code footprint (under 16KB minified and gzipped) over raw parsing speed. This is achieved by leveraging smaller, specialized libraries like Mapbox's `pbf` for protocol buffer parsing and `tiny-inflate` for ZLIB decompression. A key differentiating feature is its synchronous API, which simplifies integration into existing synchronous workflows but necessitates loading the entire PBF data into memory before parsing, making it less suitable for extremely large files or memory-constrained environments. The output format adheres to the widely used OSM-JSON standard, compatible with services like Overpass API.

data serialization http-networking

npm install tiny-osmpbf

github ↗package ↗

INSTALL

IMPORT

SIG · TINY-OSMPBF

tiny-osmpbf

datajavascriptv1.0.0-beta.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

tinyosmpbf

✓ import tinyosmpbf from 'tiny-osmpbf';

✗ 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

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

✗ 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

✓ import tinyosmpbf from 'tiny-osmpbf';

✗ import * as 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)`).

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); }

Debug

Known issues

gotchaThe 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.

affects: >=0.1.0

breakingAs 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.

affects: >=1.0.0-beta.1

gotchaThe 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.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: tinyosmpbf is not a function

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

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

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.

Upgrade

Version history

1.0.0-beta.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/tyrasd/tiny-osmpbf ↗

packagehttps://www.npmjs.com/package/tiny-osmpbf ↗