SuavePlan/suaveplan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9b28db724f7c99ad304963ee7d8a876190dd4167
suaveplan/packages/foundation/bitpacker/bitpacker-strategies/README.md
admin 9b28db724f Initial Commit
2026-05-27 23:47:53 +01:00

36 KiB
Raw Blame History

@suaveplan/bitpacker-strategies - Built-in packing strategies for @suaveplan/bitpacker

Summary

Built-in packing strategies for @suaveplan/bitpacker. Provides strategies for numbers, strings, booleans, objects, arrays, enums, optional fields, oneOf unions, varints, dates, maps, sets, bit arrays, blobs, bitsets, conditionals, versions, definitions, and custom types.

Documentation tree

  • otel — (no submodules)
  • register-default-strategies — Path: bitpacker-strategies/src/register-default-strategies.ts Export: See source for details.
  • register-default-strategies.schema — Zod schema for the manager argument of registerDefaultStrategies. Validates that an external caller hands the funct…
  • register-schemas — Idempotent integration with @suaveplan/schema-registry for the @suaveplan/bitpacker-strategies package. Exposes a s…
    • register-schemas — Idempotent integration with @suaveplan/schema-registry for the @suaveplan/bitpacker-strategies package. Exposes a s…
  • array — (no submodules)
    • array — (no submodules)
  • array-config — Packs/unpacks arrays described by an explicit configuration object.
    • array-config — Packs/unpacks arrays described by an explicit configuration object.
  • array-notation — Packs/unpacks arrays described by a string notation.
    • array-notation — Packs/unpacks arrays described by a string notation.
  • array-schema — Packs/unpacks fixed-length tuple schemas.
    • array-schema — Packs/unpacks fixed-length tuple schemas.
  • bigint — (no submodules)
  • bigint-array — Packs/unpacks arrays of 64-bit BigInt values.
    • bigint-array — Packs/unpacks arrays of 64-bit BigInt values.
  • bitarray — (no submodules)
  • bitset — (no submodules)
  • blob — (no submodules)
    • blob — (no submodules)
  • boolean — (no submodules)
  • conditional — (no submodules)
  • customType — (no submodules)
  • datetime — (no submodules)
  • defs — (no submodules)
    • defs — (no submodules)
  • enum — (no submodules)
    • enum — (no submodules)
  • map — (no submodules)
    • map — (no submodules)
  • null — (no submodules)
    • null — (no submodules)
  • number — (no submodules)
  • object — (no submodules)
  • oneOf — (no submodules)
    • oneOf — (no submodules)
  • optional — (no submodules)
  • optional-marker — Packs/unpacks optional values using an explicit marker object.
    • optional-marker — Packs/unpacks optional values using an explicit marker object.
  • optional-suffix — Packs/unpacks optional primitive schemas using a ? suffix.
    • optional-suffix — Packs/unpacks optional primitive schemas using a ? suffix.
  • set — (no submodules)
    • set — (no submodules)
  • string — (no submodules)
  • union — (no submodules)
    • union — (no submodules)
  • varint — (no submodules)
  • version — (no submodules)
  • index — Path: bitpacker-strategies/src/index.ts Export: See source for details.
- [instruments](./src/otel/instruments.md) — _(no submodules)_- [array](./src/strategies/array/array.md) — _(no submodules)_- [array](./src/strategies/array/array.md) — _(no submodules)_- [array-config](./src/strategies/array-config/array-config.md) — Packs/unpacks arrays described by an explicit configuration object.
  • array-config — Packs/unpacks arrays described by an explicit configuration object.
  • array-notation — Packs/unpacks arrays described by a string notation.
    • array-notation — Packs/unpacks arrays described by a string notation.
  • array-schema — Packs/unpacks fixed-length tuple schemas.
    • array-schema — Packs/unpacks fixed-length tuple schemas.
  • bigint — (no submodules)- bigint — (no submodules)- bigint-array — Packs/unpacks arrays of 64-bit BigInt values.
    • bigint-array — Packs/unpacks arrays of 64-bit BigInt values.
  • bitarray — (no submodules)- bitarray — (no submodules)- bitset — (no submodules)- bitset — (no submodules)- blob — (no submodules)- blob — (no submodules)- boolean — (no submodules)- boolean — (no submodules)- conditional — (no submodules)- conditional — (no submodules)- customType — (no submodules)- customType — (no submodules)- datetime — (no submodules)- datetime — (no submodules)- defs — (no submodules)- defs — (no submodules)- enum — (no submodules)- enum — (no submodules)- map — (no submodules)- map — (no submodules)- null — (no submodules)- null — (no submodules)- number — (no submodules)- number — (no submodules)- object — (no submodules)- object — (no submodules)- oneOf — (no submodules)- oneOf — (no submodules)- optional — (no submodules)- optional — (no submodules)- optional-marker — Packs/unpacks optional values using an explicit marker object.
    • optional-marker — Packs/unpacks optional values using an explicit marker object.
  • optional-suffix — Packs/unpacks optional primitive schemas using a ? suffix.
    • optional-suffix — Packs/unpacks optional primitive schemas using a ? suffix.
  • set — (no submodules)- set — (no submodules)- string — (no submodules)- string — (no submodules)- union — (no submodules)- union — (no submodules)- varint — (no submodules)- varint — (no submodules)- version — (no submodules)- version — (no submodules)- index — Path: bitpacker-strategies/src/index.ts Export: See source for details.
  • register-default-strategies — Path: bitpacker-strategies/src/register-default-strategies.ts Export: See source for details.
  • register-default-strategies.schema — Zod schema for the manager argument of registerDefaultStrategies. Validates that an external caller hands the funct…
  • register-schemas — Idempotent integration with @suaveplan/schema-registry for the @suaveplan/bitpacker-strategies package. Exposes a s…
  • instruments — (no submodules)- array — (no submodules)- array — (no submodules)- array-config — Packs/unpacks arrays described by an explicit configuration object.
    • array-config — Packs/unpacks arrays described by an explicit configuration object.
  • array-notation — Packs/unpacks arrays described by a string notation.
    • array-notation — Packs/unpacks arrays described by a string notation.
  • array-schema — Packs/unpacks fixed-length tuple schemas.
    • array-schema — Packs/unpacks fixed-length tuple schemas.
  • bigint — (no submodules)- bigint — (no submodules)- bigint-array — Packs/unpacks arrays of 64-bit BigInt values.
    • bigint-array — Packs/unpacks arrays of 64-bit BigInt values.
  • bitarray — (no submodules)- bitarray — (no submodules)- bitset — (no submodules)- bitset — (no submodules)- blob — (no submodules)- blob — (no submodules)- boolean — (no submodules)- boolean — (no submodules)- conditional — (no submodules)- conditional — (no submodules)- customType — (no submodules)- customType — (no submodules)- datetime — (no submodules)- datetime — (no submodules)- defs — (no submodules)- defs — (no submodules)- enum — (no submodules)- enum — (no submodules)- map — (no submodules)- map — (no submodules)- null — (no submodules)- null — (no submodules)- number — (no submodules)- number — (no submodules)- object — (no submodules)- object — (no submodules)- oneOf — (no submodules)- oneOf — (no submodules)- optional — (no submodules)- optional — (no submodules)- optional-marker — Packs/unpacks optional values using an explicit marker object.
    • optional-marker — Packs/unpacks optional values using an explicit marker object.
  • optional-suffix — Packs/unpacks optional primitive schemas using a ? suffix.
    • optional-suffix — Packs/unpacks optional primitive schemas using a ? suffix.
  • set — (no submodules)- set — (no submodules)- string — (no submodules)- string — (no submodules)- union — (no submodules)- union — (no submodules)- varint — (no submodules)- varint — (no submodules)- version — (no submodules)- version — (no submodules)- index — Path: bitpacker-strategies/src/index.ts Export: See source for details.
  • register-default-strategies — Path: bitpacker-strategies/src/register-default-strategies.ts Export: See source for details.
  • register-default-strategies.schema — Zod schema for the manager argument of registerDefaultStrategies. Validates that an external caller hands the funct…
  • register-schemas — Idempotent integration with @suaveplan/schema-registry for the @suaveplan/bitpacker-strategies package. Exposes a s…
  • instruments — (no submodules)- array — (no submodules)- array — (no submodules)- array-config — Packs/unpacks arrays described by an explicit configuration object.
    • array-config — Packs/unpacks arrays described by an explicit configuration object.
  • array-notation — Packs/unpacks arrays described by a string notation.
    • array-notation — Packs/unpacks arrays described by a string notation.
  • array-schema — Packs/unpacks fixed-length tuple schemas.
    • array-schema — Packs/unpacks fixed-length tuple schemas.
  • bigint — (no submodules)- bigint — (no submodules)- bigint-array — Packs/unpacks arrays of 64-bit BigInt values.
    • bigint-array — Packs/unpacks arrays of 64-bit BigInt values.
  • bitarray — (no submodules)- bitarray — (no submodules)- bitset — (no submodules)- bitset — (no submodules)- blob — (no submodules)- blob — (no submodules)- boolean — (no submodules)- boolean — (no submodules)- conditional — (no submodules)- conditional — (no submodules)- customType — (no submodules)- customType — (no submodules)- datetime — (no submodules)- datetime — (no submodules)- defs — (no submodules)- defs — (no submodules)- enum — (no submodules)- enum — (no submodules)- map — (no submodules)- map — (no submodules)- null — (no submodules)- null — (no submodules)- number — (no submodules)- number — (no submodules)- object — (no submodules)- object — (no submodules)- oneOf — (no submodules)- oneOf — (no submodules)- optional — (no submodules)- optional — (no submodules)- optional-marker — Packs/unpacks optional values using an explicit marker object.
    • optional-marker — Packs/unpacks optional values using an explicit marker object.
  • optional-suffix — Packs/unpacks optional primitive schemas using a ? suffix.
    • optional-suffix — Packs/unpacks optional primitive schemas using a ? suffix.
  • set — (no submodules)- set — (no submodules)- string — (no submodules)- string — (no submodules)- union — (no submodules)- union — (no submodules)- varint — (no submodules)- varint — (no submodules)- version — (no submodules)- version — (no submodules)- index — Path: bitpacker-strategies/src/index.ts Export: See source for details.
  • register-default-strategies — Path: bitpacker-strategies/src/register-default-strategies.ts Export: See source for details.
  • register-default-strategies.schema — Zod schema for the manager argument of registerDefaultStrategies. Validates that an external caller hands the funct…
  • register-schemas — Idempotent integration with @suaveplan/schema-registry for the @suaveplan/bitpacker-strategies package. Exposes a s…
  • instruments — (no submodules)- array — (no submodules) - array — (no submodules)- array-config — Packs/unpacks arrays described by an explicit configuration object.
    • array-config — Packs/unpacks arrays described by an explicit configuration object.
  • array-notation — Packs/unpacks arrays described by a string notation.
    • array-notation — Packs/unpacks arrays described by a string notation.
  • array-schema — Packs/unpacks fixed-length tuple schemas.
    • array-schema — Packs/unpacks fixed-length tuple schemas.
  • bigint — (no submodules) - bigint — (no submodules)- bigint-array — Packs/unpacks arrays of 64-bit BigInt values.
    • bigint-array — Packs/unpacks arrays of 64-bit BigInt values.
  • bitarray — (no submodules) - bitarray — (no submodules)- bitset — (no submodules) - bitset — (no submodules)- blob — (no submodules) - blob — (no submodules)- boolean — (no submodules) - boolean — (no submodules)- conditional — (no submodules) - conditional — (no submodules)- customType — (no submodules) - customType — (no submodules)- datetime — (no submodules) - datetime — (no submodules)- defs — (no submodules) - defs — (no submodules)- enum — (no submodules) - enum — (no submodules)- map — (no submodules) - map — (no submodules)- null — (no submodules) - null — (no submodules)- number — (no submodules) - number — (no submodules)- object — (no submodules) - object — (no submodules)- oneOf — (no submodules) - oneOf — (no submodules)- optional — (no submodules) - optional — (no submodules)- optional-marker — Packs/unpacks optional values using an explicit marker object.
    • optional-marker — Packs/unpacks optional values using an explicit marker object.
  • optional-suffix — Packs/unpacks optional primitive schemas using a ? suffix.
    • optional-suffix — Packs/unpacks optional primitive schemas using a ? suffix.
  • set — (no submodules) - set — (no submodules)- string — (no submodules) - string — (no submodules)- union — (no submodules) - union — (no submodules)- varint — (no submodules) - varint — (no submodules)- version — (no submodules) - version — (no submodules)- index — Path: bitpacker-strategies/src/index.ts Export: See source for details.
  • register-default-strategies — Path: bitpacker-strategies/src/register-default-strategies.ts Export: See source for details.
  • register-default-strategies.schema — Zod schema for the manager argument of registerDefaultStrategies. Validates that an external caller hands the funct…
  • register-schemas — Idempotent integration with @suaveplan/schema-registry for the @suaveplan/bitpacker-strategies package. Exposes a s…

Install

bun add @suaveplan/bitpacker-strategies

Usage

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

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

// Pack a number (unsigned 8-bit)
const packed = bp.pack(42, 255);
const unpacked = bp.unpack(packed, 255);

Strategies

Strategy Schema Example
NumberPackingStrategy number 255 (uint8), -127 (signed), 4.2 (fixed-point)
StringPackingStrategy string "8" (fixed 8 chars), "-16" (variable length)
BooleanPackingStrategy boolean true / false
NullPackingStrategy null null
BigIntPackingStrategy bigint "bigint-i64", "bigint-u64"
ObjectPackingStrategy object { x: 255, y: "-16" }
ArrayPackingStrategy array [255]
EnumPackingStrategy enum "enum:a|b|c"
OptionalPackingStrategy optional "8?"
OneOfPackingStrategy oneOf { _bp: "oneOf", schemas: [...] }
VarIntPackingStrategy varint "varint", "varint-signed"
DateTimePackingStrategy datetime "timestamp", "timespan-ms"
MapPackingStrategy map "map<string>"
SetPackingStrategy set "set<number>"
BitArrayPackingStrategy bitarray { _bp: "bitarray", length: 8 }
BlobPackingStrategy blob { _bp: "blob", maxLength: 1024 }
BitsetPackingStrategy bitset "bitset-8"
ConditionalPackingStrategy conditional { _bp: "conditional", condition, then, else }
VersionPackingStrategy version { _bp: "version", versions: [...] }
DefsPackingStrategy defs { _bp: "defs", definitions: {...} }
CustomTypePackingStrategy custom { _bp: { schema: ... } }

Custom Strategy

class MyStrategy implements PackingStrategy {
    canHandle(schema: BitPackerSchema): boolean {
        return schema === "my-type";
    }
    pack(data: unknown, schema: BitPackerSchema, context: PackingContext): void {
        // write to context.writer
    }
    unpack(schema: BitPackerSchema, context: PackingContext): unknown {
        // read from context.reader
    }
}

bp.strategyManager.register(new MyStrategy());
Reference in New Issue View Git Blame Copy Permalink