@solana/codecs-core 8.3.0 → 8.4.0-canary-20260918134912

package/dist/types/index.d.ts

@@ -31,7 +31,7 @@
  * - [`@solana/codecs-data-structures`](https://github.com/anza-xyz/kit/tree/main/packages/codecs-data-structures) for many data structure codecs such as objects, arrays, tuples, sets, maps, enums, discriminated unions, booleans, etc.
  * - [`@solana/options`](https://github.com/anza-xyz/kit/tree/main/packages/options) for a Rust-like `Option` type and associated codec.
  *
- * You may also be interested in some of the helpers of this `@solana/codecs-core` library such as `transformCodec`, `fixCodecSize` or `reverseCodec` that create new codecs from existing ones.
+ * You may also be interested in some of the helpers of this `@solana/codecs-core` library such as `transformCodec`, `tapCodec`, `fixCodecSize` or `reverseCodec` that create new codecs from existing ones.
  *
  * Note that all of these libraries are included in the [`@solana/codecs` package](https://github.com/anza-xyz/kit/tree/main/packages/codecs) as well as the main `@solana/kit` package for your convenience.
  *
@@ -327,6 +327,48 @@
  * const getStringU32Codec = () => combineCodec(getStringU32Encoder(), getStringU32Decoder());
  * ```
  *
+ * ## Tapping codecs
+ *
+ * Whilst transforming codecs lets you _change_ the values or bytes that flow through them, tapping codecs lets you _observe_ them without changing anything. This is mostly useful for adding validation guards to existing codecs: a tap that throws aborts the operation, whilst a tap that returns normally lets the value or bytes pass through untouched.
+ *
+ * The `tapEncoder`, `tapDecoder` and `tapCodec` helpers observe the **value**. The encoder taps the input value before encoding it and the decoder taps the decoded value after decoding it.
+ *
+ * ```ts
+ * // Reject out-of-range input before it is encoded.
+ * const boundedU8 = tapEncoder(getU8Encoder(), value => {
+ *     if (value > 100) throw new Error('Value must not exceed 100');
+ * });
+ *
+ * // Validate the decoded result.
+ * const nonZeroU8 = tapDecoder(getU8Decoder(), value => {
+ *     if (value === 0) throw new Error('Value must not be zero');
+ * });
+ * ```
+ *
+ * The `tapEncoderBytes`, `tapDecoderBytes` and `tapCodecBytes` helpers observe the raw **bytes** instead. The encoder taps the encoded bytes after writing them — alongside the offsets before and after the value was written — and the decoder taps the bytes before reading them. In both cases the bytes are provided as a `ReadonlyUint8Array` so they cannot be modified.
+ *
+ * ```ts
+ * // Guard malformed boolean bytes before decoding.
+ * const safeBoolean = tapDecoderBytes(getBooleanDecoder(), (bytes, offset) => {
+ *     if (bytes[offset] > 1) throw new Error('Expected a 0 or a 1 for booleans');
+ * });
+ * ```
+ *
+ * The `tapCodec` and `tapCodecBytes` helpers accept a tap for each side — the encode-side tap is required whilst the decode-side tap is optional — mirroring the `transformCodec` signature. Since each helper preserves the exact type of the codec it wraps, you can also compose separate encoder and decoder taps using `combineCodec`.
+ *
+ * ```ts
+ * const safeBooleanCodec = combineCodec(
+ *     // Guard the value on the encode side.
+ *     tapEncoder(getBooleanEncoder(), value => {
+ *         if (typeof value !== 'boolean') throw new Error('Expected a boolean');
+ *     }),
+ *     // Guard the raw bytes on the decode side.
+ *     tapDecoderBytes(getBooleanDecoder(), (bytes, offset) => {
+ *         if (bytes[offset] > 1) throw new Error('Expected a 0 or a 1 for booleans');
+ *     }),
+ * );
+ * ```
+ *
  * ## Fixing the size of codecs
  *
  * The `fixCodecSize` function allows you to bind the size of a given codec to the given fixed size.

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4oBG;AACH,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsrBG;AACH,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/codecs-core",
-  "version": "8.3.0",
+  "version": "8.4.0-canary-20260918134912",
   "description": "Core types and helpers for encoding and decoding byte arrays on Solana",
   "homepage": "https://www.solanakit.com/api#solanacodecs-core",
   "exports": {
@@ -56,7 +56,7 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/errors": "8.3.0"
+    "@solana/errors": "8.4.0-canary-20260918134912"
   },
   "peerDependencies": {
     "typescript": ">=5.4.0"

package/src/index.ts

@@ -31,7 +31,7 @@
  * - [`@solana/codecs-data-structures`](https://github.com/anza-xyz/kit/tree/main/packages/codecs-data-structures) for many data structure codecs such as objects, arrays, tuples, sets, maps, enums, discriminated unions, booleans, etc.
  * - [`@solana/options`](https://github.com/anza-xyz/kit/tree/main/packages/options) for a Rust-like `Option` type and associated codec.
  *
- * You may also be interested in some of the helpers of this `@solana/codecs-core` library such as `transformCodec`, `fixCodecSize` or `reverseCodec` that create new codecs from existing ones.
+ * You may also be interested in some of the helpers of this `@solana/codecs-core` library such as `transformCodec`, `tapCodec`, `fixCodecSize` or `reverseCodec` that create new codecs from existing ones.
  *
  * Note that all of these libraries are included in the [`@solana/codecs` package](https://github.com/anza-xyz/kit/tree/main/packages/codecs) as well as the main `@solana/kit` package for your convenience.
  *
@@ -327,6 +327,48 @@
  * const getStringU32Codec = () => combineCodec(getStringU32Encoder(), getStringU32Decoder());
  * ```
  *
+ * ## Tapping codecs
+ *
+ * Whilst transforming codecs lets you _change_ the values or bytes that flow through them, tapping codecs lets you _observe_ them without changing anything. This is mostly useful for adding validation guards to existing codecs: a tap that throws aborts the operation, whilst a tap that returns normally lets the value or bytes pass through untouched.
+ *
+ * The `tapEncoder`, `tapDecoder` and `tapCodec` helpers observe the **value**. The encoder taps the input value before encoding it and the decoder taps the decoded value after decoding it.
+ *
+ * ```ts
+ * // Reject out-of-range input before it is encoded.
+ * const boundedU8 = tapEncoder(getU8Encoder(), value => {
+ *     if (value > 100) throw new Error('Value must not exceed 100');
+ * });
+ *
+ * // Validate the decoded result.
+ * const nonZeroU8 = tapDecoder(getU8Decoder(), value => {
+ *     if (value === 0) throw new Error('Value must not be zero');
+ * });
+ * ```
+ *
+ * The `tapEncoderBytes`, `tapDecoderBytes` and `tapCodecBytes` helpers observe the raw **bytes** instead. The encoder taps the encoded bytes after writing them — alongside the offsets before and after the value was written — and the decoder taps the bytes before reading them. In both cases the bytes are provided as a `ReadonlyUint8Array` so they cannot be modified.
+ *
+ * ```ts
+ * // Guard malformed boolean bytes before decoding.
+ * const safeBoolean = tapDecoderBytes(getBooleanDecoder(), (bytes, offset) => {
+ *     if (bytes[offset] > 1) throw new Error('Expected a 0 or a 1 for booleans');
+ * });
+ * ```
+ *
+ * The `tapCodec` and `tapCodecBytes` helpers accept a tap for each side — the encode-side tap is required whilst the decode-side tap is optional — mirroring the `transformCodec` signature. Since each helper preserves the exact type of the codec it wraps, you can also compose separate encoder and decoder taps using `combineCodec`.
+ *
+ * ```ts
+ * const safeBooleanCodec = combineCodec(
+ *     // Guard the value on the encode side.
+ *     tapEncoder(getBooleanEncoder(), value => {
+ *         if (typeof value !== 'boolean') throw new Error('Expected a boolean');
+ *     }),
+ *     // Guard the raw bytes on the decode side.
+ *     tapDecoderBytes(getBooleanDecoder(), (bytes, offset) => {
+ *         if (bytes[offset] > 1) throw new Error('Expected a 0 or a 1 for booleans');
+ *     }),
+ * );
+ * ```
+ *
  * ## Fixing the size of codecs
  *
  * The `fixCodecSize` function allows you to bind the size of a given codec to the given fixed size.