KRBC — Keyed Range Binary Container

KRBC is a small binary container format and utility library for working with key-addressable byte ranges in large binary files.

It is designed to make partial read/write simple and predictable across Browser and Node.js, without imposing any structure on the stored data.

KRBC does not care what your data is. It only maps:

key[]  ->  [byteFrom, byteTo)

What KRBC is good for

• Partial loading of large binary files
• Tile / chunk / bbox based data access
• CAD, GIS, map, or geometry data
• Streaming binary assets
• Any scenario where data is split into independent ranges

Installation

npm install krbc

Data model

KRBC works with an array of entries.
Each entry consists of a key and a binary payload.

Keys are fixed-size arrays. Their meaning is entirely application-defined.

Ranges are always stored as [from, to) (end-exclusive).

Browser data example

const textEncoder = new TextEncoder()

const data = [
	{
		key: [ 0, 1, 2 ],
		data: textEncoder.encode( "Hello" ),
	},
	{
		key: [ 3, 4, 5 ],
		data: textEncoder.encode( "World" ),
	}
]

Node.js data example

const data = [
	{
		key: [ 0, 1, 2 ],
		data: Buffer.from( "Hello" ),
	},
	{
		key: [ 3, 4, 5 ],
		data: Buffer.from( "World" ),
	}
]

Browser example

Write (OPFS)

import * as KRBC from "krbc"

const codec = KRBC.createElementCodec( "int32" )

await KRBC.writeOPFS( "example.krbc", data, codec )

Export file (download)

await KRBC.exportFile( "example.krbc" )

Read

import * as KRBC from "krbc"

const codec = KRBC.createElementCodec( "int32" )
const index = await KRBC.readIndex( "/example.krbc" )

for ( const e of index.entries ) {

	const key = KRBC.unpackKey( e.key, codec )
	const bytes = await KRBC.fetchRange( "/example.krbc", e.range )

	console.log( key, new TextDecoder().decode( bytes ) )
}

Node.js example

Write

import * as KRBC from "krbc"

const codec = KRBC.createElementCodec( "int32" )

KRBC.writeFile( "example.krbc", data, codec )

Read

import * as KRBC from "krbc"

const codec = KRBC.createElementCodec( "int32" )
const index = KRBC.readIndex( "example.krbc" )

for ( const e of index.entries ) {

	const key = KRBC.unpackKey( e.key, codec )
	const bytes = KRBC.readRange( "example.krbc", e.range )

	console.log( key, bytes.toString() )
}

Notes

• Ranges are always [from, to) (end-exclusive)
• Index entries may overlap or duplicate
• KRBC does not validate or interpret keys
• Binary layout is stable and deterministic