Files
skills/docs/foundation/bitpacker/bitpacker/README.md
2026-05-29 08:20:56 +01:00

52 KiB

@suaveplan/bitpacker - Core bit-level binary packing: BitWriter, BitReader, BitPacker, and strategy manager

Summary

Core bit-level binary packing library. Provides BitWriter, BitReader, BitPacker, and a pluggable strategy system for schema-driven serialization.

Documentation tree

  • bit-reader — (no submodules) - index — Path: `bitpacker/src/bit-reader/index.t…
    • bit-reader — (no submodules) - index — Path: `bitpacker/src/bit-reader/index.t…
    • index — Path: bitpacker/src/bit-reader/index.ts Export: See source for details.
  • bit-writer — (no submodules) - index — Path: `bitpacker/src/bit-writer/index.t…
    • bit-writer — (no submodules) - index — Path: `bitpacker/src/bit-writer/index.t…
    • index — Path: bitpacker/src/bit-writer/index.ts Export: See source for details.
  • safety — (no submodules)
  • invalid — Path: bitpacker/src/core/strategies/invalid.ts Export: See source for details.
  • manager — Path: src/core/strategies/manager.ts Export: PackingStrategyManager (class)
  • types — Path: src/core/strategies/types.ts Export: PackingStrategy (interface), PackingContext (interface)
  • types.schema — Zod schemas for PackingStrategy and PackingContext, the two extension-point types that flow across the `@suaveplan/…
  • bitpacker — Path: src/core/bitpacker.ts Export: BitPacker (class), BitPackerOptions (interface)
  • bitpacker.schema — Zod schema for BitPackerOptions, the configuration bundle accepted by the BitPacker class constructor. It validates…
  • error-codes — Path: bitpacker/src/error-codes.ts Export: See source for details.
    • error-codes — Path: bitpacker/src/error-codes.ts Export: See source for details.
  • handlers — (no submodules)
  • pack-iterator — (no submodules)
  • otel — (no submodules)
  • packers — (no submodules) - array-packer — _(no submodu…
  • performance — (no submodules)
    • buffer-pool — Reusable Uint8Array pool for the bitpacker hot path. Instead of allocating a fresh buffer per pack/unpack call (which…
    • lru-cache — Bounded-size LRU (least-recently-used) cache used to memoize expensive bitpacker computations: schema-to-bit-width deri…
    • performance-monitor — Lightweight performance instrumentation for @suaveplan/bitpacker's hot path. PerformanceMonitor collects per-operat…
    • performance — (no submodules)
  • register-schemas — Idempotent integration with @suaveplan/schema-registry for the core @suaveplan/bitpacker package. Exposes a single…
    • register-schemas — Idempotent integration with @suaveplan/schema-registry for the core @suaveplan/bitpacker package. Exposes a single…
  • serialization — (no submodules)
  • base-types — Foundation type companions for the bitpacker — the typed-array unions (IntArray, FloatArray), the integer/float typ…
  • common — Path: bitpacker/src/types/common.ts Export: See source for details.
  • index — Path: src/types/index.ts Exports: Schema type definitions, type guards, utility types
  • key-types — Public type companions for the legacy key-material API. BitPackerKey is the canonical byte-array alias for any signin…
  • packer-types — Public configuration types for the legacy BitPackerConfig surface — the all-in-one options bundle that pre-modular bi…
  • schema-versioning-types — Type companions for the schema-version migration framework — SchemaVersion, MigrationFunction, SchemaMigration, `…
  • schemas — Path: src/types.ts Export: Schema type guards, BitPackerSchema union, token types
  • validation-types — Type companions for the legacy validation API surfaced from @suaveplan/bitpacker's root export. These types — `BitPac…
  • types.schema — Zod schemas for the recursive BitPackerSchema union and every variant it can take. These schemas are the single sourc…
    • types.schema — Zod schemas for the recursive BitPackerSchema union and every variant it can take. These schemas are the single sourc…
  • utils — (no submodules) - zigzag — Path: bitpacker/src/utils/zigzag.ts……
    • float-utils — Float-bit-pattern conversion helpers used by the float packer and any consumer that needs to round-trip a number thro…
    • pack-bits — Path: bitpacker/src/utils/pack-bits.ts Export: See source for details.
    • schema-validators — Per-shape schema validation helpers used internally by @suaveplan/bitpacker's legacy validator surface. Each function…
    • type-guards — Generic type-guard helpers used across @suaveplan/bitpacker for safe narrowing of unknown values into well-typed sh…
    • utils — (no submodules) - zigzag — Path: bitpacker/src/utils/zigzag.ts……
    • zigzag — Path: bitpacker/src/utils/zigzag.ts Export: See source for details.
  • bit-schema — Path: src/bit-schema.ts Export: defineBitSchema (function)
  • index — Path: bitpacker/src/index.ts Export: See source for details.
- index — **Path:** `bitpacker/src/bit-reader/index.t…
  • bit-reader — (no submodules)- index — Path: `bitpacker/src/bit-reader/index.t…

  • index — Path: bitpacker/src/bit-reader/index.ts Export: See source for details.

  • bit-writer — (no submodules)- index — Path: `bitpacker/src/bit-writer/index.t…

    • bit-writer — (no submodules)- index — Path: `bitpacker/src/bit-writer/index.t…
    • index — Path: bitpacker/src/bit-writer/index.ts Export: See source for details.
  • safety — (no submodules)- safety-checks — (no submodules)- invalid — Path: bitpacker/src/core/strategies/invalid.ts Export: See source for details.

  • manager — Path: src/core/strategies/manager.ts Export: PackingStrategyManager (class)

  • types — Path: src/core/strategies/types.ts Export: PackingStrategy (interface), PackingContext (interface)

  • types.schema — Zod schemas for PackingStrategy and PackingContext, the two extension-point types that flow across the `@suaveplan/…

  • bitpacker — Path: src/core/bitpacker.ts Export: BitPacker (class), BitPackerOptions (interface)

  • bitpacker.schema — Zod schema for BitPackerOptions, the configuration bundle accepted by the BitPacker class constructor. It validates…

  • handlers — (no submodules)- custom-type-registry — (no submodules)- pack-iterator — (no submodules)- pack-iterator — (no submodules)- otel — (no submodules)- instruments — (no submodules)- packers — (no submodules)- array — (no submodules)- array-packer — (no submodules)- base — (no submodules)- base-packer — (no submodules)- bigint — (no submodules)- bigint-packer — (no submodules)- bigint-array — (no submodules)- bigint-array-packer — (no submodules)- bit-array — (no submodules)- bit-array-packer — (no submodules)- bit-operations — (no submodules)- bit-operations — (no submodules)- boolean — (no submodules)- boolean-packer — (no submodules)- datetime — (no submodules)- datetime-packer — (no submodules)- enum — (no submodules)- enum-packer — (no submodules)- float — (no submodules)- float-packer — (no submodules)- integer — (no submodules)- integer-packer — (no submodules)- map — (no submodules)- map-packer — (no submodules)- set — (no submodules)- set-packer — (no submodules)- string — (no submodules)- string-packer — (no submodules)- uuid — (no submodules)- uuid-packer — (no submodules)- varint — (no submodules)- varint-packer — (no submodules)- index — (no submodules)- performance — (no submodules)- buffer-pool — Reusable Uint8Array pool for the bitpacker hot path. Instead of allocating a fresh buffer per pack/unpack call (which…

    • lru-cache — Bounded-size LRU (least-recently-used) cache used to memoize expensive bitpacker computations: schema-to-bit-width deri…
    • performance-monitor — Lightweight performance instrumentation for @suaveplan/bitpacker's hot path. PerformanceMonitor collects per-operat…
    • performance — (no submodules)- serialization — (no submodules)- serialization — (no submodules)- base-types — Foundation type companions for the bitpacker — the typed-array unions (IntArray, FloatArray), the integer/float typ…
  • common — Path: bitpacker/src/types/common.ts Export: See source for details.

  • index — Path: src/types/index.ts Exports: Schema type definitions, type guards, utility types

  • key-types — Public type companions for the legacy key-material API. BitPackerKey is the canonical byte-array alias for any signin…

  • packer-types — Public configuration types for the legacy BitPackerConfig surface — the all-in-one options bundle that pre-modular bi…

  • schema-versioning-types — Type companions for the schema-version migration framework — SchemaVersion, MigrationFunction, SchemaMigration, `…

  • validation-types — Type companions for the legacy validation API surfaced from @suaveplan/bitpacker's root export. These types — `BitPac…

  • utils — (no submodules)- zigzag — Path: bitpacker/src/utils/zigzag.ts……

    • float-utils — Float-bit-pattern conversion helpers used by the float packer and any consumer that needs to round-trip a number thro…
    • pack-bits — Path: bitpacker/src/utils/pack-bits.ts Export: See source for details.
    • schema-validators — Per-shape schema validation helpers used internally by @suaveplan/bitpacker's legacy validator surface. Each function…
    • type-guards — Generic type-guard helpers used across @suaveplan/bitpacker for safe narrowing of unknown values into well-typed sh…
    • utils — (no submodules)- zigzag — Path: bitpacker/src/utils/zigzag.ts……
    • zigzag — Path: bitpacker/src/utils/zigzag.ts Export: See source for details.
  • bit-schema — Path: src/bit-schema.ts Export: defineBitSchema (function)

  • error-codes — Path: bitpacker/src/error-codes.ts Export: See source for details.

  • index — Path: bitpacker/src/index.ts Export: See source for details.

  • register-schemas — Idempotent integration with @suaveplan/schema-registry for the core @suaveplan/bitpacker package. Exposes a single…

  • types — Path: src/types.ts Export: Schema type guards, BitPackerSchema union, token types

  • types.schema — Zod schemas for the recursive BitPackerSchema union and every variant it can take. These schemas are the single sourc…

  • index — Path: `bitpacker/src/bit-reader/index.t…

  • bit-reader — (no submodules)- index — Path: `bitpacker/src/bit-reader/index.t…

  • index — Path: bitpacker/src/bit-reader/index.ts Export: See source for details.

  • bit-writer — (no submodules)- index — Path: `bitpacker/src/bit-writer/index.t…

    • bit-writer — (no submodules)- index — Path: `bitpacker/src/bit-writer/index.t…
    • index — Path: bitpacker/src/bit-writer/index.ts Export: See source for details.
  • safety — (no submodules)- safety-checks — (no submodules)- invalid — Path: bitpacker/src/core/strategies/invalid.ts Export: See source for details.

  • manager — Path: src/core/strategies/manager.ts Export: PackingStrategyManager (class)

  • types — Path: src/core/strategies/types.ts Export: PackingStrategy (interface), PackingContext (interface)

  • types.schema — Zod schemas for PackingStrategy and PackingContext, the two extension-point types that flow across the `@suaveplan/…

  • bitpacker — Path: src/core/bitpacker.ts Export: BitPacker (class), BitPackerOptions (interface)

  • bitpacker.schema — Zod schema for BitPackerOptions, the configuration bundle accepted by the BitPacker class constructor. It validates…

  • handlers — (no submodules)- custom-type-registry — (no submodules)- pack-iterator — (no submodules)- pack-iterator — (no submodules)- otel — (no submodules)- instruments — (no submodules)- packers — (no submodules)- array-packer — <!-- begin:au…

  • performance — (no submodules)- buffer-pool — Reusable Uint8Array pool for the bitpacker hot path. Instead of allocating a fresh buffer per pack/unpack call (which…

    • lru-cache — Bounded-size LRU (least-recently-used) cache used to memoize expensive bitpacker computations: schema-to-bit-width deri…
    • performance-monitor — Lightweight performance instrumentation for @suaveplan/bitpacker's hot path. PerformanceMonitor collects per-operat…
    • performance — (no submodules)- serialization — (no submodules)- serialization — (no submodules)- base-types — Foundation type companions for the bitpacker — the typed-array unions (IntArray, FloatArray), the integer/float typ…
  • common — Path: bitpacker/src/types/common.ts Export: See source for details.

  • index — Path: src/types/index.ts Exports: Schema type definitions, type guards, utility types

  • key-types — Public type companions for the legacy key-material API. BitPackerKey is the canonical byte-array alias for any signin…

  • packer-types — Public configuration types for the legacy BitPackerConfig surface — the all-in-one options bundle that pre-modular bi…

  • schema-versioning-types — Type companions for the schema-version migration framework — SchemaVersion, MigrationFunction, SchemaMigration, `…

  • validation-types — Type companions for the legacy validation API surfaced from @suaveplan/bitpacker's root export. These types — `BitPac…

  • utils — (no submodules)- zigzag — Path: bitpacker/src/utils/zigzag.ts……

    • float-utils — Float-bit-pattern conversion helpers used by the float packer and any consumer that needs to round-trip a number thro…
    • pack-bits — Path: bitpacker/src/utils/pack-bits.ts Export: See source for details.
    • schema-validators — Per-shape schema validation helpers used internally by @suaveplan/bitpacker's legacy validator surface. Each function…
    • type-guards — Generic type-guard helpers used across @suaveplan/bitpacker for safe narrowing of unknown values into well-typed sh…
    • utils — (no submodules)- zigzag — Path: bitpacker/src/utils/zigzag.ts……
    • zigzag — Path: bitpacker/src/utils/zigzag.ts Export: See source for details.
  • bit-schema — Path: src/bit-schema.ts Export: defineBitSchema (function)

  • error-codes — Path: bitpacker/src/error-codes.ts Export: See source for details.

  • index — Path: bitpacker/src/index.ts Export: See source for details.

  • register-schemas — Idempotent integration with @suaveplan/schema-registry for the core @suaveplan/bitpacker package. Exposes a single…

  • types — Path: src/types.ts Export: Schema type guards, BitPackerSchema union, token types

  • types.schema — Zod schemas for the recursive BitPackerSchema union and every variant it can take. These schemas are the single sourc…

  • index — Path: `bitpacker/src/bit-reader/index.t…

  • bit-reader — (no submodules)- index — Path: `bitpacker/src/bit-reader/index.t…

  • index — Path: bitpacker/src/bit-reader/index.ts Export: See source for details.

  • bit-writer — (no submodules)- index — Path: `bitpacker/src/bit-writer/index.t…

    • bit-writer — (no submodules)- index — Path: `bitpacker/src/bit-writer/index.t…
    • index — Path: bitpacker/src/bit-writer/index.ts Export: See source for details.
  • safety — (no submodules)- safety-checks — (no submodules)- invalid — Path: bitpacker/src/core/strategies/invalid.ts Export: See source for details.

  • manager — Path: src/core/strategies/manager.ts Export: PackingStrategyManager (class)

  • types — Path: src/core/strategies/types.ts Export: PackingStrategy (interface), PackingContext (interface)

  • types.schema — Zod schemas for PackingStrategy and PackingContext, the two extension-point types that flow across the `@suaveplan/…

  • bitpacker — Path: src/core/bitpacker.ts Export: BitPacker (class), BitPackerOptions (interface)

  • bitpacker.schema — Zod schema for BitPackerOptions, the configuration bundle accepted by the BitPacker class constructor. It validates…

  • handlers — (no submodules)- custom-type-registry — (no submodules)- pack-iterator — (no submodules)- pack-iterator — (no submodules)- otel — (no submodules)- instruments — (no submodules)- packers — (no submodules)- array-packer — _(no submod…

  • performance — (no submodules)- buffer-pool — Reusable Uint8Array pool for the bitpacker hot path. Instead of allocating a fresh buffer per pack/unpack call (which…

    • lru-cache — Bounded-size LRU (least-recently-used) cache used to memoize expensive bitpacker computations: schema-to-bit-width deri…
    • performance-monitor — Lightweight performance instrumentation for @suaveplan/bitpacker's hot path. PerformanceMonitor collects per-operat…
    • performance — (no submodules)- serialization — (no submodules)- serialization — (no submodules)- base-types — Foundation type companions for the bitpacker — the typed-array unions (IntArray, FloatArray), the integer/float typ…
  • common — Path: bitpacker/src/types/common.ts Export: See source for details.

  • index — Path: src/types/index.ts Exports: Schema type definitions, type guards, utility types

  • key-types — Public type companions for the legacy key-material API. BitPackerKey is the canonical byte-array alias for any signin…

  • packer-types — Public configuration types for the legacy BitPackerConfig surface — the all-in-one options bundle that pre-modular bi…

  • schema-versioning-types — Type companions for the schema-version migration framework — SchemaVersion, MigrationFunction, SchemaMigration, `…

  • validation-types — Type companions for the legacy validation API surfaced from @suaveplan/bitpacker's root export. These types — `BitPac…

  • utils — (no submodules)- zigzag — Path: bitpacker/src/utils/zigzag.ts…

    • float-utils — Float-bit-pattern conversion helpers used by the float packer and any consumer that needs to round-trip a number thro…
    • pack-bits — Path: bitpacker/src/utils/pack-bits.ts Export: See source for details.
    • schema-validators — Per-shape schema validation helpers used internally by @suaveplan/bitpacker's legacy validator surface. Each function…
    • type-guards — Generic type-guard helpers used across @suaveplan/bitpacker for safe narrowing of unknown values into well-typed sh…
    • utils — (no submodules)- zigzag — Path: bitpacker/src/utils/zigzag.ts…
    • zigzag — Path: bitpacker/src/utils/zigzag.ts Export: See source for details.
  • bit-schema — Path: src/bit-schema.ts Export: defineBitSchema (function)

  • error-codes — Path: bitpacker/src/error-codes.ts Export: See source for details.

  • index — Path: bitpacker/src/index.ts Export: See source for details.

  • register-schemas — Idempotent integration with @suaveplan/schema-registry for the core @suaveplan/bitpacker package. Exposes a single…

  • types — Path: src/types.ts Export: Schema type guards, BitPackerSchema union, token types

  • types.schema — Zod schemas for the recursive BitPackerSchema union and every variant it can take. These schemas are the single sourc…

  • bit-reader — (no submodules)- index — Path: bitpacker/src/bit-reader/index.ts Export: See source for details.

  • bit-writer — (no submodules) - bit-writer — (no submodules) - index — Path: bitpacker/src/bit-writer/index.ts Export: See source for details.

  • safety — (no submodules) - safety-checks — (no submodules)- invalid — Path: bitpacker/src/core/strategies/invalid.ts Export: See source for details.

  • manager — Path: src/core/strategies/manager.ts Export: PackingStrategyManager (class)

  • types — Path: src/core/strategies/types.ts Export: PackingStrategy (interface), PackingContext (interface)

  • types.schema — Zod schemas for PackingStrategy and PackingContext, the two extension-point types that flow across the `@suaveplan/…

  • bitpacker — Path: src/core/bitpacker.ts Export: BitPacker (class), BitPackerOptions (interface)

  • bitpacker.schema — Zod schema for BitPackerOptions, the configuration bundle accepted by the BitPacker class constructor. It validates…

  • handlers — (no submodules) - custom-type-registry — (no submodules)- pack-iterator — (no submodules) - pack-iterator — (no submodules)- otel — (no submodules) - instruments — (no submodules)- packers — (no submodules) - array — (no submodules) - array-packer — (no submodules) - base — (no submodules) - base-packer — (no submodules) - bigint — (no submodules) - bigint-packer — (no submodules) - bigint-array — (no submodules) - bigint-array-packer — (no submodules) - bit-array — (no submodules) - bit-array-packer — (no submodules) - bit-operations — (no submodules) - bit-operations — (no submodules) - boolean — (no submodules) - boolean-packer — (no submodules) - datetime — (no submodules) - datetime-packer — (no submodules) - enum — (no submodules) - enum-packer — (no submodules) - float — (no submodules) - float-packer — (no submodules) - integer — (no submodules) - integer-packer — (no submodules) - map — (no submodules) - map-packer — (no submodules) - set — (no submodules) - set-packer — (no submodules) - string — (no submodules) - string-packer — (no submodules) - uuid — (no submodules) - uuid-packer — (no submodules) - varint — (no submodules) - varint-packer — (no submodules) - index — (no submodules)- performance — (no submodules) - buffer-pool — Reusable Uint8Array pool for the bitpacker hot path. Instead of allocating a fresh buffer per pack/unpack call (which…

    • lru-cache — Bounded-size LRU (least-recently-used) cache used to memoize expensive bitpacker computations: schema-to-bit-width deri…
    • performance-monitor — Lightweight performance instrumentation for @suaveplan/bitpacker's hot path. PerformanceMonitor collects per-operat…
    • performance — (no submodules)- serialization — (no submodules) - serialization — (no submodules)- base-types — Foundation type companions for the bitpacker — the typed-array unions (IntArray, FloatArray), the integer/float typ…
  • common — Path: bitpacker/src/types/common.ts Export: See source for details.

  • index — Path: src/types/index.ts Exports: Schema type definitions, type guards, utility types

  • key-types — Public type companions for the legacy key-material API. BitPackerKey is the canonical byte-array alias for any signin…

  • packer-types — Public configuration types for the legacy BitPackerConfig surface — the all-in-one options bundle that pre-modular bi…

  • schema-versioning-types — Type companions for the schema-version migration framework — SchemaVersion, MigrationFunction, SchemaMigration, `…

  • validation-types — Type companions for the legacy validation API surfaced from @suaveplan/bitpacker's root export. These types — `BitPac…

  • utils — (no submodules) - float-utils — Float-bit-pattern conversion helpers used by the float packer and any consumer that needs to round-trip a number thro…

    • pack-bits — Path: bitpacker/src/utils/pack-bits.ts Export: See source for details.
    • schema-validators — Per-shape schema validation helpers used internally by @suaveplan/bitpacker's legacy validator surface. Each function…
    • type-guards — Generic type-guard helpers used across @suaveplan/bitpacker for safe narrowing of unknown values into well-typed sh…
    • utils — (no submodules) - zigzag — Path: bitpacker/src/utils/zigzag.ts Export: See source for details.
  • bit-schema — Path: src/bit-schema.ts Export: defineBitSchema (function)

  • error-codes — Path: bitpacker/src/error-codes.ts Export: See source for details.

  • index — Path: bitpacker/src/index.ts Export: See source for details.

  • register-schemas — Idempotent integration with @suaveplan/schema-registry for the core @suaveplan/bitpacker package. Exposes a single…

  • types — Path: src/types.ts Export: Schema type guards, BitPackerSchema union, token types

  • types.schema — Zod schemas for the recursive BitPackerSchema union and every variant it can take. These schemas are the single sourc…

Install

bun add @suaveplan/bitpacker

Quick Start

import { BitPacker, registerDefaultStrategies } from "@suaveplan/bitpacker";
import { registerDefaultStrategies } from "@suaveplan/bitpacker-strategies";

const bp = new BitPacker();
registerDefaultStrategies(bp.strategyManager);

const schema = { x: 255, y: "-16", active: true };
const packed = bp.pack({ x: 100, y: "hello", active: false }, schema);
const unpacked = bp.unpack(packed, schema);

Modules

  • src/bit-writer/bit-writer.ts — Bit-level writer with writeUint, writeInt, writeBool, writeFixed, writeBytes
  • src/bit-reader/bit-reader.ts — Bit-level reader with readUint, readInt, readBool, readFixed, readBytes, peek, seek
  • src/core/bitpacker.ts — Schema-driven packer/unpacker with strategy manager and schema registry
  • src/core/strategies/manager.ts — PackingStrategyManager: chain-of-responsibility strategy resolution
  • src/core/strategies/types.ts — PackingStrategy and PackingContext interfaces
  • src/core/strategies/invalid.ts — Catch-all strategy for unknown schemas
  • src/types.ts — Schema type system: BitPackerSchema, guards, and token types
  • src/bit-schema.ts — Legacy defineBitSchema for fixed-field definitions
  • src/utils/zigzag.ts — Zigzag encoding for signed integers
  • src/utils/pack-bits.ts — Batch bit packing/unpacking utilities
  • src/error-codes.ts — Structured error codes and BitpackerError