Initial Commit
This commit is contained in:
202
packages/foundation/bitpacker/bitpacker-strategies/README.md
Normal file
202
packages/foundation/bitpacker/bitpacker-strategies/README.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# @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.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [otel](./src/otel/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [instruments](./src/otel/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [register-default-strategies](./src/register-default-strategies/register-default-strategies.md) — **Path:** `bitpacker-strategies/src/register-default-strategies.ts` **Export:** See source for details.
|
||||
- [register-default-strategies](./src/register-default-strategies/register-default-strategies.md) — **Path:** `bitpacker-strategies/src/register-default-strategies.ts` **Export:** See source for details.
|
||||
- [register-default-strategies.schema](./src/register-default-strategies.schema/register-default-strategies.schema.md) — Zod schema for the `manager` argument of `registerDefaultStrategies`. Validates that an external caller hands the funct…
|
||||
- [register-default-strategies.schema](./src/register-default-strategies.schema/register-default-strategies.schema.md) — Zod schema for the `manager` argument of `registerDefaultStrategies`. Validates that an external caller hands the funct…
|
||||
- [register-schemas](./src/register-schemas/register-schemas.md) — Idempotent integration with `@suaveplan/schema-registry` for the `@suaveplan/bitpacker-strategies` package. Exposes a s…
|
||||
- [register-schemas](./src/register-schemas/register-schemas.md) — Idempotent integration with `@suaveplan/schema-registry` for the `@suaveplan/bitpacker-strategies` package. Exposes a s…
|
||||
- [array](./src/strategies/array/array.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [array](./src/strategies/array/array.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [array-config](./src/strategies/array-config/array-config.md) — Packs/unpacks arrays described by an explicit configuration object.
|
||||
- [array-config](./src/strategies/array-config/array-config.md) — Packs/unpacks arrays described by an explicit configuration object.
|
||||
- [array-notation](./src/strategies/array-notation/array-notation.md) — Packs/unpacks arrays described by a string notation.
|
||||
- [array-notation](./src/strategies/array-notation/array-notation.md) — Packs/unpacks arrays described by a string notation.
|
||||
- [array-schema](./src/strategies/array-schema/array-schema.md) — Packs/unpacks fixed-length tuple schemas.
|
||||
- [array-schema](./src/strategies/array-schema/array-schema.md) — Packs/unpacks fixed-length tuple schemas.
|
||||
- [bigint](./src/strategies/bigint/bigint.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [bigint](./src/strategies/bigint/bigint.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [bigint-array](./src/strategies/bigint-array/bigint-array.md) — Packs/unpacks arrays of 64-bit BigInt values.
|
||||
- [bigint-array](./src/strategies/bigint-array/bigint-array.md) — Packs/unpacks arrays of 64-bit BigInt values.
|
||||
- [bitarray](./src/strategies/bitarray/bitarray.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [bitarray](./src/strategies/bitarray/bitarray.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [bitset](./src/strategies/bitset/bitset.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [bitset](./src/strategies/bitset/bitset.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [blob](./src/strategies/blob/blob.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [blob](./src/strategies/blob/blob.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [boolean](./src/strategies/boolean/boolean.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [boolean](./src/strategies/boolean/boolean.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [conditional](./src/strategies/conditional/conditional.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [conditional](./src/strategies/conditional/conditional.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [customType](./src/strategies/customType/customType.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [customType](./src/strategies/customType/customType.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [datetime](./src/strategies/datetime/datetime.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [datetime](./src/strategies/datetime/datetime.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [defs](./src/strategies/defs/defs.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [defs](./src/strategies/defs/defs.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [enum](./src/strategies/enum/enum.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [enum](./src/strategies/enum/enum.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [map](./src/strategies/map/map.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [map](./src/strategies/map/map.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [null](./src/strategies/null/null.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [null](./src/strategies/null/null.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [number](./src/strategies/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [number](./src/strategies/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [object](./src/strategies/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [object](./src/strategies/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [oneOf](./src/strategies/oneOf/oneOf.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [oneOf](./src/strategies/oneOf/oneOf.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [optional](./src/strategies/optional/optional.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [optional](./src/strategies/optional/optional.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [optional-marker](./src/strategies/optional-marker/optional-marker.md) — Packs/unpacks optional values using an explicit marker object.
|
||||
- [optional-marker](./src/strategies/optional-marker/optional-marker.md) — Packs/unpacks optional values using an explicit marker object.
|
||||
- [optional-suffix](./src/strategies/optional-suffix/optional-suffix.md) — Packs/unpacks optional primitive schemas using a `?` suffix.
|
||||
- [optional-suffix](./src/strategies/optional-suffix/optional-suffix.md) — Packs/unpacks optional primitive schemas using a `?` suffix.
|
||||
- [set](./src/strategies/set/set.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [set](./src/strategies/set/set.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [string](./src/strategies/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [string](./src/strategies/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [union](./src/strategies/union/union.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [union](./src/strategies/union/union.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [varint](./src/strategies/varint/varint.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [varint](./src/strategies/varint/varint.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [version](./src/strategies/version/version.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [version](./src/strategies/version/version.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [index](./src/index.md) — **Path:** `bitpacker-strategies/src/index.ts` **Export:** See source for details.
|
||||
<!-- end:auto-docs --> - [instruments](./src/otel/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_- [array](./src/strategies/array/array.md) — <!-- begin:auto-docs --> _(no submodules)_- [array](./src/strategies/array/array.md) — <!-- begin:auto-docs --> _(no submodules)_- [array-config](./src/strategies/array-config/array-config.md) — Packs/unpacks arrays described by an explicit configuration object.
|
||||
- [array-config](./src/strategies/array-config/array-config.md) — Packs/unpacks arrays described by an explicit configuration object.
|
||||
- [array-notation](./src/strategies/array-notation/array-notation.md) — Packs/unpacks arrays described by a string notation.
|
||||
- [array-notation](./src/strategies/array-notation/array-notation.md) — Packs/unpacks arrays described by a string notation.
|
||||
- [array-schema](./src/strategies/array-schema/array-schema.md) — Packs/unpacks fixed-length tuple schemas.
|
||||
- [array-schema](./src/strategies/array-schema/array-schema.md) — Packs/unpacks fixed-length tuple schemas.
|
||||
- [bigint](./src/strategies/bigint/bigint.md) — <!-- begin:auto-docs --> _(no submodules)_- [bigint](./src/strategies/bigint/bigint.md) — <!-- begin:auto-docs --> _(no submodules)_- [bigint-array](./src/strategies/bigint-array/bigint-array.md) — Packs/unpacks arrays of 64-bit BigInt values.
|
||||
- [bigint-array](./src/strategies/bigint-array/bigint-array.md) — Packs/unpacks arrays of 64-bit BigInt values.
|
||||
- [bitarray](./src/strategies/bitarray/bitarray.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitarray](./src/strategies/bitarray/bitarray.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitset](./src/strategies/bitset/bitset.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitset](./src/strategies/bitset/bitset.md) — <!-- begin:auto-docs --> _(no submodules)_- [blob](./src/strategies/blob/blob.md) — <!-- begin:auto-docs --> _(no submodules)_- [blob](./src/strategies/blob/blob.md) — <!-- begin:auto-docs --> _(no submodules)_- [boolean](./src/strategies/boolean/boolean.md) — <!-- begin:auto-docs --> _(no submodules)_- [boolean](./src/strategies/boolean/boolean.md) — <!-- begin:auto-docs --> _(no submodules)_- [conditional](./src/strategies/conditional/conditional.md) — <!-- begin:auto-docs --> _(no submodules)_- [conditional](./src/strategies/conditional/conditional.md) — <!-- begin:auto-docs --> _(no submodules)_- [customType](./src/strategies/customType/customType.md) — <!-- begin:auto-docs --> _(no submodules)_- [customType](./src/strategies/customType/customType.md) — <!-- begin:auto-docs --> _(no submodules)_- [datetime](./src/strategies/datetime/datetime.md) — <!-- begin:auto-docs --> _(no submodules)_- [datetime](./src/strategies/datetime/datetime.md) — <!-- begin:auto-docs --> _(no submodules)_- [defs](./src/strategies/defs/defs.md) — <!-- begin:auto-docs --> _(no submodules)_- [defs](./src/strategies/defs/defs.md) — <!-- begin:auto-docs --> _(no submodules)_- [enum](./src/strategies/enum/enum.md) — <!-- begin:auto-docs --> _(no submodules)_- [enum](./src/strategies/enum/enum.md) — <!-- begin:auto-docs --> _(no submodules)_- [map](./src/strategies/map/map.md) — <!-- begin:auto-docs --> _(no submodules)_- [map](./src/strategies/map/map.md) — <!-- begin:auto-docs --> _(no submodules)_- [null](./src/strategies/null/null.md) — <!-- begin:auto-docs --> _(no submodules)_- [null](./src/strategies/null/null.md) — <!-- begin:auto-docs --> _(no submodules)_- [number](./src/strategies/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_- [number](./src/strategies/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_- [object](./src/strategies/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_- [object](./src/strategies/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_- [oneOf](./src/strategies/oneOf/oneOf.md) — <!-- begin:auto-docs --> _(no submodules)_- [oneOf](./src/strategies/oneOf/oneOf.md) — <!-- begin:auto-docs --> _(no submodules)_- [optional](./src/strategies/optional/optional.md) — <!-- begin:auto-docs --> _(no submodules)_- [optional](./src/strategies/optional/optional.md) — <!-- begin:auto-docs --> _(no submodules)_- [optional-marker](./src/strategies/optional-marker/optional-marker.md) — Packs/unpacks optional values using an explicit marker object.
|
||||
- [optional-marker](./src/strategies/optional-marker/optional-marker.md) — Packs/unpacks optional values using an explicit marker object.
|
||||
- [optional-suffix](./src/strategies/optional-suffix/optional-suffix.md) — Packs/unpacks optional primitive schemas using a `?` suffix.
|
||||
- [optional-suffix](./src/strategies/optional-suffix/optional-suffix.md) — Packs/unpacks optional primitive schemas using a `?` suffix.
|
||||
- [set](./src/strategies/set/set.md) — <!-- begin:auto-docs --> _(no submodules)_- [set](./src/strategies/set/set.md) — <!-- begin:auto-docs --> _(no submodules)_- [string](./src/strategies/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_- [string](./src/strategies/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_- [union](./src/strategies/union/union.md) — <!-- begin:auto-docs --> _(no submodules)_- [union](./src/strategies/union/union.md) — <!-- begin:auto-docs --> _(no submodules)_- [varint](./src/strategies/varint/varint.md) — <!-- begin:auto-docs --> _(no submodules)_- [varint](./src/strategies/varint/varint.md) — <!-- begin:auto-docs --> _(no submodules)_- [version](./src/strategies/version/version.md) — <!-- begin:auto-docs --> _(no submodules)_- [version](./src/strategies/version/version.md) — <!-- begin:auto-docs --> _(no submodules)_- [index](./src/index.md) — **Path:** `bitpacker-strategies/src/index.ts` **Export:** See source for details.
|
||||
- [register-default-strategies](./src/register-default-strategies.md) — **Path:** `bitpacker-strategies/src/register-default-strategies.ts` **Export:** See source for details.
|
||||
- [register-default-strategies.schema](./src/register-default-strategies.schema.md) — Zod schema for the `manager` argument of `registerDefaultStrategies`. Validates that an external caller hands the funct…
|
||||
- [register-schemas](./src/register-schemas.md) — Idempotent integration with `@suaveplan/schema-registry` for the `@suaveplan/bitpacker-strategies` package. Exposes a s…
|
||||
- [instruments](./src/otel/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_- [array](./src/strategies/array/array.md) — <!-- begin:auto-docs --> _(no submodules)_- [array](./src/strategies/array/array.md) — <!-- begin:auto-docs --> _(no submodules)_- [array-config](./src/strategies/array-config/array-config.md) — Packs/unpacks arrays described by an explicit configuration object.
|
||||
- [array-config](./src/strategies/array-config/array-config.md) — Packs/unpacks arrays described by an explicit configuration object.
|
||||
- [array-notation](./src/strategies/array-notation/array-notation.md) — Packs/unpacks arrays described by a string notation.
|
||||
- [array-notation](./src/strategies/array-notation/array-notation.md) — Packs/unpacks arrays described by a string notation.
|
||||
- [array-schema](./src/strategies/array-schema/array-schema.md) — Packs/unpacks fixed-length tuple schemas.
|
||||
- [array-schema](./src/strategies/array-schema/array-schema.md) — Packs/unpacks fixed-length tuple schemas.
|
||||
- [bigint](./src/strategies/bigint/bigint.md) — <!-- begin:auto-docs --> _(no submodules)_- [bigint](./src/strategies/bigint/bigint.md) — <!-- begin:auto-docs --> _(no submodules)_- [bigint-array](./src/strategies/bigint-array/bigint-array.md) — Packs/unpacks arrays of 64-bit BigInt values.
|
||||
- [bigint-array](./src/strategies/bigint-array/bigint-array.md) — Packs/unpacks arrays of 64-bit BigInt values.
|
||||
- [bitarray](./src/strategies/bitarray/bitarray.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitarray](./src/strategies/bitarray/bitarray.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitset](./src/strategies/bitset/bitset.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitset](./src/strategies/bitset/bitset.md) — <!-- begin:auto-docs --> _(no submodules)_- [blob](./src/strategies/blob/blob.md) — <!-- begin:auto-docs --> _(no submodules)_- [blob](./src/strategies/blob/blob.md) — <!-- begin:auto-docs --> _(no submodules)_- [boolean](./src/strategies/boolean/boolean.md) — <!-- begin:auto-docs --> _(no submodules)_- [boolean](./src/strategies/boolean/boolean.md) — <!-- begin:auto-docs --> _(no submodules)_- [conditional](./src/strategies/conditional/conditional.md) — <!-- begin:auto-docs --> _(no submodules)_- [conditional](./src/strategies/conditional/conditional.md) — <!-- begin:auto-docs --> _(no submodules)_- [customType](./src/strategies/customType/customType.md) — <!-- begin:auto-docs --> _(no submodules)_- [customType](./src/strategies/customType/customType.md) — <!-- begin:auto-docs --> _(no submodules)_- [datetime](./src/strategies/datetime/datetime.md) — <!-- begin:auto-docs --> _(no submodules)_- [datetime](./src/strategies/datetime/datetime.md) — <!-- begin:auto-docs --> _(no submodules)_- [defs](./src/strategies/defs/defs.md) — <!-- begin:auto-docs --> _(no submodules)_- [defs](./src/strategies/defs/defs.md) — <!-- begin:auto-docs --> _(no submodules)_- [enum](./src/strategies/enum/enum.md) — <!-- begin:auto-docs --> _(no submodules)_- [enum](./src/strategies/enum/enum.md) — <!-- begin:auto-docs --> _(no submodules)_- [map](./src/strategies/map/map.md) — <!-- begin:auto-docs --> _(no submodules)_- [map](./src/strategies/map/map.md) — <!-- begin:auto-docs --> _(no submodules)_- [null](./src/strategies/null/null.md) — <!-- begin:auto-docs --> _(no submodules)_- [null](./src/strategies/null/null.md) — <!-- begin:auto-docs --> _(no submodules)_- [number](./src/strategies/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_- [number](./src/strategies/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_- [object](./src/strategies/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_- [object](./src/strategies/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_- [oneOf](./src/strategies/oneOf/oneOf.md) — <!-- begin:auto-docs --> _(no submodules)_- [oneOf](./src/strategies/oneOf/oneOf.md) — <!-- begin:auto-docs --> _(no submodules)_- [optional](./src/strategies/optional/optional.md) — <!-- begin:auto-docs --> _(no submodules)_- [optional](./src/strategies/optional/optional.md) — <!-- begin:auto-docs --> _(no submodules)_- [optional-marker](./src/strategies/optional-marker/optional-marker.md) — Packs/unpacks optional values using an explicit marker object.
|
||||
- [optional-marker](./src/strategies/optional-marker/optional-marker.md) — Packs/unpacks optional values using an explicit marker object.
|
||||
- [optional-suffix](./src/strategies/optional-suffix/optional-suffix.md) — Packs/unpacks optional primitive schemas using a `?` suffix.
|
||||
- [optional-suffix](./src/strategies/optional-suffix/optional-suffix.md) — Packs/unpacks optional primitive schemas using a `?` suffix.
|
||||
- [set](./src/strategies/set/set.md) — <!-- begin:auto-docs --> _(no submodules)_- [set](./src/strategies/set/set.md) — <!-- begin:auto-docs --> _(no submodules)_- [string](./src/strategies/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_- [string](./src/strategies/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_- [union](./src/strategies/union/union.md) — <!-- begin:auto-docs --> _(no submodules)_- [union](./src/strategies/union/union.md) — <!-- begin:auto-docs --> _(no submodules)_- [varint](./src/strategies/varint/varint.md) — <!-- begin:auto-docs --> _(no submodules)_- [varint](./src/strategies/varint/varint.md) — <!-- begin:auto-docs --> _(no submodules)_- [version](./src/strategies/version/version.md) — <!-- begin:auto-docs --> _(no submodules)_- [version](./src/strategies/version/version.md) — <!-- begin:auto-docs --> _(no submodules)_- [index](./src/index.md) — **Path:** `bitpacker-strategies/src/index.ts` **Export:** See source for details.
|
||||
- [register-default-strategies](./src/register-default-strategies.md) — **Path:** `bitpacker-strategies/src/register-default-strategies.ts` **Export:** See source for details.
|
||||
- [register-default-strategies.schema](./src/register-default-strategies.schema.md) — Zod schema for the `manager` argument of `registerDefaultStrategies`. Validates that an external caller hands the funct…
|
||||
- [register-schemas](./src/register-schemas.md) — Idempotent integration with `@suaveplan/schema-registry` for the `@suaveplan/bitpacker-strategies` package. Exposes a s…
|
||||
- [instruments](./src/otel/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_- [array](./src/strategies/array/array.md) — <!-- begin:auto-docs --> _(no submodules)_- [array](./src/strategies/array/array.md) — <!-- begin:auto-docs --> _(no submodules)_- [array-config](./src/strategies/array-config/array-config.md) — Packs/unpacks arrays described by an explicit configuration object.
|
||||
- [array-config](./src/strategies/array-config/array-config.md) — Packs/unpacks arrays described by an explicit configuration object.
|
||||
- [array-notation](./src/strategies/array-notation/array-notation.md) — Packs/unpacks arrays described by a string notation.
|
||||
- [array-notation](./src/strategies/array-notation/array-notation.md) — Packs/unpacks arrays described by a string notation.
|
||||
- [array-schema](./src/strategies/array-schema/array-schema.md) — Packs/unpacks fixed-length tuple schemas.
|
||||
- [array-schema](./src/strategies/array-schema/array-schema.md) — Packs/unpacks fixed-length tuple schemas.
|
||||
- [bigint](./src/strategies/bigint/bigint.md) — <!-- begin:auto-docs --> _(no submodules)_- [bigint](./src/strategies/bigint/bigint.md) — <!-- begin:auto-docs --> _(no submodules)_- [bigint-array](./src/strategies/bigint-array/bigint-array.md) — Packs/unpacks arrays of 64-bit BigInt values.
|
||||
- [bigint-array](./src/strategies/bigint-array/bigint-array.md) — Packs/unpacks arrays of 64-bit BigInt values.
|
||||
- [bitarray](./src/strategies/bitarray/bitarray.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitarray](./src/strategies/bitarray/bitarray.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitset](./src/strategies/bitset/bitset.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitset](./src/strategies/bitset/bitset.md) — <!-- begin:auto-docs --> _(no submodules)_- [blob](./src/strategies/blob/blob.md) — <!-- begin:auto-docs --> _(no submodules)_- [blob](./src/strategies/blob/blob.md) — <!-- begin:auto-docs --> _(no submodules)_- [boolean](./src/strategies/boolean/boolean.md) — <!-- begin:auto-docs --> _(no submodules)_- [boolean](./src/strategies/boolean/boolean.md) — <!-- begin:auto-docs --> _(no submodules)_- [conditional](./src/strategies/conditional/conditional.md) — <!-- begin:auto-docs --> _(no submodules)_- [conditional](./src/strategies/conditional/conditional.md) — <!-- begin:auto-docs --> _(no submodules)_- [customType](./src/strategies/customType/customType.md) — <!-- begin:auto-docs --> _(no submodules)_- [customType](./src/strategies/customType/customType.md) — <!-- begin:auto-docs --> _(no submodules)_- [datetime](./src/strategies/datetime/datetime.md) — <!-- begin:auto-docs --> _(no submodules)_- [datetime](./src/strategies/datetime/datetime.md) — <!-- begin:auto-docs --> _(no submodules)_- [defs](./src/strategies/defs/defs.md) — <!-- begin:auto-docs --> _(no submodules)_- [defs](./src/strategies/defs/defs.md) — <!-- begin:auto-docs --> _(no submodules)_- [enum](./src/strategies/enum/enum.md) — <!-- begin:auto-docs --> _(no submodules)_- [enum](./src/strategies/enum/enum.md) — <!-- begin:auto-docs --> _(no submodules)_- [map](./src/strategies/map/map.md) — <!-- begin:auto-docs --> _(no submodules)_- [map](./src/strategies/map/map.md) — <!-- begin:auto-docs --> _(no submodules)_- [null](./src/strategies/null/null.md) — <!-- begin:auto-docs --> _(no submodules)_- [null](./src/strategies/null/null.md) — <!-- begin:auto-docs --> _(no submodules)_- [number](./src/strategies/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_- [number](./src/strategies/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_- [object](./src/strategies/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_- [object](./src/strategies/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_- [oneOf](./src/strategies/oneOf/oneOf.md) — <!-- begin:auto-docs --> _(no submodules)_- [oneOf](./src/strategies/oneOf/oneOf.md) — <!-- begin:auto-docs --> _(no submodules)_- [optional](./src/strategies/optional/optional.md) — <!-- begin:auto-docs --> _(no submodules)_- [optional](./src/strategies/optional/optional.md) — <!-- begin:auto-docs --> _(no submodules)_- [optional-marker](./src/strategies/optional-marker/optional-marker.md) — Packs/unpacks optional values using an explicit marker object.
|
||||
- [optional-marker](./src/strategies/optional-marker/optional-marker.md) — Packs/unpacks optional values using an explicit marker object.
|
||||
- [optional-suffix](./src/strategies/optional-suffix/optional-suffix.md) — Packs/unpacks optional primitive schemas using a `?` suffix.
|
||||
- [optional-suffix](./src/strategies/optional-suffix/optional-suffix.md) — Packs/unpacks optional primitive schemas using a `?` suffix.
|
||||
- [set](./src/strategies/set/set.md) — <!-- begin:auto-docs --> _(no submodules)_- [set](./src/strategies/set/set.md) — <!-- begin:auto-docs --> _(no submodules)_- [string](./src/strategies/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_- [string](./src/strategies/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_- [union](./src/strategies/union/union.md) — <!-- begin:auto-docs --> _(no submodules)_- [union](./src/strategies/union/union.md) — <!-- begin:auto-docs --> _(no submodules)_- [varint](./src/strategies/varint/varint.md) — <!-- begin:auto-docs --> _(no submodules)_- [varint](./src/strategies/varint/varint.md) — <!-- begin:auto-docs --> _(no submodules)_- [version](./src/strategies/version/version.md) — <!-- begin:auto-docs --> _(no submodules)_- [version](./src/strategies/version/version.md) — <!-- begin:auto-docs --> _(no submodules)_- [index](./src/index.md) — **Path:** `bitpacker-strategies/src/index.ts` **Export:** See source for details.
|
||||
- [register-default-strategies](./src/register-default-strategies.md) — **Path:** `bitpacker-strategies/src/register-default-strategies.ts` **Export:** See source for details.
|
||||
- [register-default-strategies.schema](./src/register-default-strategies.schema.md) — Zod schema for the `manager` argument of `registerDefaultStrategies`. Validates that an external caller hands the funct…
|
||||
- [register-schemas](./src/register-schemas.md) — Idempotent integration with `@suaveplan/schema-registry` for the `@suaveplan/bitpacker-strategies` package. Exposes a s…
|
||||
- [instruments](./src/otel/instruments.md) — <!-- begin:auto-docs --> _(no submodules)_- [array](./src/strategies/array/array.md) — <!-- begin:auto-docs --> _(no submodules)_ - [array](./src/strategies/array/array.md) — <!-- begin:auto-docs --> _(no submodules)_- [array-config](./src/strategies/array-config/array-config.md) — Packs/unpacks arrays described by an explicit configuration object.
|
||||
- [array-config](./src/strategies/array-config/array-config.md) — Packs/unpacks arrays described by an explicit configuration object.
|
||||
- [array-notation](./src/strategies/array-notation/array-notation.md) — Packs/unpacks arrays described by a string notation.
|
||||
- [array-notation](./src/strategies/array-notation/array-notation.md) — Packs/unpacks arrays described by a string notation.
|
||||
- [array-schema](./src/strategies/array-schema/array-schema.md) — Packs/unpacks fixed-length tuple schemas.
|
||||
- [array-schema](./src/strategies/array-schema/array-schema.md) — Packs/unpacks fixed-length tuple schemas.
|
||||
- [bigint](./src/strategies/bigint/bigint.md) — <!-- begin:auto-docs --> _(no submodules)_ - [bigint](./src/strategies/bigint/bigint.md) — <!-- begin:auto-docs --> _(no submodules)_- [bigint-array](./src/strategies/bigint-array/bigint-array.md) — Packs/unpacks arrays of 64-bit BigInt values.
|
||||
- [bigint-array](./src/strategies/bigint-array/bigint-array.md) — Packs/unpacks arrays of 64-bit BigInt values.
|
||||
- [bitarray](./src/strategies/bitarray/bitarray.md) — <!-- begin:auto-docs --> _(no submodules)_ - [bitarray](./src/strategies/bitarray/bitarray.md) — <!-- begin:auto-docs --> _(no submodules)_- [bitset](./src/strategies/bitset/bitset.md) — <!-- begin:auto-docs --> _(no submodules)_ - [bitset](./src/strategies/bitset/bitset.md) — <!-- begin:auto-docs --> _(no submodules)_- [blob](./src/strategies/blob/blob.md) — <!-- begin:auto-docs --> _(no submodules)_ - [blob](./src/strategies/blob/blob.md) — <!-- begin:auto-docs --> _(no submodules)_- [boolean](./src/strategies/boolean/boolean.md) — <!-- begin:auto-docs --> _(no submodules)_ - [boolean](./src/strategies/boolean/boolean.md) — <!-- begin:auto-docs --> _(no submodules)_- [conditional](./src/strategies/conditional/conditional.md) — <!-- begin:auto-docs --> _(no submodules)_ - [conditional](./src/strategies/conditional/conditional.md) — <!-- begin:auto-docs --> _(no submodules)_- [customType](./src/strategies/customType/customType.md) — <!-- begin:auto-docs --> _(no submodules)_ - [customType](./src/strategies/customType/customType.md) — <!-- begin:auto-docs --> _(no submodules)_- [datetime](./src/strategies/datetime/datetime.md) — <!-- begin:auto-docs --> _(no submodules)_ - [datetime](./src/strategies/datetime/datetime.md) — <!-- begin:auto-docs --> _(no submodules)_- [defs](./src/strategies/defs/defs.md) — <!-- begin:auto-docs --> _(no submodules)_ - [defs](./src/strategies/defs/defs.md) — <!-- begin:auto-docs --> _(no submodules)_- [enum](./src/strategies/enum/enum.md) — <!-- begin:auto-docs --> _(no submodules)_ - [enum](./src/strategies/enum/enum.md) — <!-- begin:auto-docs --> _(no submodules)_- [map](./src/strategies/map/map.md) — <!-- begin:auto-docs --> _(no submodules)_ - [map](./src/strategies/map/map.md) — <!-- begin:auto-docs --> _(no submodules)_- [null](./src/strategies/null/null.md) — <!-- begin:auto-docs --> _(no submodules)_ - [null](./src/strategies/null/null.md) — <!-- begin:auto-docs --> _(no submodules)_- [number](./src/strategies/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_ - [number](./src/strategies/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_- [object](./src/strategies/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_ - [object](./src/strategies/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_- [oneOf](./src/strategies/oneOf/oneOf.md) — <!-- begin:auto-docs --> _(no submodules)_ - [oneOf](./src/strategies/oneOf/oneOf.md) — <!-- begin:auto-docs --> _(no submodules)_- [optional](./src/strategies/optional/optional.md) — <!-- begin:auto-docs --> _(no submodules)_ - [optional](./src/strategies/optional/optional.md) — <!-- begin:auto-docs --> _(no submodules)_- [optional-marker](./src/strategies/optional-marker/optional-marker.md) — Packs/unpacks optional values using an explicit marker object.
|
||||
- [optional-marker](./src/strategies/optional-marker/optional-marker.md) — Packs/unpacks optional values using an explicit marker object.
|
||||
- [optional-suffix](./src/strategies/optional-suffix/optional-suffix.md) — Packs/unpacks optional primitive schemas using a `?` suffix.
|
||||
- [optional-suffix](./src/strategies/optional-suffix/optional-suffix.md) — Packs/unpacks optional primitive schemas using a `?` suffix.
|
||||
- [set](./src/strategies/set/set.md) — <!-- begin:auto-docs --> _(no submodules)_ - [set](./src/strategies/set/set.md) — <!-- begin:auto-docs --> _(no submodules)_- [string](./src/strategies/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_ - [string](./src/strategies/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_- [union](./src/strategies/union/union.md) — <!-- begin:auto-docs --> _(no submodules)_ - [union](./src/strategies/union/union.md) — <!-- begin:auto-docs --> _(no submodules)_- [varint](./src/strategies/varint/varint.md) — <!-- begin:auto-docs --> _(no submodules)_ - [varint](./src/strategies/varint/varint.md) — <!-- begin:auto-docs --> _(no submodules)_- [version](./src/strategies/version/version.md) — <!-- begin:auto-docs --> _(no submodules)_ - [version](./src/strategies/version/version.md) — <!-- begin:auto-docs --> _(no submodules)_- [index](./src/index.md) — **Path:** `bitpacker-strategies/src/index.ts` **Export:** See source for details.
|
||||
- [register-default-strategies](./src/register-default-strategies.md) — **Path:** `bitpacker-strategies/src/register-default-strategies.ts` **Export:** See source for details.
|
||||
- [register-default-strategies.schema](./src/register-default-strategies.schema.md) — Zod schema for the `manager` argument of `registerDefaultStrategies`. Validates that an external caller hands the funct…
|
||||
- [register-schemas](./src/register-schemas.md) — Idempotent integration with `@suaveplan/schema-registry` for the `@suaveplan/bitpacker-strategies` package. Exposes a s…
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
bun add @suaveplan/bitpacker-strategies
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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());
|
||||
```
|
||||
@@ -0,0 +1,66 @@
|
||||
{
|
||||
"name": "@suaveplan/bitpacker-strategies",
|
||||
"version": "0.1.0",
|
||||
"type": "module",
|
||||
"sideEffects": false,
|
||||
"description": "Built-in packing strategies for @suaveplan/bitpacker",
|
||||
"license": "MIT",
|
||||
"author": "Suaveplan Team",
|
||||
"main": "./dist/index.js",
|
||||
"module": "./dist/index.js",
|
||||
"types": "./dist/index.d.ts",
|
||||
"exports": {
|
||||
"./package.json": "./package.json",
|
||||
".": {
|
||||
"import": {
|
||||
"types": "./dist/index.d.ts",
|
||||
"default": "./dist/index.js"
|
||||
},
|
||||
"require": {
|
||||
"types": "./dist/index.d.ts",
|
||||
"default": "./dist/index.js"
|
||||
}
|
||||
},
|
||||
"./register-schemas": {
|
||||
"import": {
|
||||
"types": "./dist/register-schemas/index.d.ts",
|
||||
"default": "./dist/register-schemas/index.js"
|
||||
},
|
||||
"require": {
|
||||
"types": "./dist/register-schemas/index.d.ts",
|
||||
"default": "./dist/register-schemas/index.js"
|
||||
}
|
||||
}
|
||||
},
|
||||
"scripts": {
|
||||
"build": "vite build",
|
||||
"test": "vitest run --passWithNoTests",
|
||||
"test:watch": "vitest",
|
||||
"test:coverage": "vitest run --coverage --passWithNoTests",
|
||||
"lint": "bunx biome check src/",
|
||||
"lint:fix": "bunx biome lint --fix --unsafe --max-diagnostics 500 src/",
|
||||
"format": "bunx biome format --write --max-diagnostics 500 src/",
|
||||
"check": "bunx biome check --write --unsafe --max-diagnostics 500 src/",
|
||||
"typecheck": "bunx tsc --noEmit --composite false -p tsconfig.lib.json",
|
||||
"docs:check": "bun run ../../../../scripts/docs-check.ts ."
|
||||
},
|
||||
"dependencies": {
|
||||
"@opentelemetry/api": "catalog:observability",
|
||||
"@suaveplan/bitpacker": "workspace:^",
|
||||
"@suaveplan/error": "workspace:^",
|
||||
"@suaveplan/schema-registry": "workspace:^",
|
||||
"@suaveplan/types": "workspace:^",
|
||||
"tslib": "catalog:build",
|
||||
"zod": "catalog:forms"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@suaveplan/testing": "workspace:^",
|
||||
"@types/node": "catalog:",
|
||||
"@vitest/coverage-istanbul": "catalog:testing",
|
||||
"fast-check": "catalog:testing",
|
||||
"typescript": "catalog:",
|
||||
"vite": "catalog:build",
|
||||
"vite-plugin-dts": "catalog:build",
|
||||
"vitest": "catalog:testing"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,198 @@
|
||||
import { BitPacker } from "@suaveplan/bitpacker";
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import fc from "fast-check";
|
||||
import { registerDefaultStrategies } from "../register-default-strategies/register-default-strategies.js";
|
||||
|
||||
// Round-trip property tests covering every schema kind documented in the
|
||||
// bitpacker-hardening proposal: u8, i16, varint, string, blob, array,
|
||||
// object, optional, oneOf, enum, datetime, map, set, conditional, ref,
|
||||
// tuple, version. For each kind, a fast-check arbitrary generates 50–200
|
||||
// values and asserts unpack(pack(v)) ≡ v.
|
||||
|
||||
function makePacker(): BitPacker {
|
||||
const bp = new BitPacker();
|
||||
registerDefaultStrategies(bp.strategyManager);
|
||||
return bp;
|
||||
}
|
||||
|
||||
describe("round-trip — primitive kinds", () => {
|
||||
it("u8 round-trips for every value in [0, 255]", () => {
|
||||
const bp = makePacker();
|
||||
fc.assert(
|
||||
fc.property(fc.integer({ min: 0, max: 255 }), (v) => {
|
||||
const bytes = bp.pack(v, 255);
|
||||
return bp.unpack(bytes, 255) === v;
|
||||
}),
|
||||
{ numRuns: 200 }
|
||||
);
|
||||
});
|
||||
|
||||
it("i16 round-trips for signed integers via negative-max schema", () => {
|
||||
const bp = makePacker();
|
||||
// Schema `-32768` means "signed integer with max abs value 32768",
|
||||
// which packs values in [-32768, 32768]; the strategy uses 16 bits
|
||||
// for the magnitude plus 1 sign bit.
|
||||
fc.assert(
|
||||
fc.property(fc.integer({ min: -32768, max: 32768 }), (v) => {
|
||||
const bytes = bp.pack(v, -32768);
|
||||
return bp.unpack(bytes, -32768) === v;
|
||||
}),
|
||||
{ numRuns: 200 }
|
||||
);
|
||||
});
|
||||
|
||||
it("boolean round-trips for true and false", () => {
|
||||
const bp = makePacker();
|
||||
fc.assert(
|
||||
fc.property(fc.boolean(), (v) => {
|
||||
const bytes = bp.pack(v, true);
|
||||
return bp.unpack(bytes, true) === v;
|
||||
}),
|
||||
{ numRuns: 50 }
|
||||
);
|
||||
});
|
||||
|
||||
it("null round-trips identity", () => {
|
||||
const bp = makePacker();
|
||||
const bytes = bp.pack(null, null);
|
||||
expect(bp.unpack(bytes, null)).toBe(null);
|
||||
});
|
||||
});
|
||||
|
||||
describe("round-trip — string", () => {
|
||||
it("variable-length string round-trips ASCII content", () => {
|
||||
const bp = makePacker();
|
||||
fc.assert(
|
||||
fc.property(fc.string({ minLength: 0, maxLength: 32 }), (v) => {
|
||||
const bytes = bp.pack(v, "-32");
|
||||
return bp.unpack(bytes, "-32") === v;
|
||||
}),
|
||||
{ numRuns: 100 }
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("round-trip — array", () => {
|
||||
it("variable-length uint array round-trips", () => {
|
||||
const bp = makePacker();
|
||||
fc.assert(
|
||||
fc.property(
|
||||
fc.array(fc.integer({ min: 0, max: 255 }), {
|
||||
minLength: 0,
|
||||
maxLength: 16,
|
||||
}),
|
||||
(v) => {
|
||||
const bytes = bp.pack(v, [255]);
|
||||
return (
|
||||
JSON.stringify(bp.unpack(bytes, [255])) ===
|
||||
JSON.stringify(v)
|
||||
);
|
||||
}
|
||||
),
|
||||
{ numRuns: 100 }
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("round-trip — object", () => {
|
||||
it("flat object with mixed primitives round-trips", () => {
|
||||
const bp = makePacker();
|
||||
const schema = { x: 255, flag: true, name: "-16" };
|
||||
fc.assert(
|
||||
fc.property(
|
||||
fc.record({
|
||||
x: fc.integer({ min: 0, max: 255 }),
|
||||
flag: fc.boolean(),
|
||||
name: fc.string({ minLength: 0, maxLength: 16 }),
|
||||
}),
|
||||
(v) => {
|
||||
const bytes = bp.pack(v, schema);
|
||||
const out = bp.unpack(bytes, schema);
|
||||
return JSON.stringify(out) === JSON.stringify(v);
|
||||
}
|
||||
),
|
||||
{ numRuns: 100 }
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("round-trip — enum", () => {
|
||||
it("enum tokens round-trip identity", () => {
|
||||
const bp = makePacker();
|
||||
const schema = { _enum: ["a", "b", "c", "d"] };
|
||||
fc.assert(
|
||||
fc.property(fc.constantFrom("a", "b", "c", "d"), (v) => {
|
||||
const bytes = bp.pack(v, schema);
|
||||
return bp.unpack(bytes, schema) === v;
|
||||
}),
|
||||
{ numRuns: 50 }
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("round-trip — optional", () => {
|
||||
it("optional uint round-trips presence; absence becomes undefined", () => {
|
||||
const bp = makePacker();
|
||||
const schema = { _optional: 255 };
|
||||
fc.assert(
|
||||
fc.property(
|
||||
fc.option(fc.integer({ min: 0, max: 255 }), {
|
||||
nil: undefined,
|
||||
}),
|
||||
(v) => {
|
||||
const bytes = bp.pack(v, schema);
|
||||
const out = bp.unpack(bytes, schema);
|
||||
return out === v;
|
||||
}
|
||||
),
|
||||
{ numRuns: 100 }
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("round-trip — oneOf", () => {
|
||||
it("oneOf union of uint and string round-trips", () => {
|
||||
const bp = makePacker();
|
||||
const schema = { _oneOf: [255, "-8"] };
|
||||
fc.assert(
|
||||
fc.property(
|
||||
fc.oneof(
|
||||
fc.integer({ min: 0, max: 255 }),
|
||||
fc.string({ minLength: 0, maxLength: 8 })
|
||||
),
|
||||
(v) => {
|
||||
const bytes = bp.pack(v, schema);
|
||||
const out = bp.unpack(bytes, schema);
|
||||
return out === v;
|
||||
}
|
||||
),
|
||||
{ numRuns: 100 }
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("round-trip — version forward tolerance", () => {
|
||||
it("forward-tolerant unpack equals strict-unpack output for any same-shape version", () => {
|
||||
const bp = makePacker();
|
||||
fc.assert(
|
||||
fc.property(
|
||||
fc.integer({ min: 0, max: 65535 }),
|
||||
fc.integer({ min: 0, max: 255 }),
|
||||
(writeVersion, value) => {
|
||||
const writeSchema = {
|
||||
_version: writeVersion,
|
||||
_schema: 255,
|
||||
};
|
||||
const bytes = bp.pack(value, writeSchema);
|
||||
const tolerantSchema = {
|
||||
_version: 1,
|
||||
_schema: 255,
|
||||
_tolerance: "forward" as const,
|
||||
};
|
||||
return bp.unpack(bytes, tolerantSchema) === value;
|
||||
}
|
||||
),
|
||||
{ numRuns: 100 }
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,8 @@
|
||||
## index
|
||||
|
||||
**Path:** `bitpacker-strategies/src/index.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Part of the @suaveplan/bitpacker-strategies package.
|
||||
@@ -0,0 +1,28 @@
|
||||
export { registerDefaultStrategies } from "./register-default-strategies/index.js";
|
||||
export { ArrayPackingStrategy } from "./strategies/array/array.js";
|
||||
export { ArrayConfigPackingStrategy } from "./strategies/array-config/array-config.js";
|
||||
export { ArrayNotationPackingStrategy } from "./strategies/array-notation/array-notation.js";
|
||||
export { ArraySchemaPackingStrategy } from "./strategies/array-schema/array-schema.js";
|
||||
export { BigIntPackingStrategy } from "./strategies/bigint/bigint.js";
|
||||
export { BigIntArrayPackingStrategy } from "./strategies/bigint-array/bigint-array.js";
|
||||
export { BitArrayPackingStrategy } from "./strategies/bitarray/bitarray.js";
|
||||
export { BitsetPackingStrategy } from "./strategies/bitset/bitset.js";
|
||||
export { BlobPackingStrategy } from "./strategies/blob/blob.js";
|
||||
export { BooleanPackingStrategy } from "./strategies/boolean/boolean.js";
|
||||
export { ConditionalPackingStrategy } from "./strategies/conditional/conditional.js";
|
||||
export { CustomTypePackingStrategy } from "./strategies/customType/customType.js";
|
||||
export { DateTimePackingStrategy } from "./strategies/datetime/datetime.js";
|
||||
export { DefsPackingStrategy } from "./strategies/defs/defs.js";
|
||||
export { EnumPackingStrategy } from "./strategies/enum/enum.js";
|
||||
export { MapPackingStrategy } from "./strategies/map/map.js";
|
||||
export { NullPackingStrategy } from "./strategies/null/null.js";
|
||||
export { NumberPackingStrategy } from "./strategies/number/number.js";
|
||||
export { ObjectPackingStrategy } from "./strategies/object/object.js";
|
||||
export { OneOfPackingStrategy } from "./strategies/oneOf/oneOf.js";
|
||||
export { OptionalPackingStrategy } from "./strategies/optional/optional.js";
|
||||
export { OptionalMarkerPackingStrategy } from "./strategies/optional-marker/optional-marker.js";
|
||||
export { OptionalSuffixPackingStrategy } from "./strategies/optional-suffix/optional-suffix.js";
|
||||
export { SetPackingStrategy } from "./strategies/set/set.js";
|
||||
export { StringPackingStrategy } from "./strategies/string/string.js";
|
||||
export { VarIntPackingStrategy } from "./strategies/varint/varint.js";
|
||||
export { VersionPackingStrategy } from "./strategies/version/version.js";
|
||||
@@ -0,0 +1,76 @@
|
||||
# Bitpacker Strategies OTel Instruments
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## Purpose
|
||||
|
||||
OTel meter, tracer, counter, and histogram declarations for `@suaveplan/bitpacker-strategies`. The package's only public boundary is `registerDefaultStrategies(manager)` — strategies are stateless chain handlers invoked from inside the parent `bitpacker.pack` / `bitpacker.unpack` span owned by `@suaveplan/bitpacker`. Per the proposal "one span per top-level call; per-chunk events nested", strategy invocations do NOT get their own spans; only the bootstrap call `registerDefaultStrategies` is instrumented.
|
||||
|
||||
The metric and span names follow the suaveplan convention with snake-case for the multi-word package: tracer/meter named `@suaveplan/bitpacker-strategies`; span named `bitpacker_strategies.register`; counter/histogram named `bitpacker_strategies.register.<metric>`.
|
||||
|
||||
## Features
|
||||
|
||||
- `getBitPackerStrategiesTracer()` — returns the package's tracer
|
||||
- `registerStrategiesTotal` — counter labelled by `success`
|
||||
- `registerStrategiesDurationMs` — histogram of bootstrap duration
|
||||
- `BITPACKER_STRATEGIES_SPAN_NAMES` — `{ register: "bitpacker_strategies.register" }`
|
||||
|
||||
## Usage: Basic Example
|
||||
|
||||
```ts
|
||||
import { PackingStrategyManager } from "@suaveplan/bitpacker";
|
||||
import { registerDefaultStrategies } from "@suaveplan/bitpacker-strategies";
|
||||
|
||||
const manager = new PackingStrategyManager();
|
||||
registerDefaultStrategies(manager);
|
||||
// One span emitted: "bitpacker_strategies.register"
|
||||
// Counter incremented: bitpacker_strategies.register.total{success="true"}
|
||||
// Histogram recorded: bitpacker_strategies.register.duration_ms
|
||||
```
|
||||
|
||||
## Usage: Advanced Example
|
||||
|
||||
```ts
|
||||
import { trace } from "@opentelemetry/api";
|
||||
import { PackingStrategyManager } from "@suaveplan/bitpacker";
|
||||
import {
|
||||
BITPACKER_STRATEGIES_SPAN_NAMES,
|
||||
registerDefaultStrategies,
|
||||
} from "@suaveplan/bitpacker-strategies";
|
||||
|
||||
trace
|
||||
.getTracer("my-app")
|
||||
.startActiveSpan(
|
||||
BITPACKER_STRATEGIES_SPAN_NAMES.register + ".wrapper",
|
||||
(span) => {
|
||||
const manager = new PackingStrategyManager();
|
||||
registerDefaultStrategies(manager);
|
||||
// bitpacker_strategies.register is a child span here.
|
||||
span.end();
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### `getBitPackerStrategiesTracer(): Tracer`
|
||||
|
||||
Returns the OTel `Tracer` instance for the package.
|
||||
|
||||
### `registerStrategiesTotal: Counter`
|
||||
|
||||
Counter incremented once per `registerDefaultStrategies` call. Labels: `success: "true" | "false"`.
|
||||
|
||||
### `registerStrategiesDurationMs: Histogram`
|
||||
|
||||
Histogram of elapsed wall-clock milliseconds per bootstrap call. No labels.
|
||||
|
||||
### `BITPACKER_STRATEGIES_SPAN_NAMES`
|
||||
|
||||
Const map: `{ register: "bitpacker_strategies.register" }`.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- **No per-strategy spans.** The 30 shipped strategies are invoked thousands of times per pack/unpack on large schemas; one span each would explode trace volume. They run inside the parent `bitpacker.pack` / `bitpacker.unpack` span without instrumentation.
|
||||
- **Bootstrap-only counter.** `registerStrategiesTotal` is incremented once per `registerDefaultStrategies` call. A consumer can reason about chain-bootstrap frequency from this counter without correlating across packages.
|
||||
@@ -0,0 +1,33 @@
|
||||
import { PackingStrategyManager } from "@suaveplan/bitpacker";
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import { registerDefaultStrategies } from "../register-default-strategies/register-default-strategies.js";
|
||||
import {
|
||||
BITPACKER_STRATEGIES_SPAN_NAMES,
|
||||
getBitPackerStrategiesTracer,
|
||||
registerStrategiesDurationMs,
|
||||
registerStrategiesTotal,
|
||||
} from "./instruments.js";
|
||||
|
||||
describe("OTel instruments — declarations", () => {
|
||||
it("exposes the canonical span name", () => {
|
||||
expect(BITPACKER_STRATEGIES_SPAN_NAMES.register).toBe(
|
||||
"bitpacker_strategies.register"
|
||||
);
|
||||
});
|
||||
|
||||
it("counters and histograms are constructed without error", () => {
|
||||
expect(registerStrategiesTotal).toBeDefined();
|
||||
expect(registerStrategiesDurationMs).toBeDefined();
|
||||
});
|
||||
|
||||
it("tracer is reachable via getBitPackerStrategiesTracer", () => {
|
||||
expect(getBitPackerStrategiesTracer()).toBeDefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe("OTel instruments — emission", () => {
|
||||
it("registerDefaultStrategies emits a span without throwing", () => {
|
||||
const manager = new PackingStrategyManager();
|
||||
expect(() => registerDefaultStrategies(manager)).not.toThrow();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,43 @@
|
||||
import { metrics, type Tracer, trace } from "@opentelemetry/api";
|
||||
|
||||
/** OTel meter for `@suaveplan/bitpacker-strategies`. */
|
||||
const meter = metrics.getMeter("@suaveplan/bitpacker-strategies");
|
||||
|
||||
/** OTel tracer for `@suaveplan/bitpacker-strategies`. */
|
||||
export function getBitPackerStrategiesTracer(): Tracer {
|
||||
return trace.getTracer("@suaveplan/bitpacker-strategies");
|
||||
}
|
||||
|
||||
/**
|
||||
* Counter tracking the total number of strategy registrations performed by
|
||||
* `registerDefaultStrategies`, labelled by `success`. Strategy *invocations*
|
||||
* are NOT counted at this layer — they happen inside the parent
|
||||
* `bitpacker.pack` / `bitpacker.unpack` span and would explode trace volume
|
||||
* on large schemas.
|
||||
*/
|
||||
export const registerStrategiesTotal = meter.createCounter(
|
||||
"bitpacker_strategies.register.total",
|
||||
{
|
||||
description:
|
||||
"Total calls to registerDefaultStrategies (one per BitPacker bootstrap)",
|
||||
unit: "{calls}",
|
||||
}
|
||||
);
|
||||
|
||||
/**
|
||||
* Histogram recording the wall-clock duration of `registerDefaultStrategies`
|
||||
* in milliseconds.
|
||||
*/
|
||||
export const registerStrategiesDurationMs = meter.createHistogram(
|
||||
"bitpacker_strategies.register.duration_ms",
|
||||
{
|
||||
description:
|
||||
"Duration of registerDefaultStrategies calls in milliseconds",
|
||||
unit: "ms",
|
||||
}
|
||||
);
|
||||
|
||||
/** Canonical span names emitted at the public method boundaries. */
|
||||
export const BITPACKER_STRATEGIES_SPAN_NAMES = {
|
||||
register: "bitpacker_strategies.register",
|
||||
} as const;
|
||||
@@ -0,0 +1 @@
|
||||
export { packingStrategyManagerSchema } from "./register-default-strategies.schema.js";
|
||||
@@ -0,0 +1,72 @@
|
||||
# Register Default Strategies — Schema
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Purpose
|
||||
|
||||
Zod schema for the `manager` argument of `registerDefaultStrategies`. Validates that an external caller hands the function a real `PackingStrategyManager` instance (not a plain object that "quacks like" one) so the chain ordering invariants the function depends on are guaranteed at the boundary. Identity is preserved — the parsed value is the same instance the caller passed in, so `registerDefaultStrategies(manager)` mutates the caller's manager rather than a clone.
|
||||
|
||||
This package's strategy classes are themselves parameterless and therefore expose no per-strategy options to validate. The single boundary that needs a schema is `registerDefaultStrategies(manager)`. Strategy *shape* (`canHandle`/`pack`/`unpack` are functions) is already validated upstream by `packingStrategySchema` in `@suaveplan/bitpacker`.
|
||||
|
||||
## Features
|
||||
|
||||
- `packingStrategyManagerSchema` — `z.custom<PackingStrategyManager>` `instanceof` check
|
||||
- Identity preservation (no wrapping)
|
||||
- Rejects null, undefined, and plain objects that share the manager API surface
|
||||
|
||||
## Usage: Basic Example
|
||||
|
||||
```ts
|
||||
import {
|
||||
PackingStrategyManager,
|
||||
BitPackerError,
|
||||
BITPACKER_CODES,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import {
|
||||
packingStrategyManagerSchema,
|
||||
registerDefaultStrategies,
|
||||
} from "@suaveplan/bitpacker-strategies";
|
||||
|
||||
const manager = packingStrategyManagerSchema.parse(new PackingStrategyManager());
|
||||
registerDefaultStrategies(manager);
|
||||
```
|
||||
|
||||
## Usage: Advanced Example
|
||||
|
||||
```ts
|
||||
import {
|
||||
PackingStrategyManager,
|
||||
BitPackerError,
|
||||
BITPACKER_CODES,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import {
|
||||
packingStrategyManagerSchema,
|
||||
registerDefaultStrategies,
|
||||
} from "@suaveplan/bitpacker-strategies";
|
||||
|
||||
function bootstrap(rawManager: unknown): PackingStrategyManager {
|
||||
const result = packingStrategyManagerSchema.safeParse(rawManager);
|
||||
if (!result.success) {
|
||||
throw new BitPackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
"registerDefaultStrategies received a non-manager value",
|
||||
{ cause: result.error }
|
||||
);
|
||||
}
|
||||
registerDefaultStrategies(result.data);
|
||||
return result.data;
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### `packingStrategyManagerSchema: z.ZodType<PackingStrategyManager>`
|
||||
|
||||
Strict `instanceof` validator. Returns the input value unchanged on success; throws `ZodError` with the message `"manager must be a PackingStrategyManager instance"` on failure.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- **No per-strategy schemas.** Every shipped strategy in this package is parameterless — `new ArrayPackingStrategy()`, `new ObjectPackingStrategy()`, etc. There is nothing per-strategy to validate at construction time. Strategy shape (`canHandle`/`pack`/`unpack`) is enforced by `packingStrategySchema` in `@suaveplan/bitpacker` at the registration boundary, so this package does not duplicate that validation.
|
||||
- **`instanceof` over duck-typing.** A plain object with `add`/`register` methods would compile, but the order-sensitive insertion logic in `PackingStrategyManager.register` (insert before catch-all) depends on the class internals. Refusing duck-types prevents subtle ordering bugs that would only surface deep into a pack/unpack chain.
|
||||
@@ -0,0 +1,23 @@
|
||||
import { PackingStrategyManager } from "@suaveplan/bitpacker";
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import { packingStrategyManagerSchema } from "./register-default-strategies.schema.js";
|
||||
|
||||
describe("packingStrategyManagerSchema", () => {
|
||||
it("accepts a PackingStrategyManager instance", () => {
|
||||
const manager = new PackingStrategyManager();
|
||||
expect(packingStrategyManagerSchema.parse(manager)).toBe(manager);
|
||||
});
|
||||
|
||||
it("rejects a plain object that quacks like a manager", () => {
|
||||
const fakeManager = { add() {}, register() {} };
|
||||
expect(() => packingStrategyManagerSchema.parse(fakeManager)).toThrow();
|
||||
});
|
||||
|
||||
it("rejects null", () => {
|
||||
expect(() => packingStrategyManagerSchema.parse(null)).toThrow();
|
||||
});
|
||||
|
||||
it("rejects undefined", () => {
|
||||
expect(() => packingStrategyManagerSchema.parse(undefined)).toThrow();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,16 @@
|
||||
import { PackingStrategyManager } from "@suaveplan/bitpacker";
|
||||
import z from "zod";
|
||||
|
||||
/**
|
||||
* Strict Zod schema for the `manager` argument of {@link registerDefaultStrategies}.
|
||||
*
|
||||
* Validates that the value is a `PackingStrategyManager` instance via
|
||||
* `instanceof`. Identity is preserved so `registerDefaultStrategies` mutates
|
||||
* the same manager the caller passed in.
|
||||
*/
|
||||
export const packingStrategyManagerSchema = z.custom<PackingStrategyManager>(
|
||||
(v): v is PackingStrategyManager => v instanceof PackingStrategyManager,
|
||||
{
|
||||
message: "manager must be a PackingStrategyManager instance",
|
||||
}
|
||||
);
|
||||
@@ -0,0 +1 @@
|
||||
export { registerDefaultStrategies } from "./register-default-strategies.js";
|
||||
@@ -0,0 +1,14 @@
|
||||
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## register-default-strategies
|
||||
|
||||
**Path:** `bitpacker-strategies/src/register-default-strategies.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Part of the @suaveplan/bitpacker-strategies package.
|
||||
@@ -0,0 +1,30 @@
|
||||
import { PackingStrategyManager } from "@suaveplan/bitpacker";
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import { BlobPackingStrategy } from "../strategies/blob/blob.js";
|
||||
import { StringPackingStrategy } from "../strategies/string/string.js";
|
||||
import { registerDefaultStrategies } from "./register-default-strategies.js";
|
||||
|
||||
describe("registerDefaultStrategies — chain ordering", () => {
|
||||
it("BlobPackingStrategy resolves '~' before StringPackingStrategy", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const manager = new PackingStrategyManager();
|
||||
registerDefaultStrategies(manager);
|
||||
const winner = manager.find("~");
|
||||
// Both strategies' canHandle would return true for '~' (a string),
|
||||
// so the test verifies chain ordering: Blob wins because it is
|
||||
// registered first.
|
||||
expect(winner).toBeInstanceOf(BlobPackingStrategy);
|
||||
expect(winner).not.toBeInstanceOf(StringPackingStrategy);
|
||||
});
|
||||
|
||||
it("registers Blob in the chain", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const manager = new PackingStrategyManager();
|
||||
registerDefaultStrategies(manager);
|
||||
// The chain must contain a BlobPackingStrategy somewhere.
|
||||
const blob = manager.find("~");
|
||||
expect(blob).toBeDefined();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,107 @@
|
||||
import { SpanStatusCode } from "@opentelemetry/api";
|
||||
import {
|
||||
InvalidSchemaStrategy,
|
||||
type PackingStrategyManager,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import {
|
||||
BITPACKER_STRATEGIES_SPAN_NAMES,
|
||||
getBitPackerStrategiesTracer,
|
||||
registerStrategiesDurationMs,
|
||||
registerStrategiesTotal,
|
||||
} from "../otel/instruments.js";
|
||||
import { ArrayPackingStrategy } from "../strategies/array/array.js";
|
||||
import { ArrayConfigPackingStrategy } from "../strategies/array-config/array-config.js";
|
||||
import { ArrayNotationPackingStrategy } from "../strategies/array-notation/array-notation.js";
|
||||
import { ArraySchemaPackingStrategy } from "../strategies/array-schema/array-schema.js";
|
||||
import { BigIntPackingStrategy } from "../strategies/bigint/bigint.js";
|
||||
import { BigIntArrayPackingStrategy } from "../strategies/bigint-array/bigint-array.js";
|
||||
import { BitArrayPackingStrategy } from "../strategies/bitarray/bitarray.js";
|
||||
import { BitsetPackingStrategy } from "../strategies/bitset/bitset.js";
|
||||
import { BlobPackingStrategy } from "../strategies/blob/blob.js";
|
||||
import { BooleanPackingStrategy } from "../strategies/boolean/boolean.js";
|
||||
import { ConditionalPackingStrategy } from "../strategies/conditional/conditional.js";
|
||||
import { CustomTypePackingStrategy } from "../strategies/customType/customType.js";
|
||||
import { DateTimePackingStrategy } from "../strategies/datetime/datetime.js";
|
||||
import { DefsPackingStrategy } from "../strategies/defs/defs.js";
|
||||
import { EnumPackingStrategy } from "../strategies/enum/enum.js";
|
||||
import { MapPackingStrategy } from "../strategies/map/map.js";
|
||||
import { NullPackingStrategy } from "../strategies/null/null.js";
|
||||
import { NumberPackingStrategy } from "../strategies/number/number.js";
|
||||
import { ObjectPackingStrategy } from "../strategies/object/object.js";
|
||||
import { OneOfPackingStrategy } from "../strategies/oneOf/oneOf.js";
|
||||
import { OptionalPackingStrategy } from "../strategies/optional/optional.js";
|
||||
import { OptionalMarkerPackingStrategy } from "../strategies/optional-marker/optional-marker.js";
|
||||
import { OptionalSuffixPackingStrategy } from "../strategies/optional-suffix/optional-suffix.js";
|
||||
import { SetPackingStrategy } from "../strategies/set/set.js";
|
||||
import { StringPackingStrategy } from "../strategies/string/string.js";
|
||||
import { UnionPackingStrategy } from "../strategies/union/union.js";
|
||||
import { VarIntPackingStrategy } from "../strategies/varint/varint.js";
|
||||
import { VersionPackingStrategy } from "../strategies/version/version.js";
|
||||
|
||||
/**
|
||||
* Register all built-in packing strategies on the given manager.
|
||||
*
|
||||
* Strategies are added in order from most-specific to most-general,
|
||||
* with `InvalidSchemaStrategy` as the catch-all at the end.
|
||||
*/
|
||||
export function registerDefaultStrategies(
|
||||
manager: PackingStrategyManager
|
||||
): void {
|
||||
const tracer = getBitPackerStrategiesTracer();
|
||||
tracer.startActiveSpan(BITPACKER_STRATEGIES_SPAN_NAMES.register, (span) => {
|
||||
const startedAt = Date.now();
|
||||
try {
|
||||
registerCore(manager);
|
||||
registerStrategiesTotal.add(1, { success: "true" });
|
||||
registerStrategiesDurationMs.record(Date.now() - startedAt);
|
||||
span.setStatus({ code: SpanStatusCode.OK });
|
||||
} catch (err) {
|
||||
registerStrategiesTotal.add(1, { success: "false" });
|
||||
registerStrategiesDurationMs.record(Date.now() - startedAt);
|
||||
span.setStatus({
|
||||
code: SpanStatusCode.ERROR,
|
||||
message: err instanceof Error ? err.message : String(err),
|
||||
});
|
||||
throw err;
|
||||
} finally {
|
||||
span.end();
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
function registerCore(manager: PackingStrategyManager): void {
|
||||
// Primitive / scalar strategies (most specific first)
|
||||
manager.add(new NullPackingStrategy());
|
||||
manager.add(new BooleanPackingStrategy());
|
||||
manager.add(new BigIntArrayPackingStrategy()); // before BigInt (catches bigint-i64[] / bigint-u64[])
|
||||
manager.add(new BigIntPackingStrategy());
|
||||
manager.add(new NumberPackingStrategy());
|
||||
manager.add(new VarIntPackingStrategy()); // before String ("varint" is a string token)
|
||||
manager.add(new OptionalSuffixPackingStrategy()); // before String (strips "?" from string schemas)
|
||||
manager.add(new ArrayNotationPackingStrategy()); // before String ("-5[10]" would match variable string)
|
||||
manager.add(new DateTimePackingStrategy());
|
||||
manager.add(new BitArrayPackingStrategy());
|
||||
manager.add(new BlobPackingStrategy());
|
||||
manager.add(new StringPackingStrategy());
|
||||
manager.add(new EnumPackingStrategy());
|
||||
|
||||
// Structural / meta strategies
|
||||
manager.add(new OptionalMarkerPackingStrategy()); // before Optional (more specific object shape)
|
||||
manager.add(new OptionalPackingStrategy());
|
||||
manager.add(new OneOfPackingStrategy());
|
||||
manager.add(new ConditionalPackingStrategy());
|
||||
manager.add(new VersionPackingStrategy());
|
||||
manager.add(new ArraySchemaPackingStrategy()); // before Array (tuple arrays vs homogeneous arrays)
|
||||
manager.add(new ArrayPackingStrategy());
|
||||
manager.add(new ArrayConfigPackingStrategy()); // object-based array config
|
||||
manager.add(new MapPackingStrategy());
|
||||
manager.add(new SetPackingStrategy());
|
||||
manager.add(new BitsetPackingStrategy());
|
||||
manager.add(new DefsPackingStrategy());
|
||||
manager.add(new CustomTypePackingStrategy());
|
||||
manager.add(new UnionPackingStrategy()); // before Object (discriminated union object shape)
|
||||
manager.add(new ObjectPackingStrategy()); // after all object-like markers
|
||||
|
||||
// Catch-all must be last
|
||||
manager.add(new InvalidSchemaStrategy());
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
export {
|
||||
BITPACKER_STRATEGIES_SCHEMA_VERSION,
|
||||
BITPACKER_STRATEGIES_SUBJECT,
|
||||
registerBitPackerStrategiesSchemas,
|
||||
} from "./register-schemas.js";
|
||||
@@ -0,0 +1,68 @@
|
||||
# Register Schemas — `@suaveplan/bitpacker-strategies`
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Purpose
|
||||
|
||||
Idempotent integration with `@suaveplan/schema-registry` for the `@suaveplan/bitpacker-strategies` package. Exposes a single `registerBitPackerStrategiesSchemas(registry)` function that converts the package's only public boundary schema (`packingStrategyManagerSchema`) into JSON Schema form and registers it under the canonical subject `bitpacker:@suaveplan/bitpacker-strategies` at version 1.
|
||||
|
||||
This package's strategies are parameterless, so the only registered surface is the boundary check on `registerDefaultStrategies(manager)` — the strategy classes themselves are validated by `@suaveplan/bitpacker`'s `packingStrategySchema`. Mirroring the cross-package shape avoids duplicating those schemas here.
|
||||
|
||||
## Features
|
||||
|
||||
- `BITPACKER_STRATEGIES_SUBJECT` constant — `"bitpacker:@suaveplan/bitpacker-strategies"`
|
||||
- `BITPACKER_STRATEGIES_SCHEMA_VERSION` constant — `1`
|
||||
- `registerBitPackerStrategiesSchemas(registry)` — idempotent registration
|
||||
|
||||
## Usage: Basic Example
|
||||
|
||||
```ts
|
||||
import { createRegistry } from "@suaveplan/schema-registry";
|
||||
import {
|
||||
BITPACKER_STRATEGIES_SUBJECT,
|
||||
registerBitPackerStrategiesSchemas,
|
||||
} from "@suaveplan/bitpacker-strategies/register-schemas";
|
||||
|
||||
const registry = createRegistry();
|
||||
registerBitPackerStrategiesSchemas(registry);
|
||||
console.log(registry.getLatest(BITPACKER_STRATEGIES_SUBJECT).version); // 1
|
||||
```
|
||||
|
||||
## Usage: Advanced Example
|
||||
|
||||
```ts
|
||||
import { createRegistry, SchemaRegistry } from "@suaveplan/schema-registry";
|
||||
import { registerBitPackerSchemas } from "@suaveplan/bitpacker/register-schemas";
|
||||
import { registerBitPackerStrategiesSchemas } from "@suaveplan/bitpacker-strategies/register-schemas";
|
||||
|
||||
function bootstrapAll(registry: SchemaRegistry) {
|
||||
registerBitPackerSchemas(registry);
|
||||
registerBitPackerStrategiesSchemas(registry);
|
||||
}
|
||||
|
||||
const registry = createRegistry();
|
||||
bootstrapAll(registry);
|
||||
bootstrapAll(registry); // safe: idempotent
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### `BITPACKER_STRATEGIES_SUBJECT: "bitpacker:@suaveplan/bitpacker-strategies"`
|
||||
|
||||
Const string. The exact subject under which the package's schemas are registered.
|
||||
|
||||
### `BITPACKER_STRATEGIES_SCHEMA_VERSION: 1`
|
||||
|
||||
Const number. The version under which the package's schemas are registered.
|
||||
|
||||
### `registerBitPackerStrategiesSchemas(registry: SchemaRegistry): void`
|
||||
|
||||
Idempotent registration. If the subject is already present in `registry.listSubjects()`, returns without writing. Otherwise registers the `packingStrategyManager` payload with `{ namespace, package }` metadata.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- **Single-key payload.** This package's only boundary schema is `packingStrategyManagerSchema`. The payload object keeps a single key (`packingStrategyManager`) for parity with the larger families' payloads, so a downstream consumer can pick the schema by name.
|
||||
- **Idempotency via `listSubjects()` check.** Same pattern as the core package — a membership test is sufficient to keep `version: 1` stable across re-imports.
|
||||
- **`unrepresentable: "any"`.** The strategy-manager schema uses `z.custom` for the `instanceof` check; without this option, `z.toJSONSchema` throws. Coercing to `{}` is fine because consumers reading the JSON-Schema payload are typically asking "what does this package register?" not "validate me against this schema at runtime."
|
||||
@@ -0,0 +1,33 @@
|
||||
import { createRegistry } from "@suaveplan/schema-registry";
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import {
|
||||
BITPACKER_STRATEGIES_SCHEMA_VERSION,
|
||||
BITPACKER_STRATEGIES_SUBJECT,
|
||||
registerBitPackerStrategiesSchemas,
|
||||
} from "./register-schemas.js";
|
||||
|
||||
describe("registerBitPackerStrategiesSchemas", () => {
|
||||
it("registers under the namespaced subject at version 1", () => {
|
||||
const registry = createRegistry();
|
||||
registerBitPackerStrategiesSchemas(registry);
|
||||
const latest = registry.getLatest(BITPACKER_STRATEGIES_SUBJECT);
|
||||
expect(latest.version).toBe(BITPACKER_STRATEGIES_SCHEMA_VERSION);
|
||||
});
|
||||
|
||||
it("includes the packingStrategyManager payload", () => {
|
||||
const registry = createRegistry();
|
||||
registerBitPackerStrategiesSchemas(registry);
|
||||
const payload = registry.getLatest(BITPACKER_STRATEGIES_SUBJECT)
|
||||
.schema as Record<string, unknown>;
|
||||
expect(payload).toHaveProperty("packingStrategyManager");
|
||||
});
|
||||
|
||||
it("is idempotent across repeated calls", () => {
|
||||
const registry = createRegistry();
|
||||
registerBitPackerStrategiesSchemas(registry);
|
||||
registerBitPackerStrategiesSchemas(registry);
|
||||
expect(registry.getLatest(BITPACKER_STRATEGIES_SUBJECT).version).toBe(
|
||||
1
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,44 @@
|
||||
import type { SchemaRegistry } from "@suaveplan/schema-registry";
|
||||
import z from "zod";
|
||||
import { packingStrategyManagerSchema } from "../register-default-strategies.schema/register-default-strategies.schema.js";
|
||||
|
||||
/** The exact subject under which this package's schemas are registered. */
|
||||
export const BITPACKER_STRATEGIES_SUBJECT =
|
||||
"bitpacker:@suaveplan/bitpacker-strategies" as const;
|
||||
|
||||
/** The version under which this package's schemas are registered. */
|
||||
export const BITPACKER_STRATEGIES_SCHEMA_VERSION = 1;
|
||||
|
||||
interface Payload {
|
||||
readonly packingStrategyManager: unknown;
|
||||
}
|
||||
|
||||
function buildPayload(): Payload {
|
||||
return {
|
||||
packingStrategyManager: z.toJSONSchema(packingStrategyManagerSchema, {
|
||||
unrepresentable: "any",
|
||||
}),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Idempotently register `@suaveplan/bitpacker-strategies`'s public Zod
|
||||
* schemas with the given `SchemaRegistry`. Re-registration of an
|
||||
* already-present subject is a no-op.
|
||||
*/
|
||||
export function registerBitPackerStrategiesSchemas(
|
||||
registry: SchemaRegistry
|
||||
): void {
|
||||
if (registry.listSubjects().includes(BITPACKER_STRATEGIES_SUBJECT)) {
|
||||
return;
|
||||
}
|
||||
registry.register(
|
||||
BITPACKER_STRATEGIES_SUBJECT,
|
||||
buildPayload(),
|
||||
"json-schema",
|
||||
{
|
||||
package: "@suaveplan/bitpacker-strategies",
|
||||
namespace: "bitpacker",
|
||||
}
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
# ArrayConfigPackingStrategy
|
||||
|
||||
Packs/unpacks arrays described by an explicit configuration object.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Schema shape
|
||||
|
||||
```ts
|
||||
{
|
||||
type: "array",
|
||||
maxLength: number,
|
||||
elementType: "integer" | "float" | "string" | "boolean" | "schema",
|
||||
elementMax?: number, // for integer / float / string
|
||||
elementSchema?: BitPackerSchema // for elementType "schema"
|
||||
}
|
||||
```
|
||||
|
||||
## Behaviour
|
||||
|
||||
- Writes the array length using the minimum bits required for `maxLength`.
|
||||
- Each element is packed according to its `elementType`.
|
||||
- `float` elements are encoded as unsigned integers up to `elementMax`.
|
||||
- `string` elements are encoded as fixed-length byte sequences (padded with null bytes).
|
||||
- `schema` elements are recursively packed via the strategy chain.
|
||||
@@ -0,0 +1,190 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import { BITPACKER_CODES, BitpackerError } from "@suaveplan/bitpacker";
|
||||
|
||||
function bitsRequired(maxValue: number): number {
|
||||
if (maxValue <= 0) return 0;
|
||||
return Math.floor(Math.log2(maxValue)) + 1;
|
||||
}
|
||||
|
||||
export type BitPackerArrayConfig = {
|
||||
type: "array";
|
||||
maxLength: number;
|
||||
} & (
|
||||
| { elementType: "integer"; elementMax?: number }
|
||||
| { elementType: "float"; elementMax?: number }
|
||||
| { elementType: "string"; elementMax?: number }
|
||||
| { elementType: "boolean" }
|
||||
| { elementType: "schema"; elementSchema: BitPackerSchema }
|
||||
);
|
||||
|
||||
export function isArrayConfig(schema: unknown): schema is BitPackerArrayConfig {
|
||||
if (
|
||||
typeof schema !== "object" ||
|
||||
schema === null ||
|
||||
Array.isArray(schema)
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
const obj = schema as Record<string, unknown>;
|
||||
if (obj["type"] !== "array") return false;
|
||||
if (typeof obj["maxLength"] !== "number") return false;
|
||||
if (
|
||||
!["integer", "float", "string", "boolean", "schema"].includes(
|
||||
obj["elementType"] as string
|
||||
)
|
||||
)
|
||||
return false;
|
||||
if (obj["elementType"] === "schema" && !("elementSchema" in obj))
|
||||
return false;
|
||||
return true;
|
||||
}
|
||||
|
||||
export function validateArrayData(
|
||||
data: unknown[],
|
||||
config: BitPackerArrayConfig
|
||||
): boolean {
|
||||
if (!Array.isArray(data)) return false;
|
||||
if (data.length > config.maxLength) return false;
|
||||
|
||||
return data.every((item) => {
|
||||
switch (config.elementType) {
|
||||
case "integer":
|
||||
return (
|
||||
typeof item === "number" &&
|
||||
Number.isInteger(item) &&
|
||||
item >= 0 &&
|
||||
item <= (config.elementMax || 255)
|
||||
);
|
||||
case "float":
|
||||
return (
|
||||
typeof item === "number" &&
|
||||
item >= 0 &&
|
||||
item <= (config.elementMax || 100)
|
||||
);
|
||||
case "string":
|
||||
return (
|
||||
typeof item === "string" &&
|
||||
item.length <= (config.elementMax || 100)
|
||||
);
|
||||
case "boolean":
|
||||
return typeof item === "boolean";
|
||||
case "schema":
|
||||
return true;
|
||||
default:
|
||||
return false;
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Strategy for packing array configurations.
|
||||
*
|
||||
* Schema shape: `{ type: "array", maxLength: number, elementType: "integer"|"float"|"string"|"boolean"|"schema", ... }`
|
||||
*/
|
||||
export class ArrayConfigPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return isArrayConfig(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const arrayConfig = schema as BitPackerArrayConfig;
|
||||
if (!Array.isArray(data)) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Expected array data for array configuration but received ${typeof data}`,
|
||||
{ context: { data } }
|
||||
);
|
||||
}
|
||||
|
||||
if (!validateArrayData(data, arrayConfig)) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Invalid array data for array configuration with elementType "${arrayConfig.elementType}"`,
|
||||
{ context: { data, elementType: arrayConfig.elementType } }
|
||||
);
|
||||
}
|
||||
|
||||
// Pack array length
|
||||
const lengthBits = bitsRequired(arrayConfig.maxLength);
|
||||
context.writer.writeUint(data.length, lengthBits);
|
||||
|
||||
// Pack elements
|
||||
for (const item of data) {
|
||||
switch (arrayConfig.elementType) {
|
||||
case "integer": {
|
||||
const max = arrayConfig.elementMax || 255;
|
||||
context.writer.writeUint(item as number, bitsRequired(max));
|
||||
break;
|
||||
}
|
||||
case "float": {
|
||||
const max = arrayConfig.elementMax || 100;
|
||||
context.writer.writeUint(item as number, bitsRequired(max));
|
||||
break;
|
||||
}
|
||||
case "string": {
|
||||
const maxLen = arrayConfig.elementMax || 100;
|
||||
const bytes = new TextEncoder().encode(item as string);
|
||||
const len = Math.min(bytes.length, maxLen);
|
||||
for (let i = 0; i < maxLen; i++) {
|
||||
context.writer.writeUint(i < len ? bytes[i]! : 0, 8);
|
||||
}
|
||||
break;
|
||||
}
|
||||
case "boolean":
|
||||
context.writer.writeBool(item as boolean);
|
||||
break;
|
||||
case "schema":
|
||||
context.packValue(item, arrayConfig.elementSchema);
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const arrayConfig = schema as BitPackerArrayConfig;
|
||||
const lengthBits = bitsRequired(arrayConfig.maxLength);
|
||||
const length = context.reader.readUint(lengthBits);
|
||||
const result: unknown[] = [];
|
||||
|
||||
for (let i = 0; i < length; i++) {
|
||||
switch (arrayConfig.elementType) {
|
||||
case "integer": {
|
||||
const max = arrayConfig.elementMax || 255;
|
||||
result.push(context.reader.readUint(bitsRequired(max)));
|
||||
break;
|
||||
}
|
||||
case "float": {
|
||||
const max = arrayConfig.elementMax || 100;
|
||||
result.push(context.reader.readUint(bitsRequired(max)));
|
||||
break;
|
||||
}
|
||||
case "string": {
|
||||
const maxLen = arrayConfig.elementMax || 100;
|
||||
let str = "";
|
||||
for (let j = 0; j < maxLen; j++) {
|
||||
const byte = context.reader.readUint(8);
|
||||
if (byte !== 0) str += String.fromCharCode(byte);
|
||||
}
|
||||
result.push(str);
|
||||
break;
|
||||
}
|
||||
case "boolean":
|
||||
result.push(context.reader.readBool());
|
||||
break;
|
||||
case "schema":
|
||||
result.push(context.unpackValue(arrayConfig.elementSchema));
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
# ArrayNotationPackingStrategy
|
||||
|
||||
Packs/unpacks arrays described by a string notation.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Schema shape
|
||||
|
||||
String tokens of the form `-length[elementSchema]`, e.g.:
|
||||
|
||||
- `-5[10]` → array of up to 5 integers (max 10)
|
||||
- `-5[true]` → array of up to 5 booleans
|
||||
- `-3[{"x":255}]` → array of up to 3 objects
|
||||
|
||||
## Behaviour
|
||||
|
||||
Parses the notation into an `ArrayConfig` and packs:
|
||||
|
||||
- Length prefix using the minimum bits for `length`.
|
||||
- Elements encoded according to the inner schema.
|
||||
@@ -0,0 +1,217 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import { BITPACKER_CODES, BitpackerError } from "@suaveplan/bitpacker";
|
||||
|
||||
function bitsRequired(maxValue: number): number {
|
||||
if (maxValue <= 0) return 0;
|
||||
return Math.floor(Math.log2(maxValue)) + 1;
|
||||
}
|
||||
|
||||
export type BitPackerArrayConfig = {
|
||||
type: "array";
|
||||
maxLength: number;
|
||||
} & (
|
||||
| { elementType: "integer"; elementMax?: number }
|
||||
| { elementType: "float"; elementMax?: number }
|
||||
| { elementType: "string"; elementMax?: number }
|
||||
| { elementType: "boolean" }
|
||||
| { elementType: "schema"; elementSchema: BitPackerSchema }
|
||||
);
|
||||
|
||||
export function isArrayNotation(schema: string): boolean {
|
||||
return /^-\d+\[.*\]$/.test(schema);
|
||||
}
|
||||
|
||||
export function getArrayLength(schema: string): number {
|
||||
const match = schema.match(/^-(\d+)\[/);
|
||||
if (!match?.[1]) {
|
||||
throw new Error(`Invalid array schema: ${schema}`);
|
||||
}
|
||||
return Number.parseInt(match[1], 10);
|
||||
}
|
||||
|
||||
export function getElementSchema(schema: string): string {
|
||||
const match = schema.match(/^-\d+\[(.*)\]$/);
|
||||
if (!match || match[1] === undefined) {
|
||||
throw new Error(`Invalid array schema: ${schema}`);
|
||||
}
|
||||
return match[1];
|
||||
}
|
||||
|
||||
export function parseArraySchema(schema: string): BitPackerArrayConfig | null {
|
||||
if (!isArrayNotation(schema)) return null;
|
||||
const maxLength = getArrayLength(schema);
|
||||
const elementSchema = getElementSchema(schema);
|
||||
|
||||
if (isArrayNotation(elementSchema)) {
|
||||
return {
|
||||
type: "array",
|
||||
maxLength,
|
||||
elementType: "schema",
|
||||
elementSchema,
|
||||
};
|
||||
}
|
||||
|
||||
if (elementSchema.startsWith("{") && elementSchema.endsWith("}")) {
|
||||
try {
|
||||
const normalized = elementSchema.replace(/"(\d+)"/g, "$1");
|
||||
const objectSchema = JSON.parse(normalized);
|
||||
return {
|
||||
type: "array",
|
||||
maxLength,
|
||||
elementType: "schema",
|
||||
elementSchema: objectSchema,
|
||||
};
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
if (elementSchema === "true" || elementSchema === "false") {
|
||||
return { type: "array", maxLength, elementType: "boolean" };
|
||||
}
|
||||
|
||||
if (/^-?\d+$/.test(elementSchema)) {
|
||||
return {
|
||||
type: "array",
|
||||
maxLength,
|
||||
elementType: "integer",
|
||||
elementMax: Math.abs(Number.parseInt(elementSchema, 10)),
|
||||
};
|
||||
}
|
||||
|
||||
if (elementSchema.includes(".")) {
|
||||
return {
|
||||
type: "array",
|
||||
maxLength,
|
||||
elementType: "float",
|
||||
elementMax: Math.abs(Number.parseFloat(elementSchema)),
|
||||
};
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Strategy for packing array notation strings.
|
||||
*
|
||||
* Schema tokens follow the format `-length[elementSchema]`,
|
||||
* e.g. `-5[10]` or `-5[true]`.
|
||||
*/
|
||||
export class ArrayNotationPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return typeof schema === "string" && isArrayNotation(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const config = parseArraySchema(schema as string);
|
||||
if (!config) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Invalid array schema: "${schema}"`,
|
||||
{ context: { schema } }
|
||||
);
|
||||
}
|
||||
if (!Array.isArray(data)) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Expected array data for schema "${schema}" but received ${typeof data}`,
|
||||
{ context: { schema, data } }
|
||||
);
|
||||
}
|
||||
|
||||
if (data.length > config.maxLength) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.VALUE_OUT_OF_RANGE,
|
||||
`Array length ${data.length} exceeds max ${config.maxLength}`,
|
||||
{
|
||||
context: {
|
||||
length: data.length,
|
||||
maxLength: config.maxLength,
|
||||
},
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
// Pack length
|
||||
context.writer.writeUint(data.length, bitsRequired(config.maxLength));
|
||||
|
||||
// Pack elements
|
||||
for (const item of data) {
|
||||
switch (config.elementType) {
|
||||
case "integer": {
|
||||
context.writer.writeUint(
|
||||
item as number,
|
||||
bitsRequired(config.elementMax!)
|
||||
);
|
||||
break;
|
||||
}
|
||||
case "float": {
|
||||
context.writer.writeUint(
|
||||
item as number,
|
||||
bitsRequired(config.elementMax!)
|
||||
);
|
||||
break;
|
||||
}
|
||||
|
||||
case "boolean":
|
||||
context.writer.writeBool(item as boolean);
|
||||
break;
|
||||
case "schema":
|
||||
context.packValue(item, config.elementSchema);
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const config = parseArraySchema(schema as string);
|
||||
if (!config) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Invalid array schema: ${schema}`,
|
||||
{ context: { schema } }
|
||||
);
|
||||
}
|
||||
const lengthBits = bitsRequired(config.maxLength);
|
||||
const length = context.reader.readUint(lengthBits);
|
||||
const result: unknown[] = [];
|
||||
|
||||
for (let i = 0; i < length; i++) {
|
||||
switch (config.elementType) {
|
||||
case "integer": {
|
||||
result.push(
|
||||
context.reader.readUint(
|
||||
bitsRequired(config.elementMax!)
|
||||
)
|
||||
);
|
||||
break;
|
||||
}
|
||||
case "float": {
|
||||
result.push(
|
||||
context.reader.readUint(
|
||||
bitsRequired(config.elementMax!)
|
||||
)
|
||||
);
|
||||
break;
|
||||
}
|
||||
|
||||
case "boolean":
|
||||
result.push(context.reader.readBool());
|
||||
break;
|
||||
case "schema":
|
||||
result.push(context.unpackValue(config.elementSchema));
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
# ArraySchemaPackingStrategy
|
||||
|
||||
Packs/unpacks fixed-length tuple schemas.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Schema shape
|
||||
|
||||
An array where each element is a distinct schema:
|
||||
|
||||
```ts
|
||||
[255, "-16", true] // tuple of [uint8, variable-string, boolean]
|
||||
```
|
||||
|
||||
## Behaviour
|
||||
|
||||
- No length prefix is written (the schema itself defines the arity).
|
||||
- Each data element is packed/unpacked against the schema at the same index.
|
||||
- Arrays matching suaveplan homogeneous formats (`[schema]` or `[number, schema]`)
|
||||
are delegated to `ArrayPackingStrategy`.
|
||||
@@ -0,0 +1,58 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import { BITPACKER_CODES, BitpackerError } from "@suaveplan/bitpacker";
|
||||
|
||||
function isGenesisArraySchema(schema: readonly unknown[]): boolean {
|
||||
return (
|
||||
schema.length === 1 ||
|
||||
(schema.length === 2 && typeof schema[0] === "number")
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Strategy for packing tuple-style array schemas.
|
||||
*
|
||||
* Handles schemas that are arrays where each position has its own schema,
|
||||
* e.g. `[255, "-16", true]`. This is distinct from genesis homogeneous
|
||||
* array schemas `[elementSchema]` and `[maxLength, elementSchema]`.
|
||||
*/
|
||||
export class ArraySchemaPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return Array.isArray(schema) && !isGenesisArraySchema(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const schemaArray = schema as unknown as BitPackerSchema[];
|
||||
|
||||
for (let i = 0; i < schemaArray.length; ++i) {
|
||||
const schemaItem = schemaArray[i];
|
||||
if (schemaItem === undefined) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Schema array item at index ${i} is undefined`,
|
||||
{ context: { index: i } }
|
||||
);
|
||||
}
|
||||
context.packValue(
|
||||
Array.isArray(data) ? data[i] : undefined,
|
||||
schemaItem
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const schemaArray = schema as unknown as BitPackerSchema[];
|
||||
const result: unknown[] = [];
|
||||
for (const item of schemaArray) {
|
||||
result.push(context.unpackValue(item));
|
||||
}
|
||||
return result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## array
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/array/array.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,76 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import {
|
||||
BITPACKER_CODES,
|
||||
BitpackerError,
|
||||
isArraySchema,
|
||||
} from "@suaveplan/bitpacker";
|
||||
|
||||
function bitsRequired(maxValue: number): number {
|
||||
if (maxValue <= 0) return 0;
|
||||
return Math.floor(Math.log2(maxValue)) + 1;
|
||||
}
|
||||
|
||||
export class ArrayPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return isArraySchema(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
if (!Array.isArray(data)) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Expected array, got ${typeof data}`,
|
||||
{ context: { data } }
|
||||
);
|
||||
}
|
||||
|
||||
const arr = schema as unknown as readonly BitPackerSchema[];
|
||||
const hasMaxLength = arr.length === 2 && typeof arr[0] === "number";
|
||||
const maxLength = hasMaxLength ? (arr[0] as number) : undefined;
|
||||
const elementSchema = hasMaxLength ? arr[1]! : arr[0]!;
|
||||
|
||||
if (maxLength !== undefined && data.length > maxLength) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.VALUE_OUT_OF_RANGE,
|
||||
`Array length ${data.length} exceeds max ${maxLength}`,
|
||||
{ context: { length: data.length, maxLength } }
|
||||
);
|
||||
}
|
||||
|
||||
if (maxLength !== undefined) {
|
||||
context.writer.writeUint(data.length, bitsRequired(maxLength));
|
||||
} else {
|
||||
context.writer.writeUint(data.length, 32);
|
||||
}
|
||||
|
||||
for (const item of data) {
|
||||
context.packValue(item, elementSchema);
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const arr = schema as unknown as readonly BitPackerSchema[];
|
||||
const hasMaxLength = arr.length === 2 && typeof arr[0] === "number";
|
||||
const maxLength = hasMaxLength ? (arr[0] as number) : undefined;
|
||||
const elementSchema = hasMaxLength ? arr[1]! : arr[0]!;
|
||||
|
||||
const length =
|
||||
maxLength !== undefined
|
||||
? context.reader.readUint(bitsRequired(maxLength))
|
||||
: context.reader.readUint(32);
|
||||
|
||||
const result: unknown[] = [];
|
||||
for (let i = 0; i < length; i++) {
|
||||
result.push(context.unpackValue(elementSchema));
|
||||
}
|
||||
return result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
# BigIntArrayPackingStrategy
|
||||
|
||||
Packs/unpacks arrays of 64-bit BigInt values.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Schema tokens
|
||||
|
||||
- `"bigint-i64[]"` — signed 64-bit BigInt array
|
||||
- `"bigint-u64[]"` — unsigned 64-bit BigInt array
|
||||
|
||||
## Behaviour
|
||||
|
||||
- Accepts `bigint[]`, `BigInt64Array`, or `BigUint64Array`.
|
||||
- Writes a 16-bit unsigned length prefix.
|
||||
- Each element is written as 8 bytes (big-endian).
|
||||
@@ -0,0 +1,87 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import { BITPACKER_CODES, BitpackerError } from "@suaveplan/bitpacker";
|
||||
|
||||
const LENGTH_BITS = 16;
|
||||
|
||||
/**
|
||||
* Strategy for packing BigInt array schemas.
|
||||
*
|
||||
* Handles `bigint-i64[]` (signed) and `bigint-u64[]` (unsigned) array schemas.
|
||||
*/
|
||||
export class BigIntArrayPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return schema === "bigint-i64[]" || schema === "bigint-u64[]";
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
if (
|
||||
!Array.isArray(data) &&
|
||||
!(data instanceof BigInt64Array) &&
|
||||
!(data instanceof BigUint64Array)
|
||||
) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Expected array for schema '${schema}', got ${typeof data}`,
|
||||
{ context: { schema, data } }
|
||||
);
|
||||
}
|
||||
|
||||
const arr =
|
||||
data instanceof BigInt64Array || data instanceof BigUint64Array
|
||||
? Array.from(data)
|
||||
: (data as bigint[]);
|
||||
|
||||
if (arr.length > 65535) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.VALUE_OUT_OF_RANGE,
|
||||
`Array length ${arr.length} exceeds maximum 65535`,
|
||||
{ context: { length: arr.length } }
|
||||
);
|
||||
}
|
||||
|
||||
context.writer.writeUint(arr.length, LENGTH_BITS);
|
||||
|
||||
const isSigned = schema === "bigint-i64[]";
|
||||
const buf = new ArrayBuffer(8);
|
||||
const view = new DataView(buf);
|
||||
|
||||
for (const item of arr) {
|
||||
if (isSigned) {
|
||||
view.setBigInt64(0, item, false);
|
||||
} else {
|
||||
view.setBigUint64(0, item, false);
|
||||
}
|
||||
context.writer.writeBytes(new Uint8Array(buf));
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const length = context.reader.readUint(LENGTH_BITS);
|
||||
const result: bigint[] = [];
|
||||
const isSigned = schema === "bigint-i64[]";
|
||||
|
||||
for (let i = 0; i < length; i++) {
|
||||
const bytes = context.reader.readBytes(8);
|
||||
const view = new DataView(
|
||||
bytes.buffer,
|
||||
bytes.byteOffset,
|
||||
bytes.byteLength
|
||||
);
|
||||
result.push(
|
||||
isSigned
|
||||
? view.getBigInt64(0, false)
|
||||
: view.getBigUint64(0, false)
|
||||
);
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## bigint
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/bigint/bigint.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,108 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import {
|
||||
BITPACKER_CODES,
|
||||
BitpackerError,
|
||||
isBigIntSchema,
|
||||
} from "@suaveplan/bitpacker";
|
||||
|
||||
export class BigIntPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return isBigIntSchema(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const token = schema as string;
|
||||
|
||||
if (token.endsWith("[]")) {
|
||||
this.#packBigIntArray(data as bigint[], token, context);
|
||||
} else {
|
||||
this.#packBigInt(data as bigint, token, context);
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const token = schema as string;
|
||||
|
||||
if (token.endsWith("[]")) {
|
||||
return this.#unpackBigIntArray(token, context);
|
||||
}
|
||||
return this.#unpackBigInt(token, context);
|
||||
}
|
||||
|
||||
#packBigInt(value: bigint, token: string, context: PackingContext): void {
|
||||
if (typeof value !== "bigint") {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Expected bigint for schema "${token}", got ${typeof value}`,
|
||||
{ context: { token, value } }
|
||||
);
|
||||
}
|
||||
|
||||
const isSigned = token === "bigint-i64";
|
||||
const buf = new ArrayBuffer(8);
|
||||
const view = new DataView(buf);
|
||||
|
||||
if (isSigned) {
|
||||
view.setBigInt64(0, value, false);
|
||||
} else {
|
||||
view.setBigUint64(0, value, false);
|
||||
}
|
||||
|
||||
context.writer.writeBytes(new Uint8Array(buf));
|
||||
}
|
||||
|
||||
#unpackBigInt(token: string, context: PackingContext): bigint {
|
||||
const bytes = context.reader.readBytes(8);
|
||||
const view = new DataView(
|
||||
bytes.buffer,
|
||||
bytes.byteOffset,
|
||||
bytes.byteLength
|
||||
);
|
||||
|
||||
if (token === "bigint-i64") {
|
||||
return view.getBigInt64(0, false);
|
||||
}
|
||||
return view.getBigUint64(0, false);
|
||||
}
|
||||
|
||||
#packBigIntArray(
|
||||
values: bigint[],
|
||||
token: string,
|
||||
context: PackingContext
|
||||
): void {
|
||||
if (!Array.isArray(values)) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Expected bigint[] for schema "${token}", got ${typeof values}`,
|
||||
{ context: { token, values } }
|
||||
);
|
||||
}
|
||||
|
||||
context.writer.writeUint(values.length, 32);
|
||||
|
||||
for (const value of values) {
|
||||
this.#packBigInt(value, token.replace("[]", ""), context);
|
||||
}
|
||||
}
|
||||
|
||||
#unpackBigIntArray(token: string, context: PackingContext): bigint[] {
|
||||
const length = context.reader.readUint(32);
|
||||
const result: bigint[] = [];
|
||||
const scalarToken = token.replace("[]", "") as
|
||||
| "bigint-i64"
|
||||
| "bigint-u64";
|
||||
|
||||
for (let i = 0; i < length; i++) {
|
||||
result.push(this.#unpackBigInt(scalarToken, context));
|
||||
}
|
||||
return result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## bitarray
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/bitarray/bitarray.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,79 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import { BITPACKER_CODES, BitpackerError } from "@suaveplan/bitpacker";
|
||||
|
||||
/**
|
||||
* BitArray schema: `{ _bitArray: { length: number } }` or `"bitArray"` for variable length.
|
||||
*/
|
||||
export class BitArrayPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return (
|
||||
schema === "bitArray" ||
|
||||
(typeof schema === "object" &&
|
||||
schema !== null &&
|
||||
"_bitArray" in schema)
|
||||
);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const bits = data as boolean[];
|
||||
const fixedLength =
|
||||
typeof schema === "object" &&
|
||||
schema !== null &&
|
||||
"_bitArray" in schema
|
||||
? (schema as { _bitArray: { length: number } })._bitArray.length
|
||||
: undefined;
|
||||
|
||||
if (
|
||||
!Array.isArray(bits) ||
|
||||
!bits.every((b) => typeof b === "boolean")
|
||||
) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
"Expected boolean[] for bitArray schema",
|
||||
{ context: { data } }
|
||||
);
|
||||
}
|
||||
|
||||
if (fixedLength !== undefined && bits.length !== fixedLength) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.VALUE_OUT_OF_RANGE,
|
||||
`BitArray length ${bits.length} does not match fixed length ${fixedLength}`,
|
||||
{ context: { length: bits.length, fixedLength } }
|
||||
);
|
||||
}
|
||||
|
||||
if (fixedLength === undefined) {
|
||||
context.writer.writeUint(bits.length, 32);
|
||||
}
|
||||
|
||||
for (const bit of bits) {
|
||||
context.writer.writeBool(bit);
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const fixedLength =
|
||||
typeof schema === "object" &&
|
||||
schema !== null &&
|
||||
"_bitArray" in schema
|
||||
? (schema as { _bitArray: { length: number } })._bitArray.length
|
||||
: undefined;
|
||||
|
||||
const length = fixedLength ?? context.reader.readUint(32);
|
||||
const result: boolean[] = [];
|
||||
|
||||
for (let i = 0; i < length; i++) {
|
||||
result.push(context.reader.readBool());
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## bitset
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/bitset/bitset.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,65 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import { BITPACKER_CODES, BitpackerError } from "@suaveplan/bitpacker";
|
||||
|
||||
function bitsRequired(maxValue: number): number {
|
||||
if (maxValue <= 0) return 0;
|
||||
return Math.floor(Math.log2(maxValue)) + 1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Bitset schema: `{ _bitset: { maxSize: number } }`.
|
||||
*/
|
||||
export class BitsetPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return (
|
||||
typeof schema === "object" && schema !== null && "_bitset" in schema
|
||||
);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const cfg = (schema as { _bitset: { maxSize: number } })._bitset;
|
||||
const set = data as Set<number>;
|
||||
|
||||
if (!(set instanceof Set)) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Expected Set<number> for bitset schema, got ${typeof data}`,
|
||||
{ context: { data } }
|
||||
);
|
||||
}
|
||||
|
||||
if (set.size > cfg.maxSize) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.VALUE_OUT_OF_RANGE,
|
||||
`Bitset size ${set.size} exceeds max ${cfg.maxSize}`,
|
||||
{ context: { size: set.size, maxSize: cfg.maxSize } }
|
||||
);
|
||||
}
|
||||
|
||||
context.writer.writeUint(set.size, bitsRequired(cfg.maxSize));
|
||||
|
||||
for (const index of set) {
|
||||
context.writer.writeUint(index, bitsRequired(cfg.maxSize));
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const cfg = (schema as { _bitset: { maxSize: number } })._bitset;
|
||||
const size = context.reader.readUint(bitsRequired(cfg.maxSize));
|
||||
const result = new Set<number>();
|
||||
|
||||
for (let i = 0; i < size; i++) {
|
||||
result.add(context.reader.readUint(bitsRequired(cfg.maxSize)));
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## blob
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/blob/blob.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,107 @@
|
||||
import {
|
||||
BITPACKER_CODES,
|
||||
BitPacker,
|
||||
type BitpackerError,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import { describe, expect, it } from "@suaveplan/testing/runner";
|
||||
import { registerDefaultStrategies } from "../../register-default-strategies/register-default-strategies.js";
|
||||
import { BlobPackingStrategy } from "./blob.js";
|
||||
|
||||
function makeBitPacker(): BitPacker {
|
||||
const bp = new BitPacker();
|
||||
registerDefaultStrategies(bp.strategyManager);
|
||||
return bp;
|
||||
}
|
||||
|
||||
describe("BlobPackingStrategy — adaptive '~' encoding", () => {
|
||||
it("selects 2-byte length tag for payloads under 64 KiB", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const bp = makeBitPacker();
|
||||
const data = new Uint8Array(200).fill(7);
|
||||
const bytes = bp.pack(data, "~");
|
||||
const decoded = bp.unpack(bytes, "~") as Uint8Array;
|
||||
expect(decoded).toEqual(data);
|
||||
// Tag 0 = 2-byte length. The first 2 bits of the wire encode tag.
|
||||
const firstByte = bytes[0] as number;
|
||||
const tag = (firstByte >> 6) & 0b11;
|
||||
expect(tag).toBe(0);
|
||||
});
|
||||
|
||||
it("selects 4-byte length tag for payloads over 16 MiB", {
|
||||
timeout: 30000,
|
||||
}, () => {
|
||||
const bp = makeBitPacker();
|
||||
// 17 MiB exceeds the 16,777,215-byte 3-byte cap, picks tag 2 (4 bytes).
|
||||
const length = 17 * 1024 * 1024;
|
||||
const data = new Uint8Array(length);
|
||||
const bytes = bp.pack(data, "~");
|
||||
const firstByte = bytes[0] as number;
|
||||
const tag = (firstByte >> 6) & 0b11;
|
||||
expect(tag).toBe(2);
|
||||
});
|
||||
|
||||
it("throws on payloads exceeding 1 TiB", { timeout: 5000 }, () => {
|
||||
// We can't actually allocate 1 TiB in memory; use the strategy
|
||||
// directly with a stub Uint8Array shape that reports a length
|
||||
// beyond the tag-3 cap. The strategy reads `data.length`, so the
|
||||
// stub is the cheapest reproduction.
|
||||
const strategy = new BlobPackingStrategy();
|
||||
const fakeData = Object.create(Uint8Array.prototype) as Uint8Array;
|
||||
Object.defineProperty(fakeData, "length", {
|
||||
value: 0xffffffffff + 1,
|
||||
});
|
||||
const writer = {
|
||||
writeUint: () => {},
|
||||
writeBytes: () => {},
|
||||
} as unknown as Parameters<typeof strategy.pack>[2]["writer"];
|
||||
const ctx = { writer } as unknown as Parameters<
|
||||
typeof strategy.pack
|
||||
>[2];
|
||||
try {
|
||||
strategy.pack(fakeData, "~", ctx);
|
||||
throw new Error("expected throw");
|
||||
} catch (e) {
|
||||
expect((e as BitpackerError).code).toBe(
|
||||
BITPACKER_CODES.VALUE_OUT_OF_RANGE
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
it("round-trip preserves bytes byte-identical", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const bp = makeBitPacker();
|
||||
const data = new Uint8Array(1024);
|
||||
for (let i = 0; i < data.length; i++) {
|
||||
data[i] = (i * 31 + 7) & 0xff;
|
||||
}
|
||||
const bytes = bp.pack(data, "~");
|
||||
const decoded = bp.unpack(bytes, "~") as Uint8Array;
|
||||
expect(decoded).toEqual(data);
|
||||
});
|
||||
|
||||
it("rejects non-Uint8Array data with INVALID_SCHEMA", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const bp = makeBitPacker();
|
||||
try {
|
||||
bp.pack("not bytes", "~");
|
||||
throw new Error("expected throw");
|
||||
} catch (e) {
|
||||
expect((e as BitpackerError).code).toBe(
|
||||
BITPACKER_CODES.INVALID_SCHEMA
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
it("packs and unpacks an empty payload", {
|
||||
timeout: 5000,
|
||||
}, () => {
|
||||
const bp = makeBitPacker();
|
||||
const data = new Uint8Array(0);
|
||||
const bytes = bp.pack(data, "~");
|
||||
const decoded = bp.unpack(bytes, "~") as Uint8Array;
|
||||
expect(decoded.length).toBe(0);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,101 @@
|
||||
/**
|
||||
* `BlobPackingStrategy` — adaptive binary blob serializer.
|
||||
*
|
||||
* Wire format (matches upstream `bitpacker/src/core/strategies/blob/blob.ts`):
|
||||
*
|
||||
* [2-bit tag][2..5 byte length, big-endian][raw bytes]
|
||||
*
|
||||
* The 2-bit tag selects how many bytes hold the length:
|
||||
*
|
||||
* | tag | bytes | max length |
|
||||
* |-----|-------|-------------------------|
|
||||
* | 0 | 2 | 65,535 (≈ 64 KiB) |
|
||||
* | 1 | 3 | 16,777,215 (≈ 16 MiB) |
|
||||
* | 2 | 4 | 4,294,967,295 (≈ 4 GiB) |
|
||||
* | 3 | 5 | ≈ 1 TiB |
|
||||
*
|
||||
* The strategy picks the smallest tag that fits the payload, so small
|
||||
* blobs only pay 16 bits of length overhead while still supporting
|
||||
* payloads up to ~1 TiB without a schema annotation.
|
||||
*
|
||||
* Schema notation: `"~"` (a single ASCII character — reserved keyword).
|
||||
* The token is checked before `StringPackingStrategy` in the default
|
||||
* strategy chain so it cannot be misinterpreted as a string schema.
|
||||
*/
|
||||
|
||||
import {
|
||||
BITPACKER_CODES,
|
||||
type BitPackerSchema,
|
||||
BitpackerError,
|
||||
type PackingContext,
|
||||
type PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
|
||||
const TAG_BYTE_COUNTS = [2, 3, 4, 5] as const;
|
||||
const TAG_MAX_VALUES = [
|
||||
0xffff, // tag 0 — 2 bytes — 65,535
|
||||
0xffffff, // tag 1 — 3 bytes — 16,777,215
|
||||
0xffffffff, // tag 2 — 4 bytes — 4,294,967,295
|
||||
0xffffffffff, // tag 3 — 5 bytes — 1,099,511,627,775
|
||||
] as const;
|
||||
|
||||
export class BlobPackingStrategy implements PackingStrategy {
|
||||
public canHandle(schema: BitPackerSchema): boolean {
|
||||
return schema === "~";
|
||||
}
|
||||
|
||||
public pack(
|
||||
data: unknown,
|
||||
_schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
if (!(data instanceof Uint8Array)) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Expected Uint8Array for blob schema "~", got ${typeof data}`,
|
||||
{ context: { dataType: typeof data } }
|
||||
);
|
||||
}
|
||||
|
||||
const length = data.length;
|
||||
const tag = pickTag(length);
|
||||
|
||||
// 2-bit width tag.
|
||||
context.writer.writeUint(tag, 2);
|
||||
|
||||
// Length, big-endian, in (tag + 2) bytes. Multiplication is used
|
||||
// instead of bitwise shift so payloads above 2^31 don't truncate.
|
||||
const byteCount = TAG_BYTE_COUNTS[tag] as number;
|
||||
for (let i = byteCount - 1; i >= 0; i--) {
|
||||
const byte = Math.floor(length / 256 ** i) & 0xff;
|
||||
context.writer.writeUint(byte, 8);
|
||||
}
|
||||
|
||||
context.writer.writeBytes(data);
|
||||
}
|
||||
|
||||
public unpack(_schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const tag = context.reader.readUint(2);
|
||||
const byteCount = TAG_BYTE_COUNTS[tag] as number;
|
||||
|
||||
let length = 0;
|
||||
for (let i = 0; i < byteCount; i++) {
|
||||
length = length * 256 + context.reader.readUint(8);
|
||||
}
|
||||
|
||||
return context.reader.readBytes(length);
|
||||
}
|
||||
}
|
||||
|
||||
function pickTag(length: number): number {
|
||||
for (let i = 0; i < TAG_MAX_VALUES.length; i++) {
|
||||
if (length <= (TAG_MAX_VALUES[i] as number)) {
|
||||
return i;
|
||||
}
|
||||
}
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.VALUE_OUT_OF_RANGE,
|
||||
`Blob size ${length} exceeds maximum (${TAG_MAX_VALUES[3]} bytes / ~1 TiB)`,
|
||||
{ context: { length, max: TAG_MAX_VALUES[3] } }
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## boolean
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/boolean/boolean.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,23 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
|
||||
export class BooleanPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return typeof schema === "boolean";
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
_schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
context.writer.writeBool(Boolean(data));
|
||||
}
|
||||
|
||||
unpack(_schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
return context.reader.readBool();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## conditional
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/conditional/conditional.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,152 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
|
||||
type ConditionalOp = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "has";
|
||||
|
||||
interface IfShape {
|
||||
field: string;
|
||||
op: ConditionalOp;
|
||||
value: unknown;
|
||||
}
|
||||
|
||||
interface ConditionalSchemaShape {
|
||||
_if?: IfShape;
|
||||
_when?: IfShape;
|
||||
_then: BitPackerSchema;
|
||||
_else?: BitPackerSchema;
|
||||
}
|
||||
|
||||
const NO_BRANCH = Symbol("NO_BRANCH");
|
||||
|
||||
const VALID_OPS: readonly ConditionalOp[] = [
|
||||
"==",
|
||||
"!=",
|
||||
"<",
|
||||
"<=",
|
||||
">",
|
||||
">=",
|
||||
"in",
|
||||
"has",
|
||||
];
|
||||
|
||||
function getPredicate(obj: {
|
||||
_if?: unknown;
|
||||
_when?: unknown;
|
||||
}): IfShape | undefined {
|
||||
const raw = obj._if ?? obj._when;
|
||||
if (!raw || typeof raw !== "object") return undefined;
|
||||
const predicate = raw as {
|
||||
field?: unknown;
|
||||
op?: unknown;
|
||||
value?: unknown;
|
||||
};
|
||||
if (typeof predicate.field !== "string" || predicate.field.length === 0) {
|
||||
return undefined;
|
||||
}
|
||||
if (
|
||||
typeof predicate.op !== "string" ||
|
||||
!(VALID_OPS as readonly string[]).includes(predicate.op)
|
||||
) {
|
||||
return undefined;
|
||||
}
|
||||
if (!("value" in predicate)) return undefined;
|
||||
return predicate as IfShape;
|
||||
}
|
||||
|
||||
export function isConditionalSchema(
|
||||
schema: unknown
|
||||
): schema is ConditionalSchemaShape {
|
||||
if (
|
||||
typeof schema !== "object" ||
|
||||
schema === null ||
|
||||
Array.isArray(schema)
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
const obj = schema as {
|
||||
_if?: unknown;
|
||||
_when?: unknown;
|
||||
_then?: unknown;
|
||||
};
|
||||
const predicate = getPredicate(obj);
|
||||
if (predicate === undefined) return false;
|
||||
return obj._then !== undefined;
|
||||
}
|
||||
|
||||
export function evaluatePredicate(
|
||||
ctx: unknown,
|
||||
field: string,
|
||||
op: ConditionalOp,
|
||||
value: unknown
|
||||
): boolean {
|
||||
const fieldValue =
|
||||
typeof ctx === "object" && ctx !== null
|
||||
? (ctx as Record<string, unknown>)[field]
|
||||
: undefined;
|
||||
switch (op) {
|
||||
case "==":
|
||||
return fieldValue === value;
|
||||
case "!=":
|
||||
return fieldValue !== value;
|
||||
case "<":
|
||||
return (fieldValue as number) < (value as number);
|
||||
case "<=":
|
||||
return (fieldValue as number) <= (value as number);
|
||||
case ">":
|
||||
return (fieldValue as number) > (value as number);
|
||||
case ">=":
|
||||
return (fieldValue as number) >= (value as number);
|
||||
case "in":
|
||||
return Array.isArray(value) ? value.includes(fieldValue) : false;
|
||||
case "has":
|
||||
return Array.isArray(fieldValue)
|
||||
? (fieldValue as unknown[]).includes(value)
|
||||
: false;
|
||||
}
|
||||
}
|
||||
|
||||
export class ConditionalPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return isConditionalSchema(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const cfg = schema as unknown as ConditionalSchemaShape;
|
||||
const branch = this.resolveBranch(cfg, context, data);
|
||||
if (branch === NO_BRANCH) return;
|
||||
context.packValue(data, branch as BitPackerSchema);
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const cfg = schema as unknown as ConditionalSchemaShape;
|
||||
const branch = this.resolveBranch(cfg, context, context.parentData);
|
||||
if (branch === NO_BRANCH) return undefined;
|
||||
return context.unpackValue(branch as BitPackerSchema);
|
||||
}
|
||||
|
||||
private resolveBranch(
|
||||
cfg: ConditionalSchemaShape,
|
||||
context: PackingContext,
|
||||
data: unknown
|
||||
): BitPackerSchema | typeof NO_BRANCH {
|
||||
const predicate = cfg._if ?? cfg._when;
|
||||
if (predicate === undefined) return NO_BRANCH;
|
||||
const scope = context.parentData ?? data;
|
||||
const matched = evaluatePredicate(
|
||||
scope,
|
||||
predicate.field,
|
||||
predicate.op,
|
||||
predicate.value
|
||||
);
|
||||
if (matched) return cfg._then;
|
||||
if ("_else" in cfg) return cfg._else as BitPackerSchema;
|
||||
return NO_BRANCH;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## customType
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/customType/customType.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,66 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import {
|
||||
CustomTypeRegistry,
|
||||
isCustomSchema,
|
||||
isCustomTypeSchema,
|
||||
} from "@suaveplan/bitpacker";
|
||||
|
||||
/**
|
||||
* Custom type strategy: handles two shapes:
|
||||
*
|
||||
* 1. `{ _bp: { schema: ... } }` — unwraps and delegates to the inner schema.
|
||||
* 2. `{ _customType: "handlerName" }` — looks up the handler in the process-wide
|
||||
* {@link CustomTypeRegistry} and packs/unpacks via its `pack` / `unpack` methods.
|
||||
*/
|
||||
export class CustomTypePackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return isCustomSchema(schema) || isCustomTypeSchema(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
if (isCustomSchema(schema)) {
|
||||
const inner = (schema as { _bp: { schema: BitPackerSchema } })._bp
|
||||
.schema;
|
||||
context.packValue(data, inner);
|
||||
return;
|
||||
}
|
||||
|
||||
const typeName = (schema as { _customType: string })._customType;
|
||||
const handler = CustomTypeRegistry.getInstance().get(typeName);
|
||||
if (handler === undefined) {
|
||||
throw new Error(
|
||||
`No custom type handler registered for "${typeName}"`
|
||||
);
|
||||
}
|
||||
const bytes = handler.pack(data);
|
||||
context.writer.writeUint(bytes.length, 32);
|
||||
context.writer.writeBytes(bytes);
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
if (isCustomSchema(schema)) {
|
||||
const inner = (schema as { _bp: { schema: BitPackerSchema } })._bp
|
||||
.schema;
|
||||
return context.unpackValue(inner);
|
||||
}
|
||||
|
||||
const typeName = (schema as { _customType: string })._customType;
|
||||
const handler = CustomTypeRegistry.getInstance().get(typeName);
|
||||
if (handler === undefined) {
|
||||
throw new Error(
|
||||
`No custom type handler registered for "${typeName}"`
|
||||
);
|
||||
}
|
||||
const length = context.reader.readUint(32);
|
||||
const bytes = context.reader.readBytes(length);
|
||||
return handler.unpack(bytes);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## datetime
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/datetime/datetime.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,77 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import { BITPACKER_CODES, BitpackerError } from "@suaveplan/bitpacker";
|
||||
|
||||
const DATETIME_TOKENS: readonly string[] = [
|
||||
"timestamp",
|
||||
"timestamp-ms",
|
||||
"timestamp-s",
|
||||
"timespan",
|
||||
"timespan-ms",
|
||||
"date-only",
|
||||
];
|
||||
|
||||
export class DateTimePackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return typeof schema === "string" && DATETIME_TOKENS.includes(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const token = schema as string;
|
||||
let ms: number;
|
||||
|
||||
if (data instanceof Date) {
|
||||
ms = data.getTime();
|
||||
} else if (typeof data === "number") {
|
||||
ms = data;
|
||||
} else {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Expected Date or number for datetime schema "${token}", got ${typeof data}`,
|
||||
{ context: { token, data } }
|
||||
);
|
||||
}
|
||||
|
||||
switch (token) {
|
||||
case "timestamp":
|
||||
case "timestamp-ms":
|
||||
case "date-only":
|
||||
context.writer.writeInt(ms, 53);
|
||||
break;
|
||||
case "timestamp-s":
|
||||
context.writer.writeInt(Math.floor(ms / 1000), 32);
|
||||
break;
|
||||
case "timespan":
|
||||
context.writer.writeInt(ms, 53);
|
||||
break;
|
||||
case "timespan-ms":
|
||||
context.writer.writeInt(ms, 53);
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const token = schema as string;
|
||||
|
||||
switch (token) {
|
||||
case "timestamp":
|
||||
case "timestamp-ms":
|
||||
case "date-only":
|
||||
return context.reader.readInt(53);
|
||||
case "timestamp-s":
|
||||
return context.reader.readInt(32) * 1000;
|
||||
case "timespan":
|
||||
case "timespan-ms":
|
||||
return context.reader.readInt(53);
|
||||
default:
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## defs
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/defs/defs.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,33 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
|
||||
/**
|
||||
* Defs schema: `{ _defs: { name: string } }` — look up a definition from a
|
||||
* shared definitions table passed in the BitPacker options.
|
||||
*/
|
||||
export class DefsPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return (
|
||||
typeof schema === "object" && schema !== null && "_defs" in schema
|
||||
);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const name = (schema as { _defs: { name: string } })._defs.name;
|
||||
// Defs resolution is handled by the BitPacker's schema registry
|
||||
// This strategy just passes through to the resolved schema
|
||||
context.packValue(data, { _ref: name });
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const name = (schema as { _defs: { name: string } })._defs.name;
|
||||
return context.unpackValue({ _ref: name });
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## enum
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/enum/enum.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,63 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import {
|
||||
BITPACKER_CODES,
|
||||
BitpackerError,
|
||||
isEnumSchema,
|
||||
} from "@suaveplan/bitpacker";
|
||||
|
||||
function bitsRequired(maxValue: number): number {
|
||||
if (maxValue <= 0) return 0;
|
||||
return Math.floor(Math.log2(maxValue)) + 1;
|
||||
}
|
||||
|
||||
export class EnumPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return isEnumSchema(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const { _enum: values } = schema as { _enum: readonly string[] };
|
||||
|
||||
if (typeof data !== "string") {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Enum value must be a string, got ${typeof data}`,
|
||||
{ context: { data, values } }
|
||||
);
|
||||
}
|
||||
|
||||
const index = values.indexOf(data);
|
||||
if (index === -1) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.VALUE_OUT_OF_RANGE,
|
||||
`Enum value "${data}" not in [${values.join(", ")}]`,
|
||||
{ context: { data, values } }
|
||||
);
|
||||
}
|
||||
|
||||
context.writer.writeUint(index, bitsRequired(values.length - 1));
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const { _enum: values } = schema as { _enum: readonly string[] };
|
||||
const index = context.reader.readUint(bitsRequired(values.length - 1));
|
||||
|
||||
if (index >= values.length) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.UNDERFLOW,
|
||||
`Enum index ${index} out of range (max ${values.length - 1})`,
|
||||
{ context: { index, values } }
|
||||
);
|
||||
}
|
||||
|
||||
return values[index];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## map
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/map/map.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,84 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import { BITPACKER_CODES, BitpackerError } from "@suaveplan/bitpacker";
|
||||
|
||||
function bitsRequired(maxValue: number): number {
|
||||
if (maxValue <= 0) return 0;
|
||||
return Math.floor(Math.log2(maxValue)) + 1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Map schema: `{ _map: { key: keySchema, value: valueSchema, maxSize: 255 } }`
|
||||
*/
|
||||
export class MapPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return (
|
||||
typeof schema === "object" && schema !== null && "_map" in schema
|
||||
);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const cfg = (
|
||||
schema as {
|
||||
_map: {
|
||||
key: BitPackerSchema;
|
||||
value: BitPackerSchema;
|
||||
maxSize: number;
|
||||
};
|
||||
}
|
||||
)._map;
|
||||
const map = data as Map<unknown, unknown>;
|
||||
|
||||
if (!(map instanceof Map)) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Expected Map for _map schema, got ${typeof data}`,
|
||||
{ context: { data } }
|
||||
);
|
||||
}
|
||||
|
||||
if (map.size > cfg.maxSize) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.VALUE_OUT_OF_RANGE,
|
||||
`Map size ${map.size} exceeds max ${cfg.maxSize}`,
|
||||
{ context: { size: map.size, maxSize: cfg.maxSize } }
|
||||
);
|
||||
}
|
||||
|
||||
context.writer.writeUint(map.size, bitsRequired(cfg.maxSize));
|
||||
|
||||
for (const [key, value] of map) {
|
||||
context.packValue(key, cfg.key);
|
||||
context.packValue(value, cfg.value);
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const cfg = (
|
||||
schema as {
|
||||
_map: {
|
||||
key: BitPackerSchema;
|
||||
value: BitPackerSchema;
|
||||
maxSize: number;
|
||||
};
|
||||
}
|
||||
)._map;
|
||||
const size = context.reader.readUint(bitsRequired(cfg.maxSize));
|
||||
const result = new Map<unknown, unknown>();
|
||||
|
||||
for (let i = 0; i < size; i++) {
|
||||
const key = context.unpackValue(cfg.key);
|
||||
const value = context.unpackValue(cfg.value);
|
||||
result.set(key, value);
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## null
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/null/null.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,23 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
|
||||
export class NullPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return schema === null;
|
||||
}
|
||||
|
||||
pack(
|
||||
_data: unknown,
|
||||
_schema: BitPackerSchema,
|
||||
_context: PackingContext
|
||||
): void {
|
||||
// No bits written
|
||||
}
|
||||
|
||||
unpack(_schema: BitPackerSchema, _context: PackingContext): unknown {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## number
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/number/number.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,136 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import { BITPACKER_CODES, BitpackerError } from "@suaveplan/bitpacker";
|
||||
|
||||
function bitsRequired(maxValue: number): number {
|
||||
return Math.floor(Math.log2(maxValue)) + 1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Strategy for integer and fixed-point schemas.
|
||||
*
|
||||
* Schema token is a **number**:
|
||||
* - positive integer → unsigned integer (0 … maxValue)
|
||||
* - negative integer → signed integer (-maxValue … +maxValue)
|
||||
* - float (e.g. 4.2) → fixed-point (wholeBits.fractionalBits)
|
||||
*/
|
||||
export class NumberPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return typeof schema === "number";
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const schemaNum = schema as number;
|
||||
|
||||
if (Number.isInteger(schemaNum)) {
|
||||
this.#packInteger(data as number, schemaNum, context);
|
||||
} else {
|
||||
this.#packFixed(data as number, schemaNum, context);
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const schemaNum = schema as number;
|
||||
|
||||
if (Number.isInteger(schemaNum)) {
|
||||
return this.#unpackInteger(schemaNum, context);
|
||||
}
|
||||
return this.#unpackFixed(schemaNum, context);
|
||||
}
|
||||
|
||||
#packInteger(value: number, schema: number, context: PackingContext): void {
|
||||
if (schema === 0) {
|
||||
if (value !== 0) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.VALUE_OUT_OF_RANGE,
|
||||
`Integer schema 0 only allows value 0, got ${value}`,
|
||||
{ context: { value, schema } }
|
||||
);
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
const isSigned = schema < 0;
|
||||
const maxVal = Math.abs(schema);
|
||||
const bits = bitsRequired(maxVal);
|
||||
|
||||
if (Math.abs(value) > maxVal) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.VALUE_OUT_OF_RANGE,
|
||||
`Value ${value} out of range for schema ${schema}`,
|
||||
{ context: { value, schema, max: maxVal } }
|
||||
);
|
||||
}
|
||||
|
||||
if (isSigned) {
|
||||
context.writer.writeUint(value < 0 ? 1 : 0, 1);
|
||||
}
|
||||
|
||||
context.writer.writeUint(Math.abs(value), bits);
|
||||
}
|
||||
|
||||
#unpackInteger(schema: number, context: PackingContext): number {
|
||||
if (schema === 0) return 0;
|
||||
|
||||
const isSigned = schema < 0;
|
||||
const maxVal = Math.abs(schema);
|
||||
const bits = bitsRequired(maxVal);
|
||||
|
||||
let value: number;
|
||||
if (isSigned) {
|
||||
const negative = context.reader.readUint(1) === 1;
|
||||
value = context.reader.readUint(bits);
|
||||
if (negative) value = -value;
|
||||
} else {
|
||||
value = context.reader.readUint(bits);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
#packFixed(value: number, schema: number, context: PackingContext): void {
|
||||
const [wholeStr, fracStr] = String(schema).split(".");
|
||||
const wholeBits = Math.abs(Number(wholeStr));
|
||||
const fracBits = Number(fracStr);
|
||||
const totalBits = wholeBits + fracBits;
|
||||
const isSigned = Number(wholeStr) < 0;
|
||||
|
||||
const factor = 1 << fracBits;
|
||||
const scaled = Math.round(value * factor);
|
||||
|
||||
const maxVal = (1 << totalBits) - 1;
|
||||
if (Math.abs(scaled) > maxVal) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.VALUE_OUT_OF_RANGE,
|
||||
`Fixed-point value ${value} out of range for schema ${schema}`,
|
||||
{ context: { value, schema, scaled, max: maxVal } }
|
||||
);
|
||||
}
|
||||
|
||||
if (isSigned) {
|
||||
context.writer.writeInt(scaled, totalBits);
|
||||
} else {
|
||||
context.writer.writeUint(scaled, totalBits);
|
||||
}
|
||||
}
|
||||
|
||||
#unpackFixed(schema: number, context: PackingContext): number {
|
||||
const [wholeStr, fracStr] = String(schema).split(".");
|
||||
const wholeBits = Math.abs(Number(wholeStr));
|
||||
const fracBits = Number(fracStr);
|
||||
const totalBits = wholeBits + fracBits;
|
||||
const isSigned = Number(wholeStr) < 0;
|
||||
|
||||
const scaled = isSigned
|
||||
? context.reader.readInt(totalBits)
|
||||
: context.reader.readUint(totalBits);
|
||||
|
||||
return scaled / (1 << fracBits);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## object
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/object/object.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,59 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import {
|
||||
BITPACKER_CODES,
|
||||
BitpackerError,
|
||||
isObjectSchema,
|
||||
} from "@suaveplan/bitpacker";
|
||||
|
||||
function isPlainObject(value: unknown): value is Record<string, unknown> {
|
||||
return typeof value === "object" && value !== null && !Array.isArray(value);
|
||||
}
|
||||
|
||||
export class ObjectPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return isObjectSchema(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
if (!isPlainObject(data)) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Expected object, got ${typeof data}`,
|
||||
{ context: { data } }
|
||||
);
|
||||
}
|
||||
|
||||
const schemaObj = schema as Record<string, BitPackerSchema>;
|
||||
const dataObj = data as Record<string, unknown>;
|
||||
|
||||
for (const key of Object.keys(schemaObj)) {
|
||||
const fieldSchema = schemaObj[key];
|
||||
if (fieldSchema === undefined) continue;
|
||||
const fieldValue = Object.hasOwn(dataObj, key)
|
||||
? dataObj[key]
|
||||
: undefined;
|
||||
context.packValue(fieldValue, fieldSchema, dataObj);
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const schemaObj = schema as Record<string, BitPackerSchema>;
|
||||
const result: Record<string, unknown> = {};
|
||||
|
||||
for (const key of Object.keys(schemaObj)) {
|
||||
const fieldSchema = schemaObj[key];
|
||||
if (fieldSchema === undefined) continue;
|
||||
result[key] = context.unpackValue(fieldSchema, result);
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## oneOf
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/oneOf/oneOf.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,111 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import {
|
||||
BITPACKER_CODES,
|
||||
BitpackerError,
|
||||
isOneOfSchema,
|
||||
} from "@suaveplan/bitpacker";
|
||||
|
||||
function bitsRequired(maxValue: number): number {
|
||||
if (maxValue <= 0) return 0;
|
||||
return Math.floor(Math.log2(maxValue)) + 1;
|
||||
}
|
||||
|
||||
export class OneOfPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return isOneOfSchema(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const { _oneOf: schemas } = schema as {
|
||||
_oneOf: readonly BitPackerSchema[];
|
||||
};
|
||||
|
||||
let matchedIndex = -1;
|
||||
for (let i = 0; i < schemas.length; i++) {
|
||||
const s = schemas[i]!;
|
||||
if (this.#canPack(data, s)) {
|
||||
matchedIndex = i;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
if (matchedIndex === -1) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
"Data does not match any branch of _oneOf",
|
||||
{ context: { data, schemas } }
|
||||
);
|
||||
}
|
||||
|
||||
context.writer.writeUint(
|
||||
matchedIndex,
|
||||
bitsRequired(schemas.length - 1)
|
||||
);
|
||||
context.packValue(data, schemas[matchedIndex]!);
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const { _oneOf: schemas } = schema as {
|
||||
_oneOf: readonly BitPackerSchema[];
|
||||
};
|
||||
const index = context.reader.readUint(bitsRequired(schemas.length - 1));
|
||||
|
||||
if (index >= schemas.length) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.UNDERFLOW,
|
||||
`_oneOf tag ${index} out of range (max ${schemas.length - 1})`,
|
||||
{ context: { index, schemas } }
|
||||
);
|
||||
}
|
||||
|
||||
return context.unpackValue(schemas[index]!);
|
||||
}
|
||||
|
||||
#canPack(data: unknown, schema: BitPackerSchema): boolean {
|
||||
switch (typeof schema) {
|
||||
case "boolean":
|
||||
return typeof data === "boolean";
|
||||
case "number":
|
||||
return typeof data === "number";
|
||||
case "string":
|
||||
return typeof data === "string";
|
||||
case "object":
|
||||
if (schema === null) return data === null;
|
||||
if (Array.isArray(schema)) return Array.isArray(data);
|
||||
if (isOneOfSchema(schema)) return true;
|
||||
if ("_optional" in schema) {
|
||||
return (
|
||||
data === undefined ||
|
||||
data === null ||
|
||||
this.#canPack(
|
||||
data,
|
||||
(schema as { _optional: BitPackerSchema })._optional
|
||||
)
|
||||
);
|
||||
}
|
||||
if ("_enum" in schema) {
|
||||
return (
|
||||
typeof data === "string" &&
|
||||
(schema as { _enum: readonly string[] })._enum.includes(
|
||||
data
|
||||
)
|
||||
);
|
||||
}
|
||||
return (
|
||||
typeof data === "object" &&
|
||||
data !== null &&
|
||||
!Array.isArray(data)
|
||||
);
|
||||
default:
|
||||
return false;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
# OptionalMarkerPackingStrategy
|
||||
|
||||
Packs/unpacks optional values using an explicit marker object.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Schema shape
|
||||
|
||||
```ts
|
||||
{
|
||||
_optional: true,
|
||||
_schema: BitPackerSchema,
|
||||
_default?: unknown // returned when value is absent
|
||||
}
|
||||
```
|
||||
|
||||
## Behaviour
|
||||
|
||||
- Writes a single boolean presence bit.
|
||||
- When present, the inner `_schema` is packed/unpacked normally.
|
||||
- When absent on unpack, returns `_default` if defined, otherwise `undefined`.
|
||||
@@ -0,0 +1,59 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
|
||||
interface OptionalMarkerSchema {
|
||||
_optional: true;
|
||||
_schema: BitPackerSchema;
|
||||
_default?: unknown;
|
||||
}
|
||||
|
||||
export function isOptionalMarkerSchema(
|
||||
schema: unknown
|
||||
): schema is OptionalMarkerSchema {
|
||||
if (
|
||||
typeof schema !== "object" ||
|
||||
schema === null ||
|
||||
Array.isArray(schema)
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
const obj = schema as { _optional?: unknown; _schema?: unknown };
|
||||
return obj._optional === true && obj._schema !== undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Object-level optional marker: `{ _optional: true, _schema: {...}, _default?: ... }`.
|
||||
*
|
||||
* Packs a single presence bit. On unpack, missing data returns `_default`
|
||||
* when declared, otherwise `undefined`.
|
||||
*/
|
||||
export class OptionalMarkerPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return isOptionalMarkerSchema(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const cfg = schema as OptionalMarkerSchema;
|
||||
const hasValue = data !== undefined && data !== null;
|
||||
context.writer.writeBool(hasValue);
|
||||
if (hasValue) {
|
||||
context.packValue(data, cfg._schema);
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const cfg = schema as OptionalMarkerSchema;
|
||||
const hasValue = context.reader.readBool();
|
||||
if (!hasValue) {
|
||||
return "_default" in cfg ? cfg._default : undefined;
|
||||
}
|
||||
return context.unpackValue(cfg._schema);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
# OptionalSuffixPackingStrategy
|
||||
|
||||
Packs/unpacks optional primitive schemas using a `?` suffix.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Schema tokens
|
||||
|
||||
Any valid schema string followed by `?`, e.g.:
|
||||
|
||||
- `"uuid?"` → optional UUID
|
||||
- `"20?"` → optional fixed 20-byte string
|
||||
- `"-20?"` → optional variable-length string
|
||||
- `"varint?"` → optional varint
|
||||
|
||||
## Behaviour
|
||||
|
||||
- Writes a single boolean presence bit.
|
||||
- When present, strips the `?` and delegates packing/unpacking to the base schema.
|
||||
- When absent on unpack, returns `undefined`.
|
||||
@@ -0,0 +1,50 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
|
||||
/**
|
||||
* Primitive optional suffix: any string token followed by `?` becomes an
|
||||
* optional form of the underlying token. A single presence bit is packed;
|
||||
* when set, the base schema is packed / unpacked normally.
|
||||
*
|
||||
* Examples: `"uuid?"`, `"20?"`, `"-20?"`, `"timestamp?"`, `"varint?"`.
|
||||
*/
|
||||
export class OptionalSuffixPackingStrategy implements PackingStrategy {
|
||||
static isOptionalSuffix(schema: unknown): schema is `${string}?` {
|
||||
if (typeof schema !== "string") return false;
|
||||
if (!schema.endsWith("?")) return false;
|
||||
const base = schema.slice(0, -1);
|
||||
if (base.length === 0) return false;
|
||||
return !base.endsWith("?");
|
||||
}
|
||||
|
||||
static baseSchema(schema: string): string {
|
||||
return schema.slice(0, -1);
|
||||
}
|
||||
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return OptionalSuffixPackingStrategy.isOptionalSuffix(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const base = OptionalSuffixPackingStrategy.baseSchema(schema as string);
|
||||
const hasValue = data !== undefined && data !== null;
|
||||
context.writer.writeBool(hasValue);
|
||||
if (hasValue) {
|
||||
context.packValue(data, base);
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const base = OptionalSuffixPackingStrategy.baseSchema(schema as string);
|
||||
const hasValue = context.reader.readBool();
|
||||
if (!hasValue) return undefined;
|
||||
return context.unpackValue(base);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## optional
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/optional/optional.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,37 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import { isOptionalSchema } from "@suaveplan/bitpacker";
|
||||
|
||||
export class OptionalPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return isOptionalSchema(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const { _optional: inner } = schema as { _optional: BitPackerSchema };
|
||||
|
||||
const present = data !== undefined && data !== null;
|
||||
context.writer.writeBool(present);
|
||||
|
||||
if (present) {
|
||||
context.packValue(data, inner);
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const { _optional: inner } = schema as { _optional: BitPackerSchema };
|
||||
|
||||
const present = context.reader.readBool();
|
||||
if (!present) {
|
||||
return undefined;
|
||||
}
|
||||
return context.unpackValue(inner);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## set
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/set/set.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,69 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import { BITPACKER_CODES, BitpackerError } from "@suaveplan/bitpacker";
|
||||
|
||||
function bitsRequired(maxValue: number): number {
|
||||
if (maxValue <= 0) return 0;
|
||||
return Math.floor(Math.log2(maxValue)) + 1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Set schema: `{ _set: { element: elementSchema, maxSize: 255 } }`
|
||||
*/
|
||||
export class SetPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return (
|
||||
typeof schema === "object" && schema !== null && "_set" in schema
|
||||
);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const cfg = (
|
||||
schema as { _set: { element: BitPackerSchema; maxSize: number } }
|
||||
)._set;
|
||||
const set = data as Set<unknown>;
|
||||
|
||||
if (!(set instanceof Set)) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Expected Set for _set schema, got ${typeof data}`,
|
||||
{ context: { data } }
|
||||
);
|
||||
}
|
||||
|
||||
if (set.size > cfg.maxSize) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.VALUE_OUT_OF_RANGE,
|
||||
`Set size ${set.size} exceeds max ${cfg.maxSize}`,
|
||||
{ context: { size: set.size, maxSize: cfg.maxSize } }
|
||||
);
|
||||
}
|
||||
|
||||
context.writer.writeUint(set.size, bitsRequired(cfg.maxSize));
|
||||
|
||||
for (const item of set) {
|
||||
context.packValue(item, cfg.element);
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const cfg = (
|
||||
schema as { _set: { element: BitPackerSchema; maxSize: number } }
|
||||
)._set;
|
||||
const size = context.reader.readUint(bitsRequired(cfg.maxSize));
|
||||
const result = new Set<unknown>();
|
||||
|
||||
for (let i = 0; i < size; i++) {
|
||||
result.add(context.unpackValue(cfg.element));
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## string
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/string/string.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,224 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import {
|
||||
BITPACKER_CODES,
|
||||
BitpackerError,
|
||||
isFixedFloatSchema,
|
||||
isFloatSchema,
|
||||
isUuidSchema,
|
||||
} from "@suaveplan/bitpacker";
|
||||
|
||||
function bitsRequired(maxValue: number): number {
|
||||
if (maxValue <= 0) return 0;
|
||||
return Math.floor(Math.log2(maxValue)) + 1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Strategy for string schemas.
|
||||
*
|
||||
* Handles:
|
||||
* - Fixed strings: `"20"` → exactly 20 bytes
|
||||
* - Variable strings:`"-20"` → up to 20 bytes with length prefix
|
||||
* - UUID: `"uuid"` → 16 bytes
|
||||
* - Float: `"f32"`, `"f64"` → IEEE-754 floats
|
||||
* - Fixed float: `"4.2"`, `"-4.2"` → fixed-point numbers encoded as strings
|
||||
*/
|
||||
export class StringPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return typeof schema === "string";
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const s = schema as string;
|
||||
|
||||
if (isUuidSchema(s)) {
|
||||
this.#packUuid(data, context);
|
||||
} else if (isFloatSchema(s)) {
|
||||
this.#packFloat(data as number, s, context);
|
||||
} else if (isFixedFloatSchema(s)) {
|
||||
this.#packFixedFloat(data as number | string, s, context);
|
||||
} else {
|
||||
this.#packString(data as string, s, context);
|
||||
}
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const s = schema as string;
|
||||
|
||||
if (isUuidSchema(s)) {
|
||||
return this.#unpackUuid(context);
|
||||
}
|
||||
if (isFloatSchema(s)) {
|
||||
return this.#unpackFloat(s, context);
|
||||
}
|
||||
if (isFixedFloatSchema(s)) {
|
||||
return this.#unpackFixedFloat(s, context);
|
||||
}
|
||||
return this.#unpackString(s, context);
|
||||
}
|
||||
|
||||
#packString(value: string, schema: string, context: PackingContext): void {
|
||||
const isFixed = !schema.startsWith("-");
|
||||
const maxLength = Number(isFixed ? schema : schema.slice(1));
|
||||
|
||||
if (typeof value !== "string") {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Expected string for schema "${schema}", got ${typeof value}`,
|
||||
{ context: { schema, value } }
|
||||
);
|
||||
}
|
||||
|
||||
const bytes = new TextEncoder().encode(value);
|
||||
const length = Math.min(bytes.length, maxLength);
|
||||
|
||||
if (isFixed && bytes.length > maxLength) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.VALUE_OUT_OF_RANGE,
|
||||
`String length ${bytes.length} exceeds fixed schema length ${maxLength}`,
|
||||
{ context: { schema, length: bytes.length, maxLength } }
|
||||
);
|
||||
}
|
||||
|
||||
if (!isFixed) {
|
||||
context.writer.writeUint(length, bitsRequired(maxLength));
|
||||
}
|
||||
|
||||
const writeCount = isFixed ? maxLength : length;
|
||||
for (let i = 0; i < writeCount; i++) {
|
||||
context.writer.writeUint(i < bytes.length ? bytes[i]! : 0, 8);
|
||||
}
|
||||
}
|
||||
|
||||
#unpackString(schema: string, context: PackingContext): string {
|
||||
const isFixed = !schema.startsWith("-");
|
||||
const maxLength = Number(isFixed ? schema : schema.slice(1));
|
||||
|
||||
let length = maxLength;
|
||||
if (!isFixed) {
|
||||
length = context.reader.readUint(bitsRequired(maxLength));
|
||||
}
|
||||
|
||||
const bytes = new Uint8Array(length);
|
||||
for (let i = 0; i < length; i++) {
|
||||
bytes[i] = context.reader.readUint(8);
|
||||
}
|
||||
|
||||
let actualLength = length;
|
||||
while (actualLength > 0 && bytes[actualLength - 1] === 0) {
|
||||
actualLength--;
|
||||
}
|
||||
|
||||
return new TextDecoder().decode(bytes.subarray(0, actualLength));
|
||||
}
|
||||
|
||||
#packUuid(value: unknown, context: PackingContext): void {
|
||||
let bytes: Uint8Array;
|
||||
if (typeof value === "string" && value.includes("-")) {
|
||||
const hex = value.replace(/-/g, "");
|
||||
if (hex.length !== 32) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.VALUE_OUT_OF_RANGE,
|
||||
`Invalid UUID string: ${value}`,
|
||||
{ context: { value } }
|
||||
);
|
||||
}
|
||||
bytes = new Uint8Array(16);
|
||||
for (let i = 0; i < 16; i++) {
|
||||
bytes[i] = Number.parseInt(hex.substring(i * 2, i * 2 + 2), 16);
|
||||
}
|
||||
} else if (value instanceof Uint8Array && value.length === 16) {
|
||||
bytes = value;
|
||||
} else {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
"UUID must be a 36-char string or 16-byte Uint8Array",
|
||||
{ context: { value } }
|
||||
);
|
||||
}
|
||||
context.writer.writeBytes(bytes);
|
||||
}
|
||||
|
||||
#unpackUuid(context: PackingContext): string {
|
||||
const bytes = context.reader.readBytes(16);
|
||||
const hex = Array.from(bytes)
|
||||
.map((b) => b.toString(16).padStart(2, "0"))
|
||||
.join("");
|
||||
return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
|
||||
}
|
||||
|
||||
#packFloat(value: number, schema: string, context: PackingContext): void {
|
||||
if (typeof value !== "number") {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Expected number for float schema "${schema}", got ${typeof value}`,
|
||||
{ context: { schema, value } }
|
||||
);
|
||||
}
|
||||
if (schema === "f32") {
|
||||
const buf = new ArrayBuffer(4);
|
||||
new DataView(buf).setFloat32(0, value, false);
|
||||
context.writer.writeBytes(new Uint8Array(buf));
|
||||
} else {
|
||||
const buf = new ArrayBuffer(8);
|
||||
new DataView(buf).setFloat64(0, value, false);
|
||||
context.writer.writeBytes(new Uint8Array(buf));
|
||||
}
|
||||
}
|
||||
|
||||
#unpackFloat(schema: string, context: PackingContext): number {
|
||||
const bytes = context.reader.readBytes(schema === "f32" ? 4 : 8);
|
||||
const view = new DataView(
|
||||
bytes.buffer,
|
||||
bytes.byteOffset,
|
||||
bytes.byteLength
|
||||
);
|
||||
if (schema === "f32") {
|
||||
return view.getFloat32(0, false);
|
||||
}
|
||||
return view.getFloat64(0, false);
|
||||
}
|
||||
|
||||
#packFixedFloat(
|
||||
value: number | string,
|
||||
schema: string,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const [wholeStr, fracStr] = schema.split(".");
|
||||
const wholeBits = Math.abs(Number(wholeStr));
|
||||
const fracBits = Number(fracStr);
|
||||
const totalBits = wholeBits + fracBits;
|
||||
const isSigned = Number(wholeStr) < 0;
|
||||
|
||||
const numValue = typeof value === "string" ? Number(value) : value;
|
||||
const factor = 1 << fracBits;
|
||||
const scaled = Math.round(numValue * factor);
|
||||
|
||||
if (isSigned) {
|
||||
context.writer.writeInt(scaled, totalBits);
|
||||
} else {
|
||||
context.writer.writeUint(scaled, totalBits);
|
||||
}
|
||||
}
|
||||
|
||||
#unpackFixedFloat(schema: string, context: PackingContext): number {
|
||||
const [wholeStr, fracStr] = schema.split(".");
|
||||
const wholeBits = Math.abs(Number(wholeStr));
|
||||
const fracBits = Number(fracStr);
|
||||
const totalBits = wholeBits + fracBits;
|
||||
const isSigned = Number(wholeStr) < 0;
|
||||
|
||||
const scaled = isSigned
|
||||
? context.reader.readInt(totalBits)
|
||||
: context.reader.readUint(totalBits);
|
||||
|
||||
return scaled / (1 << fracBits);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## UnionPackingStrategy
|
||||
|
||||
**Export:** `UnionPackingStrategy` (class)
|
||||
|
||||
Packs and unpacks discriminated unions.
|
||||
|
||||
### Schema shape
|
||||
|
||||
```ts
|
||||
{ _union: { on: "kind", cases: { move: {...}, chat: {...} } } }
|
||||
```
|
||||
|
||||
### Behaviour
|
||||
|
||||
- **Pack:** reads the discriminator value from `data[on]`, writes its case index as a compact uint, then packs the data using the matching branch schema.
|
||||
- **Unpack:** reads the case index, then unpacks using the corresponding branch schema.
|
||||
|
||||
### Registration order
|
||||
|
||||
Must be registered **before** `ObjectPackingStrategy` because the schema is an object shape.
|
||||
@@ -0,0 +1,106 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import { BITPACKER_CODES, BitpackerError } from "@suaveplan/bitpacker";
|
||||
|
||||
interface UnionSchemaShape {
|
||||
_union: {
|
||||
on: string;
|
||||
cases: Record<string, BitPackerSchema>;
|
||||
};
|
||||
}
|
||||
|
||||
export function isUnionSchema(schema: unknown): schema is UnionSchemaShape {
|
||||
if (
|
||||
typeof schema !== "object" ||
|
||||
schema === null ||
|
||||
Array.isArray(schema)
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
const obj = schema as { _union?: unknown };
|
||||
if (!obj._union || typeof obj._union !== "object") return false;
|
||||
const union = obj._union as {
|
||||
on?: unknown;
|
||||
cases?: unknown;
|
||||
};
|
||||
if (typeof union.on !== "string") return false;
|
||||
if (
|
||||
!union.cases ||
|
||||
typeof union.cases !== "object" ||
|
||||
Array.isArray(union.cases)
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
return Object.keys(union.cases).length > 0;
|
||||
}
|
||||
|
||||
export class UnionPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return isUnionSchema(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const cfg = schema as unknown as UnionSchemaShape;
|
||||
const { on, cases } = cfg._union;
|
||||
const caseKeys = Object.keys(cases);
|
||||
const bits = Math.max(1, Math.ceil(Math.log2(caseKeys.length)));
|
||||
|
||||
const discriminator =
|
||||
typeof data === "object" && data !== null
|
||||
? (data as Record<string, unknown>)[on]
|
||||
: undefined;
|
||||
const caseIndex = caseKeys.indexOf(String(discriminator));
|
||||
if (caseIndex === -1) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Union discriminator "${String(discriminator)}" not found in cases [${caseKeys.join(", ")}]`,
|
||||
{ context: { discriminator, cases: caseKeys } }
|
||||
);
|
||||
}
|
||||
|
||||
context.writer.writeUint(caseIndex, bits);
|
||||
const caseKey = caseKeys[caseIndex]!;
|
||||
const caseSchema = cases[caseKey];
|
||||
if (caseSchema === undefined) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Union case schema for "${caseKey}" is undefined`,
|
||||
{ context: { case: caseKey } }
|
||||
);
|
||||
}
|
||||
context.packValue(data, caseSchema);
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const cfg = schema as unknown as UnionSchemaShape;
|
||||
const { cases } = cfg._union;
|
||||
const caseKeys = Object.keys(cases);
|
||||
const bits = Math.max(1, Math.ceil(Math.log2(caseKeys.length)));
|
||||
|
||||
const caseIndex = context.reader.readUint(bits);
|
||||
const caseKey = caseKeys[caseIndex];
|
||||
if (caseKey === undefined) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Union case index ${caseIndex} out of range [0, ${caseKeys.length - 1}]`,
|
||||
{ context: { caseIndex, cases: caseKeys } }
|
||||
);
|
||||
}
|
||||
const caseSchema = cases[caseKey];
|
||||
if (caseSchema === undefined) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Union case schema for "${caseKey}" is undefined`,
|
||||
{ context: { case: caseKey } }
|
||||
);
|
||||
}
|
||||
return context.unpackValue(caseSchema);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## varint
|
||||
|
||||
**Path:** `bitpacker-strategies/src/strategies/varint/varint.ts`
|
||||
**Export:** See source for details.
|
||||
|
||||
### What it does
|
||||
|
||||
Packing strategy for @suaveplan/bitpacker.
|
||||
@@ -0,0 +1,71 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import { BITPACKER_CODES, BitpackerError } from "@suaveplan/bitpacker";
|
||||
|
||||
/**
|
||||
* Variable-length integer encoding (similar to protobuf varint).
|
||||
* Schema token: `"varint"` for unsigned, `"-varint"` for signed (zigzag).
|
||||
*/
|
||||
export class VarIntPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return schema === "varint" || schema === "-varint";
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
if (typeof data !== "number" || !Number.isInteger(data)) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Expected integer for varint schema, got ${typeof data}`,
|
||||
{ context: { schema, data } }
|
||||
);
|
||||
}
|
||||
|
||||
const signed = schema === "-varint";
|
||||
let value = signed ? this.#zigzagEncode(data) : data;
|
||||
|
||||
if (value < 0) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Unsigned varint cannot be negative: ${value}`,
|
||||
{ context: { value } }
|
||||
);
|
||||
}
|
||||
|
||||
do {
|
||||
let byte = value & 0x7f;
|
||||
value >>>= 7;
|
||||
if (value !== 0) byte |= 0x80;
|
||||
context.writer.writeUint(byte, 8);
|
||||
} while (value !== 0);
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const signed = schema === "-varint";
|
||||
let value = 0;
|
||||
let shift = 0;
|
||||
let byte: number;
|
||||
|
||||
do {
|
||||
byte = context.reader.readUint(8);
|
||||
value |= (byte & 0x7f) << shift;
|
||||
shift += 7;
|
||||
} while ((byte & 0x80) !== 0);
|
||||
|
||||
return signed ? this.#zigzagDecode(value) : value;
|
||||
}
|
||||
|
||||
#zigzagEncode(n: number): number {
|
||||
return (n << 1) ^ (n >> 31);
|
||||
}
|
||||
|
||||
#zigzagDecode(n: number): number {
|
||||
return (n >>> 1) ^ -(n & 1);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,103 @@
|
||||
# VersionPackingStrategy
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## Purpose
|
||||
|
||||
Packing strategy for the version-pinned schema shape `{ _version: number; _schema: BitPackerSchema; _tolerance?: "strict" | "forward"; _allowedVersions?: number[] }`. Writes a 16-bit unsigned big-endian wire-version followed by the schema-encoded payload. On unpack, the strategy reads the wire-version and either matches it strictly against `_version` (the default) or accepts a configurable set of alternate versions when the schema opts into forward tolerance.
|
||||
|
||||
Forward tolerance is the right choice for clients that read newer-version payloads from a server they don't control: setting `_tolerance: "forward"` lets the client decode a future-versioned wire format using its current schema, as long as the consumer guarantees structural compatibility (e.g. fields added in the newer version are wrapped in `_optional` so they decode as `undefined` against the older schema). Strict mode remains the default because most consumers benefit from the early failure of a version mismatch.
|
||||
|
||||
## Features
|
||||
|
||||
- 16-bit big-endian wire-version prefix (range `[0, 65535]`)
|
||||
- Strict mode (default) — throws `BitpackerError(INVALID_SCHEMA)` on any wire-version mismatch
|
||||
- Forward-tolerant mode (`_tolerance: "forward"`) — accepts alternate versions
|
||||
- Optional `_allowedVersions: number[]` — restricts forward-tolerant acceptance to a curated allowlist
|
||||
- Wire format unchanged across all modes — only the unpack-time validation changes
|
||||
|
||||
## Usage: Basic Example
|
||||
|
||||
```ts
|
||||
import { BitPacker } from "@suaveplan/bitpacker";
|
||||
import { registerDefaultStrategies } from "@suaveplan/bitpacker-strategies";
|
||||
|
||||
const bp = new BitPacker();
|
||||
registerDefaultStrategies(bp.strategyManager);
|
||||
|
||||
const schema = { _version: 1, _schema: 255 };
|
||||
const bytes = bp.pack(42, schema);
|
||||
console.log(bp.unpack(bytes, schema)); // 42
|
||||
```
|
||||
|
||||
## Usage: Advanced Example
|
||||
|
||||
```ts
|
||||
import { BitPacker, BitpackerError, BITPACKER_CODES } from "@suaveplan/bitpacker";
|
||||
import { registerDefaultStrategies } from "@suaveplan/bitpacker-strategies";
|
||||
|
||||
const bp = new BitPacker();
|
||||
registerDefaultStrategies(bp.strategyManager);
|
||||
|
||||
// Write at version 1:
|
||||
const writeSchema = { _version: 1, _schema: 255 };
|
||||
const wireBytes = bp.pack(42, writeSchema);
|
||||
|
||||
// Read with forward tolerance, accepting versions 1-3:
|
||||
const readSchema = {
|
||||
_version: 1,
|
||||
_schema: 255,
|
||||
_tolerance: "forward" as const,
|
||||
_allowedVersions: [1, 2, 3],
|
||||
};
|
||||
console.log(bp.unpack(wireBytes, readSchema)); // 42
|
||||
|
||||
// Reading a payload tagged version 9 with the same readSchema fails:
|
||||
const futureBytes = bp.pack(42, { _version: 9, _schema: 255 });
|
||||
try {
|
||||
bp.unpack(futureBytes, readSchema);
|
||||
} catch (err) {
|
||||
if (err instanceof BitpackerError && err.code === BITPACKER_CODES.INVALID_SCHEMA) {
|
||||
// Error context: { expected: 1, received: 9, allowedVersions: [1, 2, 3] }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### `class VersionPackingStrategy implements PackingStrategy`
|
||||
|
||||
#### `canHandle(schema)`
|
||||
|
||||
Returns `true` if `isVersionSchema(schema)` is `true`.
|
||||
|
||||
#### `pack(data, schema, ctx)`
|
||||
|
||||
Writes 16 bits of `_version` masked to 16 bits, then delegates to `ctx.packValue(data, schema._schema)`.
|
||||
|
||||
#### `unpack(schema, ctx)`
|
||||
|
||||
Reads 16 bits of wire-version. Behaviour depends on `_tolerance`:
|
||||
|
||||
- `"strict"` (default, or omitted): throw `BitpackerError(INVALID_SCHEMA)` on mismatch.
|
||||
- `"forward"` with `_allowedVersions`: throw if the wire-version is NOT in the allowlist.
|
||||
- `"forward"` without `_allowedVersions`: accept any wire-version in `[0, 65535]`.
|
||||
|
||||
On acceptance, delegates to `ctx.unpackValue(schema._schema)`.
|
||||
|
||||
### `function isVersionSchema(value): value is VersionSchemaShape`
|
||||
|
||||
Type guard. Returns `true` for any object with `_version: number` (in `[0, 65535]`), `_schema: BitPackerSchema`, optional `_tolerance: "strict" | "forward"`, and optional `_allowedVersions: number[]` (each in `[0, 65535]`).
|
||||
|
||||
### `type VersionTolerance = "strict" | "forward"`
|
||||
|
||||
The two supported tolerance modes.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- **Wire format unchanged.** Forward-tolerance is purely an unpack-time decision. Bytes produced by a strict-mode pack are byte-identical to those produced by a forward-mode pack at the same `_version`. Bytes produced by either mode are unpacked equivalently when wire-versions match.
|
||||
- **Schema identity on success.** When forward-tolerance accepts an alternate wire-version, the strategy still uses `_schema` for decoding. This places the burden on the consumer to ensure the schema can decode the alternate wire format. Typical pattern: wrap fields added in newer versions in `_optional` so they decode as `undefined` against the older schema.
|
||||
- **`_allowedVersions: undefined` is permissive, `[]` is restrictive.** An empty allowlist accepts no alternate versions (forward-tolerant mode collapses to strict). An undefined allowlist with `_tolerance: "forward"` accepts any wire-version.
|
||||
- **No silent migration.** The strategy does NOT auto-migrate fields between versions. Migrations are the consumer's responsibility — typically encoded as `_optional` wrappers with default values, or as the richer `MigrationStrategy` framework in `@suaveplan/bitpacker`'s `schema-versioning-types`.
|
||||
- **Stable wire-version cap at 16 bits.** A schema with `_version > 65535` is rejected by `isVersionSchema` and would not be dispatched to this strategy in the first place.
|
||||
@@ -0,0 +1,113 @@
|
||||
import type {
|
||||
BitPackerSchema,
|
||||
PackingContext,
|
||||
PackingStrategy,
|
||||
} from "@suaveplan/bitpacker";
|
||||
import { BITPACKER_CODES, BitpackerError } from "@suaveplan/bitpacker";
|
||||
|
||||
/** Behaviour mode for the `_version` strategy on unpack. */
|
||||
export type VersionTolerance = "strict" | "forward";
|
||||
|
||||
interface VersionSchemaShape {
|
||||
_version: number;
|
||||
_schema: BitPackerSchema;
|
||||
_tolerance?: VersionTolerance;
|
||||
_allowedVersions?: readonly number[];
|
||||
}
|
||||
|
||||
export function isVersionSchema(schema: unknown): schema is VersionSchemaShape {
|
||||
if (
|
||||
typeof schema !== "object" ||
|
||||
schema === null ||
|
||||
Array.isArray(schema)
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
const obj = schema as {
|
||||
_version?: unknown;
|
||||
_schema?: unknown;
|
||||
_tolerance?: unknown;
|
||||
_allowedVersions?: unknown;
|
||||
};
|
||||
if (
|
||||
typeof obj._version !== "number" ||
|
||||
!Number.isInteger(obj._version) ||
|
||||
obj._version < 0 ||
|
||||
obj._version > 0xffff ||
|
||||
obj._schema === undefined
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
if (
|
||||
obj._tolerance !== undefined &&
|
||||
obj._tolerance !== "strict" &&
|
||||
obj._tolerance !== "forward"
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
if (obj._allowedVersions !== undefined) {
|
||||
if (!Array.isArray(obj._allowedVersions)) return false;
|
||||
for (const v of obj._allowedVersions) {
|
||||
if (
|
||||
typeof v !== "number" ||
|
||||
!Number.isInteger(v) ||
|
||||
v < 0 ||
|
||||
v > 0xffff
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
export class VersionPackingStrategy implements PackingStrategy {
|
||||
canHandle(schema: BitPackerSchema): boolean {
|
||||
return isVersionSchema(schema);
|
||||
}
|
||||
|
||||
pack(
|
||||
data: unknown,
|
||||
schema: BitPackerSchema,
|
||||
context: PackingContext
|
||||
): void {
|
||||
const cfg = schema as unknown as VersionSchemaShape;
|
||||
context.writer.writeUint(cfg._version & 0xffff, 16);
|
||||
context.packValue(data, cfg._schema);
|
||||
}
|
||||
|
||||
unpack(schema: BitPackerSchema, context: PackingContext): unknown {
|
||||
const cfg = schema as unknown as VersionSchemaShape;
|
||||
const read = context.reader.readUint(16) & 0xffff;
|
||||
const expected = cfg._version & 0xffff;
|
||||
const tolerance = cfg._tolerance ?? "strict";
|
||||
if (tolerance === "strict") {
|
||||
if (read !== expected) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Version mismatch: expected ${cfg._version}, got ${read}. Set _tolerance: "forward" to accept alternate versions.`,
|
||||
{ context: { expected: cfg._version, received: read } }
|
||||
);
|
||||
}
|
||||
return context.unpackValue(cfg._schema);
|
||||
}
|
||||
// tolerance === "forward"
|
||||
if (cfg._allowedVersions !== undefined) {
|
||||
const allowed = cfg._allowedVersions.includes(read);
|
||||
if (!allowed) {
|
||||
throw new BitpackerError(
|
||||
BITPACKER_CODES.INVALID_SCHEMA,
|
||||
`Version ${read} not in _allowedVersions [${cfg._allowedVersions.join(", ")}] (expected ${cfg._version} or one of the allowed versions).`,
|
||||
{
|
||||
context: {
|
||||
expected: cfg._version,
|
||||
received: read,
|
||||
allowedVersions: cfg._allowedVersions,
|
||||
},
|
||||
}
|
||||
);
|
||||
}
|
||||
}
|
||||
return context.unpackValue(cfg._schema);
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"$schema": "https://json.schemastore.org/tsconfig",
|
||||
"extends": "../../../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"rootDir": "./src",
|
||||
"outDir": "./dist",
|
||||
"lib": ["ES2022"],
|
||||
"types": ["node"]
|
||||
},
|
||||
"include": ["src/**/*.ts"],
|
||||
"exclude": ["src/**/*.test.ts", "src/**/*.bench.ts", "dist", "node_modules"]
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
import { defineConfig } from "vite";
|
||||
import dts from "vite-plugin-dts";
|
||||
|
||||
export default defineConfig({
|
||||
root: __dirname,
|
||||
cacheDir: "../../../node_modules/.vite/packages/bitpacker",
|
||||
plugins: [
|
||||
dts({
|
||||
entryRoot: "src",
|
||||
tsconfigPath: "./tsconfig.lib.json",
|
||||
insertTypesEntry: true,
|
||||
}),
|
||||
],
|
||||
build: {
|
||||
outDir: "./dist",
|
||||
emptyOutDir: true,
|
||||
reportCompressedSize: true,
|
||||
sourcemap: true,
|
||||
lib: { entry: "src/index.ts", formats: ["es"] },
|
||||
rollupOptions: {
|
||||
treeshake: true,
|
||||
output: {
|
||||
preserveModules: true,
|
||||
preserveModulesRoot: "src",
|
||||
entryFileNames: "[name].js",
|
||||
},
|
||||
external: [
|
||||
"tslib",
|
||||
"zod",
|
||||
"@opentelemetry/api",
|
||||
"@suaveplan/error",
|
||||
"@suaveplan/types",
|
||||
/^node:/,
|
||||
],
|
||||
},
|
||||
},
|
||||
});
|
||||
@@ -0,0 +1,9 @@
|
||||
import { defineConfig } from "vitest/config";
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
coverage: {
|
||||
provider: "istanbul",
|
||||
},
|
||||
},
|
||||
});
|
||||
Reference in New Issue
Block a user