@osmix/pbf 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @osmix/pbf
 
+## 0.0.3
+
+### Patch Changes
+
+- d001d9a: Refactor to align around new main external API
+
+## 0.0.2
+
+### Patch Changes
+
+- 33d9c12: Modify types to take Uint8Array<ArrayBufferLike> for compatiblity
+
 ## 0.0.1
 
 ### Patch Changes

package/README.md

@@ -1,19 +1,19 @@
 # @osmix/pbf
 
-@osmix/pbf is a low-level TypeScript toolkit for reading and writing OpenStreetMap PBF data. It keeps the API surface close to the official protobuf schema, surfaces predictable types, and runs in Node 20+ and modern browsers through Web Streams and native compression primitives.
+Low-level TypeScript library for reading and writing OpenStreetMap PBF data. Stays close to the official protobuf schema (`osmformat.proto`, `fileformat.proto`), exposes predictable types, and runs in Node.js and modern browsers via Web Streams and native compression primitives.
 
 ## Highlights
 
-- Parse headers and primitive blocks from `ArrayBufferLike`, async iterables, or Web `ReadableStream`s.
-- Build streaming pipelines with `TransformStream` helpers instead of buffering entire files in memory.
-- Serialize header and primitive blocks back to spec-compliant blobs with size guardrails baked in.
-- Reuse generated protobuf types/readers so downstream tools can stay close to `osmformat.proto`.
-- Utility helpers handle compression, concatenation, and big-endian encoding tuned for the PBF format.
+- **Parse** headers and primitive blocks from `ArrayBufferLike`, async iterables, or Web `ReadableStream`s.
+- **Stream** with `TransformStream` helpers instead of buffering entire files in memory.
+- **Serialize** header and primitive blocks back to spec-compliant blobs with size guardrails.
+- **Types** generated from protobuf schemas for type-safe access to OSM data structures.
+- **Utilities** for compression, concatenation, and big-endian encoding tuned for the PBF format.
 
 ## Installation
 
 ```sh
-npm install @osmix/pbf
+bun add @osmix/pbf
 ```
 
 ## Usage
@@ -25,8 +25,7 @@ npm install @osmix/pbf
 ```ts
 import { readOsmPbf } from "@osmix/pbf"
 
-const response = await fetch("/fixtures/monaco.pbf")
-const { header, blocks } = await readOsmPbf(response.body)
+const { header, blocks } = await readOsmPbf(Bun.file('./monaco.pbf').stream())
 
 console.log(header.required_features)
 
@@ -37,108 +36,102 @@ for await (const block of blocks) {
 }
 ```
 
-### Stream as you go
+### Streaming with TransformStreams
 
-Use the streaming helpers when you do not want to materialize the whole file.
+For large files, use `TransformStream` helpers to process data incrementally:
 
 ```ts
-import { OsmPbfBytesToBlocksTransformStream } from "@osmix/pbf"
+import {
+	OsmPbfBytesToBlocksTransformStream,
+	OsmBlocksToPbfBytesTransformStream,
+} from "@osmix/pbf"
 
-const response = await fetch("/fixtures/monaco.pbf")
-
-await response.body
+// Decode PBF bytes into blocks
+const blocksStream = response.body!
 	.pipeThrough(new OsmPbfBytesToBlocksTransformStream())
-	.pipeTo(
-		new WritableStream({
-			write: (block) => {
-				if ("primitivegroup" in block) {
-					// Handle primitive data blocks.
-					return
-				}
-
-				console.log("Header bbox", block.bbox)
-			},
-		}),
-	)
-```
 
-### Write blocks back to PBF
-
-Serialize individual blocks into blobs, or stream them directly to a writable target.
+// Encode blocks back to PBF bytes
+const pbfStream = blocksStream
+	.pipeThrough(new OsmBlocksToPbfBytesTransformStream())
+```
 
-#### Buffer the result
+### Write a PBF file
 
 ```ts
-import { concatUint8, osmBlockToPbfBlobBytes, readOsmPbf } from "@osmix/pbf"
-
-const response = await fetch("/fixtures/monaco.pbf")
-const { header, blocks } = await readOsmPbf(response.body)
-
-const chunks: Uint8Array[] = [await osmBlockToPbfBlobBytes(header)]
-for await (const block of blocks) chunks.push(await osmBlockToPbfBlobBytes(block))
+import { osmBlockToPbfBlobBytes } from "@osmix/pbf"
 
-const fullFile = concatUint8(...chunks)
+// Serialize a header block
+const headerBytes = await osmBlockToPbfBlobBytes({
+	required_features: ["OsmSchema-V0.6", "DenseNodes"],
+	optional_features: [],
+})
 
+// Serialize a primitive block
+const dataBytes = await osmBlockToPbfBlobBytes(primitiveBlock)
 ```
 
-#### Stream to a sink
+## API
 
-Generators returned by `readOsmPbf` are single-use. Re-open the source (or buffer the blocks) if you want to stream the same dataset again.
+### Reading
 
-```ts
-import { OsmBlocksToPbfBytesTransformStream, readOsmPbf } from "@osmix/pbf"
+| Export | Description |
+|--------|-------------|
+| `readOsmPbf(data)` | Parse PBF from buffer/stream/iterable into header + blocks generator |
+| `OsmPbfBytesToBlocksTransformStream` | TransformStream: raw bytes → header/primitive blocks |
+| `createOsmPbfBlobGenerator()` | Stateful parser that extracts compressed blobs from byte chunks |
+| `osmPbfBlobsToBlocksGenerator(blobs)` | Async generator: compressed blobs → typed blocks |
+| `readOsmHeaderBlock(blob)` | Decompress and parse a header blob |
+| `readOsmPrimitiveBlock(blob)` | Decompress and parse a primitive blob |
 
-const response = await fetch("/fixtures/monaco.pbf")
-const { header, blocks } = await readOsmPbf(response.body)
+### Writing
 
-const upstream = new ReadableStream({
-	async start(controller) {
-		controller.enqueue(header)
-		for await (const block of blocks) controller.enqueue(block)
-		controller.close()
-	},
-})
+| Export | Description |
+|--------|-------------|
+| `osmBlockToPbfBlobBytes(block)` | Serialize a block to spec-compliant PBF bytes |
+| `OsmBlocksToPbfBytesTransformStream` | TransformStream: header/primitive blocks → PBF bytes |
 
-await upstream
-	.pipeThrough(new OsmBlocksToPbfBytesTransformStream())
-	.pipeTo(new WritableStream({ write: persistChunk }))
-```
+### Types
 
-`persistChunk` represents your storage layer (filesystem writes, uploads, IndexedDB, and so on). It receives `Uint8Array` pieces in the order they should be persisted.
+| Export | Description |
+|--------|-------------|
+| `OsmPbfHeaderBlock` | Parsed header with required/optional features and bbox |
+| `OsmPbfBlock` | Parsed primitive block with string table and groups |
+| `OsmPbfGroup` | Primitive group containing nodes, ways, or relations |
+| `OsmPbfDenseNodes` | Delta-encoded dense node format |
+| `OsmPbfWay`, `OsmPbfRelation`, `OsmPbfNode` | Raw entity structures |
 
-## API overview
+### Constants
 
-- `readOsmPbf(data)` – Parses binary PBF data, returning `{ header, blocks }`. Throws if the first block is not an OSM header.
-- `OsmPbfBytesToBlocksTransformStream` – Web `TransformStream` that emits the header once and then primitive blocks as they become available.
-- `OsmBlocksToPbfBytesTransformStream` – Inverse transform that turns header/primitive blocks into PBF byte blobs while enforcing size limits.
-- `createOsmPbfBlobGenerator()` – Returns a stateful generator that slices incoming bytes into compressed blob payloads (`Uint8Array`s), emitting the header blob first.
-- `osmPbfBlobsToBlocksGenerator(blobs)` – Accepts a (async) generator of compressed blobs, decompresses them, and yields the header followed by primitive blocks.
-- `osmBlockToPbfBlobBytes(block)` – Serializes a single header or primitive block, returning the BlobHeader length prefix and blob bytes as one `Uint8Array`.
-- Utility exports: `toAsyncGenerator`, `compress`, `decompress`, `concatUint8`, `uint32BE`, and the size constants from `spec.ts`. Compression helpers detect Bun and fall back to Node's zlib bindings for compatibility.
-- Generated protobuf helpers: `readHeaderBlock`, `writeHeaderBlock`, `readPrimitiveBlock`, `writePrimitiveBlock`, plus the associated TypeScript types (`OsmPbfBlock`, `OsmPbfHeaderBlock`, `OsmPbfBlob`, and friends).
+| Export | Description |
+|--------|-------------|
+| `MAX_BLOB_SIZE_BYTES` | Maximum blob size per spec (32 MiB) |
+| `RECOMMENDED_BLOB_SIZE_BYTES` | Recommended blob size (16 MiB) |
+| `MAX_ENTITIES_PER_BLOCK` | Recommended max entities per block (8,000) |
 
-## See also
+## Related Packages
 
-- [`@osmix/json`](../json/README.md) – Converts parsed blocks into ergonomic JSON or GeoJSON entities.
-- [`@osmix/core`](../core/README.md) – Uses these readers/writers for ingest and export workflows.
-- [`@osmix/change`](../change/README.md) – Builds on `@osmix/core` to generate change pipelines.
+- [`@osmix/json`](../json/README.md) – Converts parsed blocks into ergonomic JSON entities.
+- [`@osmix/core`](../core/README.md) – In-memory storage using these readers/writers.
+- [`@osmix/change`](../change/README.md) – Changeset and merge workflows.
 
-## Environment and limitations
+## Environment and Limitations
 
-- Requires runtimes with Web Streams + `CompressionStream` / `DecompressionStream` support (modern browsers, Node 20+).
-- Only `zlib_data` blobs are supported today; files containing `raw` or `lzma` payloads will throw.
-- When working with Node `Readable` / `Writable` streams, adapt them to Web Streams (`stream/web`) before passing them to these helpers.
+- Requires runtimes with Web Streams + `CompressionStream` / `DecompressionStream` (modern browsers, Node 20+, Bun).
+- Only `zlib_data` blobs are supported; files with `raw` or `lzma` payloads will throw.
+- When working with Node `Readable` / `Writable` streams, adapt them to Web Streams (`stream/web`) first.
 
-### Memory usage guidance
+### Memory Guidance
 
-- Prefer streaming transforms (`OsmPbfBytesToBlocksTransformStream` → `OsmBlocksToPbfBytesTransformStream`) for large extracts to avoid materializing entire files.
-- Re-materializing full files (e.g., concatenating all blocks into one buffer) can require memory roughly proportional to input size plus transient compression buffers.
-- In browsers, keep an eye on available heap limits (2–4 GB typical). Use chunked persistence (IndexedDB, file streams) rather than holding all bytes in RAM.
+- Prefer streaming transforms (`OsmPbfBytesToBlocksTransformStream` → `OsmBlocksToPbfBytesTransformStream`) for large extracts.
+- Materializing full files requires memory proportional to input size plus compression buffers.
+- In browsers, watch heap limits (typically 2–4 GB).
 
 ## Development
 
-- `bun run test packages/pbf`
-- `bun run lint packages/pbf`
-- `bun run typecheck packages/pbf`
+```sh
+bun run test packages/pbf
+bun run lint packages/pbf
+bun run typecheck packages/pbf
+```
 
 Run `bun run check` at the repo root before publishing to ensure formatting, lint, and type coverage.

package/dist/src/blobs-to-blocks.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Blob-to-block conversion utilities.
+ *
+ * Handles decompression and protobuf decoding of raw OSM PBF blobs into
+ * typed header and primitive block structures.
+ *
+ * @module
+ */
+import { type OsmPbfBlock, type OsmPbfHeaderBlock } from "./proto/osmformat";
+/**
+ * Decompress and decode a stream of raw PBF blobs into typed blocks.
+ *
+ * This async generator handles the transition from compressed bytes to parsed
+ * protobuf structures. The first blob is always decoded as a header block;
+ * subsequent blobs are decoded as primitive blocks containing OSM entities.
+ *
+ * @param blobs - Async or sync generator yielding compressed blob payloads.
+ * @param decompress - Optional decompression function (defaults to Web Streams zlib).
+ * @yields Header block first, then primitive blocks.
+ *
+ * @example
+ * ```ts
+ * import { osmPbfBlobsToBlocksGenerator, createOsmPbfBlobGenerator } from "@osmix/pbf"
+ *
+ * const generateBlobs = createOsmPbfBlobGenerator()
+ * const blobsGen = (async function* () {
+ *   for await (const chunk of stream) {
+ *     yield* generateBlobs(chunk)
+ *   }
+ * })()
+ *
+ * for await (const block of osmPbfBlobsToBlocksGenerator(blobsGen)) {
+ *   // First iteration yields header, rest yield primitive blocks
+ * }
+ * ```
+ */
+export declare function osmPbfBlobsToBlocksGenerator(blobs: AsyncGenerator<Uint8Array<ArrayBuffer>> | Generator<Uint8Array<ArrayBuffer>>, decompress?: (data: Uint8Array<ArrayBuffer>) => Promise<Uint8Array<ArrayBuffer>>): AsyncGenerator<OsmPbfHeaderBlock | OsmPbfBlock, void, unknown>;
+/**
+ * Decompress and parse a header block from a compressed blob.
+ *
+ * @param compressedBlob - Zlib-compressed protobuf header blob.
+ * @param decompress - Optional decompression function.
+ * @returns Parsed header block with required/optional features and bbox.
+ */
+export declare function readOsmHeaderBlock(compressedBlob: Uint8Array<ArrayBuffer>, decompress?: (data: Uint8Array<ArrayBuffer>) => Promise<Uint8Array<ArrayBuffer>>): Promise<OsmPbfHeaderBlock>;
+/**
+ * Decompress and parse a primitive block from a compressed blob.
+ *
+ * @param compressedBlob - Zlib-compressed protobuf primitive blob.
+ * @param decompress - Optional decompression function.
+ * @returns Parsed primitive block with string table and primitive groups.
+ */
+export declare function readOsmPrimitiveBlock(compressedBlob: Uint8Array<ArrayBuffer>, decompress?: (data: Uint8Array<ArrayBuffer>) => Promise<Uint8Array<ArrayBuffer>>): Promise<OsmPbfBlock>;
+//# sourceMappingURL=blobs-to-blocks.d.ts.map

package/dist/src/blobs-to-blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blobs-to-blocks.d.ts","sourceRoot":"","sources":["../../src/blobs-to-blocks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,iBAAiB,EAGtB,MAAM,mBAAmB,CAAA;AAG1B;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAuB,4BAA4B,CAClD,KAAK,EACF,cAAc,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,GACvC,SAAS,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,EACrC,UAAU,GAAE,CACX,IAAI,EAAE,UAAU,CAAC,WAAW,CAAC,KACzB,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAiB,kEAWrD;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACvC,cAAc,EAAE,UAAU,CAAC,WAAW,CAAC,EACvC,UAAU,GAAE,CACX,IAAI,EAAE,UAAU,CAAC,WAAW,CAAC,KACzB,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAiB,GACnD,OAAO,CAAC,iBAAiB,CAAC,CAI5B;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAC1C,cAAc,EAAE,UAAU,CAAC,WAAW,CAAC,EACvC,UAAU,GAAE,CACX,IAAI,EAAE,UAAU,CAAC,WAAW,CAAC,KACzB,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAiB,GACnD,OAAO,CAAC,WAAW,CAAC,CAItB"}

package/dist/src/blobs-to-blocks.js

@@ -0,0 +1,75 @@
+/**
+ * Blob-to-block conversion utilities.
+ *
+ * Handles decompression and protobuf decoding of raw OSM PBF blobs into
+ * typed header and primitive block structures.
+ *
+ * @module
+ */
+import Pbf from "pbf";
+import { readHeaderBlock, readPrimitiveBlock, } from "./proto/osmformat";
+import { webDecompress } from "./utils";
+/**
+ * Decompress and decode a stream of raw PBF blobs into typed blocks.
+ *
+ * This async generator handles the transition from compressed bytes to parsed
+ * protobuf structures. The first blob is always decoded as a header block;
+ * subsequent blobs are decoded as primitive blocks containing OSM entities.
+ *
+ * @param blobs - Async or sync generator yielding compressed blob payloads.
+ * @param decompress - Optional decompression function (defaults to Web Streams zlib).
+ * @yields Header block first, then primitive blocks.
+ *
+ * @example
+ * ```ts
+ * import { osmPbfBlobsToBlocksGenerator, createOsmPbfBlobGenerator } from "@osmix/pbf"
+ *
+ * const generateBlobs = createOsmPbfBlobGenerator()
+ * const blobsGen = (async function* () {
+ *   for await (const chunk of stream) {
+ *     yield* generateBlobs(chunk)
+ *   }
+ * })()
+ *
+ * for await (const block of osmPbfBlobsToBlocksGenerator(blobsGen)) {
+ *   // First iteration yields header, rest yield primitive blocks
+ * }
+ * ```
+ */
+export async function* osmPbfBlobsToBlocksGenerator(blobs, decompress = webDecompress) {
+    let headerRead = false;
+    for await (const blob of blobs) {
+        if (!headerRead) {
+            headerRead = true;
+            yield readOsmHeaderBlock(blob, decompress);
+        }
+        else {
+            yield readOsmPrimitiveBlock(blob, decompress);
+        }
+    }
+}
+/**
+ * Decompress and parse a header block from a compressed blob.
+ *
+ * @param compressedBlob - Zlib-compressed protobuf header blob.
+ * @param decompress - Optional decompression function.
+ * @returns Parsed header block with required/optional features and bbox.
+ */
+export async function readOsmHeaderBlock(compressedBlob, decompress = webDecompress) {
+    const decompressedBlob = await decompress(compressedBlob);
+    const pbf = new Pbf(decompressedBlob);
+    return readHeaderBlock(pbf);
+}
+/**
+ * Decompress and parse a primitive block from a compressed blob.
+ *
+ * @param compressedBlob - Zlib-compressed protobuf primitive blob.
+ * @param decompress - Optional decompression function.
+ * @returns Parsed primitive block with string table and primitive groups.
+ */
+export async function readOsmPrimitiveBlock(compressedBlob, decompress = webDecompress) {
+    const decompressedBlob = await decompress(compressedBlob);
+    const pbf = new Pbf(decompressedBlob);
+    return readPrimitiveBlock(pbf);
+}
+//# sourceMappingURL=blobs-to-blocks.js.map

package/dist/src/blobs-to-blocks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blobs-to-blocks.js","sourceRoot":"","sources":["../../src/blobs-to-blocks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,GAAG,MAAM,KAAK,CAAA;AACrB,OAAO,EAGN,eAAe,EACf,kBAAkB,GAClB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,4BAA4B,CAClD,KAEqC,EACrC,aAEwC,aAAa;IAErD,IAAI,UAAU,GAAG,KAAK,CAAA;IACtB,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAChC,IAAI,CAAC,UAAU,EAAE,CAAC;YACjB,UAAU,GAAG,IAAI,CAAA;YACjB,MAAM,kBAAkB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;QAC3C,CAAC;aAAM,CAAC;YACP,MAAM,qBAAqB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;QAC9C,CAAC;IACF,CAAC;AACF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACvC,cAAuC,EACvC,aAEwC,aAAa;IAErD,MAAM,gBAAgB,GAAG,MAAM,UAAU,CAAC,cAAc,CAAC,CAAA;IACzD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,CAAA;IACrC,OAAO,eAAe,CAAC,GAAG,CAAC,CAAA;AAC5B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAC1C,cAAuC,EACvC,aAEwC,aAAa;IAErD,MAAM,gBAAgB,GAAG,MAAM,UAAU,CAAC,cAAc,CAAC,CAAA;IACzD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,CAAA;IACrC,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAA;AAC/B,CAAC"}

package/dist/src/blocks-to-pbf.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Block-to-PBF serialization utilities.
+ *
+ * Converts parsed OSM header and primitive blocks back into spec-compliant
+ * PBF byte sequences with proper framing, compression, and size validation.
+ *
+ * @module
+ */
+import type { OsmPbfBlock, OsmPbfHeaderBlock } from "./proto/osmformat";
+/**
+ * Serialize a header or primitive block into spec-compliant PBF bytes.
+ *
+ * Handles protobuf encoding, zlib compression, blob wrapping, and length prefixing.
+ * Validates output against OSM PBF specification size limits and logs warnings
+ * if recommended sizes are exceeded.
+ *
+ * @param block - Parsed header or primitive block to encode.
+ * @param compress - Optional compression function (defaults to Web Streams zlib).
+ * @returns Complete blob bytes: 4-byte length prefix + BlobHeader + Blob.
+ * @throws If blob exceeds maximum size limits (64 KiB header, 32 MiB data).
+ *
+ * @example
+ * ```ts
+ * import { osmBlockToPbfBlobBytes } from "@osmix/pbf"
+ *
+ * const headerBytes = await osmBlockToPbfBlobBytes({
+ *   required_features: ["OsmSchema-V0.6", "DenseNodes"],
+ *   optional_features: [],
+ * })
+ * ```
+ */
+export declare function osmBlockToPbfBlobBytes(block: OsmPbfBlock | OsmPbfHeaderBlock, compress?: (data: Uint8Array<ArrayBuffer>) => Promise<Uint8Array<ArrayBuffer>>): Promise<Uint8Array<ArrayBufferLike>>;
+/**
+ * Web `TransformStream` that encodes OSM blocks into PBF byte chunks.
+ *
+ * Accepts a stream of header and primitive blocks and outputs spec-compliant
+ * PBF bytes. The header block must be the first item in the stream.
+ *
+ * @throws If a primitive block is received before the header.
+ *
+ * @example
+ * ```ts
+ * import { OsmBlocksToPbfBytesTransformStream } from "@osmix/pbf"
+ *
+ * const pbfStream = blocksStream.pipeThrough(new OsmBlocksToPbfBytesTransformStream())
+ * await pbfStream.pipeTo(writableFile)
+ * ```
+ */
+export declare class OsmBlocksToPbfBytesTransformStream extends TransformStream<OsmPbfHeaderBlock | OsmPbfBlock, Uint8Array> {
+    headerEnqueued: boolean;
+    constructor();
+}
+//# sourceMappingURL=blocks-to-pbf.d.ts.map

package/dist/src/blocks-to-pbf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks-to-pbf.d.ts","sourceRoot":"","sources":["../../src/blocks-to-pbf.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAUvE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,sBAAsB,CAC3C,KAAK,EAAE,WAAW,GAAG,iBAAiB,EACtC,QAAQ,GAAE,CACT,IAAI,EAAE,UAAU,CAAC,WAAW,CAAC,KACzB,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAe,wCAqDnD;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,kCAAmC,SAAQ,eAAe,CACtE,iBAAiB,GAAG,WAAW,EAC/B,UAAU,CACV;IACA,cAAc,UAAQ;;CAYtB"}

package/dist/{blocks-to-pbf.js → src/blocks-to-pbf.js}

@@ -1,15 +1,39 @@
+/**
+ * Block-to-PBF serialization utilities.
+ *
+ * Converts parsed OSM header and primitive blocks back into spec-compliant
+ * PBF byte sequences with proper framing, compression, and size validation.
+ *
+ * @module
+ */
 import Pbf from "pbf";
 import { writeBlob, writeBlobHeader } from "./proto/fileformat";
 import { writeHeaderBlock, writePrimitiveBlock } from "./proto/osmformat";
 import { MAX_BLOB_SIZE_BYTES, MAX_HEADER_SIZE_BYTES, RECOMMENDED_BLOB_SIZE_BYTES, RECOMMENDED_HEADER_SIZE_BYTES, } from "./spec";
-import { compress, concatUint8, uint32BE } from "./utils";
+import { concatUint8, uint32BE, webCompress } from "./utils";
 /**
- * Serializes a header or primitive block into a spec-compliant compressed blob.
- * Automatically sets the blob type, compresses the payload, and enforces size guardrails.
+ * Serialize a header or primitive block into spec-compliant PBF bytes.
+ *
+ * Handles protobuf encoding, zlib compression, blob wrapping, and length prefixing.
+ * Validates output against OSM PBF specification size limits and logs warnings
+ * if recommended sizes are exceeded.
+ *
  * @param block - Parsed header or primitive block to encode.
- * @returns BlobHeader length prefix + Blob bytes as a single Uint8Array.
+ * @param compress - Optional compression function (defaults to Web Streams zlib).
+ * @returns Complete blob bytes: 4-byte length prefix + BlobHeader + Blob.
+ * @throws If blob exceeds maximum size limits (64 KiB header, 32 MiB data).
+ *
+ * @example
+ * ```ts
+ * import { osmBlockToPbfBlobBytes } from "@osmix/pbf"
+ *
+ * const headerBytes = await osmBlockToPbfBlobBytes({
+ *   required_features: ["OsmSchema-V0.6", "DenseNodes"],
+ *   optional_features: [],
+ * })
+ * ```
  */
-export async function osmBlockToPbfBlobBytes(block) {
+export async function osmBlockToPbfBlobBytes(block, compress = webCompress) {
     const contentPbf = new Pbf();
     let type;
     if ("primitivegroup" in block) {
@@ -54,8 +78,20 @@ export async function osmBlockToPbfBlobBytes(block) {
     return concatUint8(blobHeaderSize, blobHeader, blob);
 }
 /**
- * Web `TransformStream` that converts OSM header/data blocks into PBF byte chunks.
- * Throws if the header is not the first block and reuses `osmBlockToPbfBlobBytes` for encoding.
+ * Web `TransformStream` that encodes OSM blocks into PBF byte chunks.
+ *
+ * Accepts a stream of header and primitive blocks and outputs spec-compliant
+ * PBF bytes. The header block must be the first item in the stream.
+ *
+ * @throws If a primitive block is received before the header.
+ *
+ * @example
+ * ```ts
+ * import { OsmBlocksToPbfBytesTransformStream } from "@osmix/pbf"
+ *
+ * const pbfStream = blocksStream.pipeThrough(new OsmBlocksToPbfBytesTransformStream())
+ * await pbfStream.pipeTo(writableFile)
+ * ```
  */
 export class OsmBlocksToPbfBytesTransformStream extends TransformStream {
     headerEnqueued = false;
@@ -71,3 +107,4 @@ export class OsmBlocksToPbfBytesTransformStream extends TransformStream {
         });
     }
 }
+//# sourceMappingURL=blocks-to-pbf.js.map

package/dist/src/blocks-to-pbf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks-to-pbf.js","sourceRoot":"","sources":["../../src/blocks-to-pbf.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @osmix/pbf - Low-level OSM PBF parsing and serialization.
+ *
+ * Provides streaming primitives for reading and writing OpenStreetMap PBF files
+ * using Web Streams and native compression APIs. Stays close to the official
+ * protobuf schema (`osmformat.proto`, `fileformat.proto`) while exposing
+ * predictable TypeScript types.
+ *
+ * Key capabilities:
+ * - **Parse**: Read headers and primitive blocks from `ArrayBuffer`, async iterables, or `ReadableStream`.
+ * - **Stream**: Use `TransformStream` helpers to process large files without buffering entirely in memory.
+ * - **Serialize**: Write header and primitive blocks back to spec-compliant blobs with size guardrails.
+ * - **Types**: Generated protobuf readers/writers and TypeScript interfaces for OSM data structures.
+ *
+ * @example
+ * ```ts
+ * import { readOsmPbf } from "@osmix/pbf"
+ *
+ * const { header, blocks } = await readOsmPbf(Bun.file('./monaco.pbf').stream())
+ * console.log(header.required_features)
+ *
+ * for await (const block of blocks) {
+ *   console.log(block.primitivegroup.length, "groups")
+ * }
+ * ```
+ *
+ * @module @osmix/pbf
+ */
+export * from "./blobs-to-blocks";
+export * from "./blocks-to-pbf";
+export * from "./pbf-to-blobs";
+export * from "./pbf-to-blocks";
+export * from "./proto/fileformat";
+export * from "./proto/osmformat";
+export * from "./spec";
+export * from "./utils";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,QAAQ,CAAA;AACtB,cAAc,SAAS,CAAA"}

package/dist/src/index.js

@@ -0,0 +1,37 @@
+/**
+ * @osmix/pbf - Low-level OSM PBF parsing and serialization.
+ *
+ * Provides streaming primitives for reading and writing OpenStreetMap PBF files
+ * using Web Streams and native compression APIs. Stays close to the official
+ * protobuf schema (`osmformat.proto`, `fileformat.proto`) while exposing
+ * predictable TypeScript types.
+ *
+ * Key capabilities:
+ * - **Parse**: Read headers and primitive blocks from `ArrayBuffer`, async iterables, or `ReadableStream`.
+ * - **Stream**: Use `TransformStream` helpers to process large files without buffering entirely in memory.
+ * - **Serialize**: Write header and primitive blocks back to spec-compliant blobs with size guardrails.
+ * - **Types**: Generated protobuf readers/writers and TypeScript interfaces for OSM data structures.
+ *
+ * @example
+ * ```ts
+ * import { readOsmPbf } from "@osmix/pbf"
+ *
+ * const { header, blocks } = await readOsmPbf(Bun.file('./monaco.pbf').stream())
+ * console.log(header.required_features)
+ *
+ * for await (const block of blocks) {
+ *   console.log(block.primitivegroup.length, "groups")
+ * }
+ * ```
+ *
+ * @module @osmix/pbf
+ */
+export * from "./blobs-to-blocks";
+export * from "./blocks-to-pbf";
+export * from "./pbf-to-blobs";
+export * from "./pbf-to-blocks";
+export * from "./proto/fileformat";
+export * from "./proto/osmformat";
+export * from "./spec";
+export * from "./utils";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,QAAQ,CAAA;AACtB,cAAc,SAAS,CAAA"}

package/dist/src/pbf-to-blobs.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Create a stateful parser that extracts compressed blobs from raw PBF bytes.
+ *
+ * OSM PBF files consist of length-prefixed blobs. This function returns a generator
+ * that accumulates incoming byte chunks and yields complete compressed blobs as they
+ * become available. The caller is responsible for decompression.
+ *
+ * The first yielded blob contains the file header; subsequent blobs contain primitive data.
+ *
+ * @returns A generator function that accepts byte chunks and yields compressed blob payloads.
+ *
+ * @example
+ * ```ts
+ * import { createOsmPbfBlobGenerator } from "@osmix/pbf"
+ *
+ * const generateBlobs = createOsmPbfBlobGenerator()
+ *
+ * for await (const chunk of stream) {
+ *   for (const compressedBlob of generateBlobs(chunk)) {
+ *     // Decompress and parse blob...
+ *   }
+ * }
+ * ```
+ */
+export declare function createOsmPbfBlobGenerator(): (chunk: Uint8Array) => Generator<Uint8Array<ArrayBuffer>, void, unknown>;
+//# sourceMappingURL=pbf-to-blobs.d.ts.map

package/dist/src/pbf-to-blobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pbf-to-blobs.d.ts","sourceRoot":"","sources":["../../src/pbf-to-blobs.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,yBAAyB,KAWb,OAAO,UAAU,uDAiC5C"}