{"id":16244,"library":"tiny-osmpbf","title":"Tiny OSMPBF Parser","description":"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.","status":"active","version":"1.0.0-beta.1","language":"javascript","source_language":"en","source_url":"https://github.com/tyrasd/tiny-osmpbf","tags":["javascript","openstreetmap","osmpbf","pbf"],"install":[{"cmd":"npm install tiny-osmpbf","lang":"bash","label":"npm"},{"cmd":"yarn add tiny-osmpbf","lang":"bash","label":"yarn"},{"cmd":"pnpm add tiny-osmpbf","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { tinyosmpbf } from 'tiny-osmpbf';","symbol":"tinyosmpbf","correct":"import tinyosmpbf from 'tiny-osmpbf';"},{"note":"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`.","wrong":"const { tinyosmpbf } = require('tiny-osmpbf');","symbol":"tinyosmpbf","correct":"const tinyosmpbf = require('tiny-osmpbf');"},{"note":"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)`).","wrong":"import * as tinyosmpbf from 'tiny-osmpbf';","symbol":"tinyosmpbf","correct":"import tinyosmpbf from 'tiny-osmpbf';"}],"quickstart":{"code":"import * as fs from 'node:fs';\nimport tinyosmpbf from 'tiny-osmpbf';\n\n// Assuming you have an osm.pbf file. Replace with your file path.\nconst filePath = 'path/to/your/map.osm.pbf';\n\ntry {\n  const dataBuffer = fs.readFileSync(filePath);\n  console.log(`Successfully read ${dataBuffer.length} bytes from ${filePath}`);\n\n  // Parse the PBF data synchronously\n  const osmData = tinyosmpbf(dataBuffer);\n\n  console.log('Parsed OSM Data (first few elements):', osmData.elements.slice(0, 2));\n  console.log('Total OSM elements:', osmData.elements.length);\n  console.log('OSM Generator:', osmData.osm3s.generator);\n} catch (error) {\n  console.error('Error parsing PBF file:', error);\n}","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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).","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0-beta.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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');`).","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.","error":"TypeError: tinyosmpbf is not a function"},{"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.","cause":"The `dataBuffer` argument provided to the `tinyosmpbf` function was not a Node.js `Buffer` or a compatible `Uint8Array` object.","error":"Error: PBF data must be a Buffer"},{"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.","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.","error":"RangeError: Array buffer allocation failed"}],"ecosystem":"npm"}