{"_id":"@atlaschain/codecs-core","name":"@atlaschain/codecs-core","dist-tags":{"latest":"3.0.0"},"versions":{"3.0.0":{"name":"@atlaschain/codecs-core","version":"3.0.0","description":"Core types and helpers for encoding and decoding byte arrays on Atlas","exports":{"edge-light":{"import":"./dist/index.node.mjs","require":"./dist/index.node.cjs"},"workerd":{"import":"./dist/index.node.mjs","require":"./dist/index.node.cjs"},"browser":{"import":"./dist/index.browser.mjs","require":"./dist/index.browser.cjs"},"node":{"import":"./dist/index.node.mjs","require":"./dist/index.node.cjs"},"react-native":"./dist/index.native.mjs","types":"./dist/types/index.d.ts"},"browser":{"./dist/index.node.cjs":"./dist/index.browser.cjs","./dist/index.node.mjs":"./dist/index.browser.mjs"},"main":"./dist/index.node.cjs","module":"./dist/index.node.mjs","react-native":"./dist/index.native.mjs","types":"./dist/types/index.d.ts","type":"commonjs","sideEffects":false,"keywords":["blockchain","atlas","web3"],"scripts":{"benchmark":"./src/__benchmarks__/run.ts","compile:docs":"typedoc","compile:js":"tsup --config build-scripts/tsup.config.package.ts","compile:typedefs":"tsc -p ./tsconfig.declarations.json","dev":"jest -c ../../node_modules/@atlas/test-config/jest-dev.config.ts --rootDir . --watch","prepublishOnly":"pnpm pkg delete devDependencies","publish-impl":"npm view $npm_package_name@$npm_package_version > /dev/null 2>&1 || (pnpm publish --tag ${PUBLISH_TAG:-canary} --access public --no-git-checks && (([ -n \"${GITHUB_OUTPUT:-}\" ] && echo 'published=true' >> \"$GITHUB_OUTPUT\") || true) && (([ \"$PUBLISH_TAG\" != \"canary\" ] && ../build-scripts/maybe-tag-latest.ts $npm_package_name@$npm_package_version) || true))","publish-packages":"pnpm prepublishOnly && pnpm publish-impl","style:fix":"pnpm eslint --fix src && pnpm prettier --log-level warn --ignore-unknown --write ./*","test:lint":"TERM_OVERRIDE=\"${TURBO_HASH:+dumb}\" TERM=${TERM_OVERRIDE:-$TERM} jest -c ../../node_modules/@atlas/test-config/jest-lint.config.ts --rootDir . --silent","test:prettier":"TERM_OVERRIDE=\"${TURBO_HASH:+dumb}\" TERM=${TERM_OVERRIDE:-$TERM} jest -c ../../node_modules/@atlas/test-config/jest-prettier.config.ts --rootDir . --silent","test:treeshakability:browser":"agadoo dist/index.browser.mjs","test:treeshakability:native":"agadoo dist/index.native.mjs","test:treeshakability:node":"agadoo dist/index.node.mjs","test:typecheck":"tsc --noEmit","test:unit:browser":"TERM_OVERRIDE=\"${TURBO_HASH:+dumb}\" TERM=${TERM_OVERRIDE:-$TERM} jest -c ../../node_modules/@atlas/test-config/jest-unit.config.browser.ts --rootDir . --silent","test:unit:node":"TERM_OVERRIDE=\"${TURBO_HASH:+dumb}\" TERM=${TERM_OVERRIDE:-$TERM} jest -c ../../node_modules/@atlas/test-config/jest-unit.config.node.ts --rootDir . --silent"},"author":{"name":"Atlas Chain Foundation"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/anza-xyz/kit.git"},"bugs":{"url":"https://github.com/anza-xyz/kit/issues"},"browserslist":["supports bigint and not dead","maintained node versions"],"dependencies":{"@atlaschain/errors":"workspace:*"},"peerDependencies":{"typescript":">=5.3.3"},"engines":{"node":">=20.18.0"},"_id":"@atlaschain/codecs-core@3.0.0","homepage":"https://github.com/anza-xyz/kit#readme","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-fQaufVkYgrSetqZG6bGgcKDoxUvAlno4/gkoWq0amPM7K262Ky/UF1pbLBcDlrXLl5xubbYePgJazwGpf4jXuQ==","shasum":"746156811766d7ff8e29ec602d80091f41be56ea","tarball":"https://registry.npmjs.org/@atlaschain/codecs-core/-/codecs-core-3.0.0.tgz","fileCount":5,"unpackedSize":65998,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCB2CHH+S96ROKsCDPTj0yo0Iug8XhhfVRbTya+wMaDbQIga+liEszOUZF6DRkkwki55B6ltLvPtgz4NbnyGF2XYwE="}]},"_npmUser":{"name":"atlaschain","email":"jq@atlaschain.org"},"directories":{},"maintainers":[{"name":"atlaschain","email":"jq@atlaschain.org"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/codecs-core_3.0.0_1756885067386_0.3406556563944765"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-03T07:37:47.316Z","3.0.0":"2025-09-03T07:37:47.560Z","modified":"2025-09-03T07:37:47.839Z"},"maintainers":[{"name":"atlaschain","email":"jq@atlaschain.org"}],"description":"Core types and helpers for encoding and decoding byte arrays on Atlas","homepage":"https://github.com/anza-xyz/kit#readme","keywords":["blockchain","atlas","web3"],"repository":{"type":"git","url":"git+https://github.com/anza-xyz/kit.git"},"author":{"name":"Atlas Chain Foundation"},"bugs":{"url":"https://github.com/anza-xyz/kit/issues"},"license":"MIT","readme":"[![npm][npm-image]][npm-url]\n[![npm-downloads][npm-downloads-image]][npm-url]\n<br />\n[![code-style-prettier][code-style-prettier-image]][code-style-prettier-url]\n\n[code-style-prettier-image]: https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square\n[code-style-prettier-url]: https://github.com/prettier/prettier\n[npm-downloads-image]: https://img.shields.io/npm/dm/@atlas/codecs-core?style=flat\n[npm-image]: https://img.shields.io/npm/v/@atlas/codecs-core?style=flat\n[npm-url]: https://www.npmjs.com/package/@atlas/codecs-core\n\n# @atlas/codecs-core\n\nThis package contains the core types and functions for encoding and decoding data structures on Atlas. It can be used standalone, but it is also exported as part of Kit [`@atlas/kit`](https://github.com/anza-xyz/kit/tree/main/packages/kit).\n\nThis package is also part of the [`@atlas/codecs` package](https://github.com/anza-xyz/kit/tree/main/packages/codecs) which acts as an entry point for all codec packages as well as for their documentation.\n\n## Composing codecs\n\nThe easiest way to create your own codecs is to compose the [various codecs](https://github.com/anza-xyz/kit/tree/main/packages/codecs) offered by this library. For instance, here’s how you would define a codec for a `Person` object that contains a `name` string attribute and an `age` number stored in 4 bytes.\n\n```ts\ntype Person = { name: string; age: number };\nconst getPersonCodec = (): Codec<Person> =>\n    getStructCodec([\n        ['name', addCodecSizePrefix(getUtf8Codec(), getU32Codec())],\n        ['age', getU32Codec()],\n    ]);\n```\n\nThis function returns a `Codec` object which contains both an `encode` and `decode` function that can be used to convert a `Person` type to and from a `Uint8Array`.\n\n```ts\nconst personCodec = getPersonCodec();\nconst bytes = personCodec.encode({ name: 'John', age: 42 });\nconst person = personCodec.decode(bytes);\n```\n\nThere is a significant library of composable codecs at your disposal, enabling you to compose complex types. You may be interested in the documentation of these other packages to learn more about them:\n\n- [`@atlas/codecs-numbers`](https://github.com/anza-xyz/kit/tree/main/packages/codecs-numbers) for number codecs.\n- [`@atlas/codecs-strings`](https://github.com/anza-xyz/kit/tree/main/packages/codecs-strings) for string codecs.\n- [`@atlas/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.\n- [`@atlas/options`](https://github.com/anza-xyz/kit/tree/main/packages/options) for a Rust-like `Option` type and associated codec.\n\nYou may also be interested in some of the helpers of this `@atlas/codecs-core` library such as `transformCodec`, `fixCodecSize` or `reverseCodec` that create new codecs from existing ones.\n\nNote that all of these libraries are included in the [`@atlas/codecs` package](https://github.com/anza-xyz/kit/tree/main/packages/codecs) as well as the main `@atlas/kit` package for your convenience.\n\n## Composing encoders and decoders\n\nWhilst Codecs can both encode and decode, it is possible to only focus on encoding or decoding data, enabling the unused logic to be tree-shaken. For instance, here’s our previous example using Encoders only to encode a `Person` type.\n\n```ts\nconst getPersonEncoder = (): Encoder<Person> =>\n    getStructEncoder([\n        ['name', addEncoderSizePrefix(getUtf8Encoder(), getU32Encoder())],\n        ['age', getU32Encoder()],\n    ]);\n\nconst bytes = getPersonEncoder().encode({ name: 'John', age: 42 });\n```\n\nThe same can be done for decoding the `Person` type by using Decoders like so.\n\n```ts\nconst getPersonDecoder = (): Decoder<Person> =>\n    getStructDecoder([\n        ['name', addDecoderSizePrefix(getUtf8Decoder(), getU32Decoder())],\n        ['age', getU32Decoder()],\n    ]);\n\nconst person = getPersonDecoder().decode(bytes);\n```\n\n## Combining encoders and decoders\n\nSeparating Codecs into Encoders and Decoders is particularly good practice for library maintainers as it allows their users to tree-shake any of the encoders and/or decoders they don’t need. However, we may still want to offer a codec helper for users who need both for convenience.\n\nThat’s why this library offers a `combineCodec` helper that creates a `Codec` instance from a matching `Encoder` and `Decoder`.\n\n```ts\nconst getPersonCodec = (): Codec<Person> => combineCodec(getPersonEncoder(), getPersonDecoder());\n```\n\nThis means library maintainers can offer Encoders, Decoders and Codecs for all their types whilst staying efficient and tree-shakeable. In summary, we recommend the following pattern when creating codecs for library types.\n\n```ts\ntype MyType = /* ... */;\nconst getMyTypeEncoder = (): Encoder<MyType> => { /* ... */ };\nconst getMyTypeDecoder = (): Decoder<MyType> => { /* ... */ };\nconst getMyTypeCodec = (): Codec<MyType> =>\n    combineCodec(getMyTypeEncoder(), getMyTypeDecoder());\n```\n\n## Different From and To types\n\nWhen creating codecs, the encoded type is allowed to be looser than the decoded type. A good example of that is the u64 number codec:\n\n```ts\nconst u64Codec: Codec<number | bigint, bigint> = getU64Codec();\n```\n\nAs you can see, the first type parameter is looser since it accepts numbers or big integers, whereas the second type parameter only accepts big integers. That’s because when _encoding_ a u64 number, you may provide either a `bigint` or a `number` for convenience. However, when you decode a u64 number, you will always get a `bigint` because not all u64 values can fit in a JavaScript `number` type.\n\n```ts\nconst bytes = u64Codec.encode(42);\nconst value = u64Codec.decode(bytes); // BigInt(42)\n```\n\nThis relationship between the type we encode “From” and decode “To” can be generalized in TypeScript as `To extends From`.\n\nHere’s another example using an object with default values. You can read more about the `transformEncoder` helper below.\n\n```ts\ntype Person = { name: string, age: number };\ntype PersonInput = { name: string, age?: number };\n\nconst getPersonEncoder = (): Encoder<PersonInput> =>\n    transformEncoder(\n        getStructEncoder([\n            ['name', addEncoderSizePrefix(getUtf8Encoder(), getU32Encoder())],\n            ['age', getU32Encoder()],\n        ]),\n        input => { ...input, age: input.age ?? 42 }\n    );\n\nconst getPersonDecoder = (): Decoder<Person> =>\n    getStructDecoder([\n        ['name', addDecoderSizePrefix(getUtf8Decoder(), getU32Decoder())],\n        ['age', getU32Decoder()],\n    ]);\n\nconst getPersonCodec = (): Codec<PersonInput, Person> =>\n  combineCodec(getPersonEncoder(), getPersonDecoder())\n```\n\n## Fixed-size and variable-size codecs\n\nIt is also worth noting that Codecs can either be of fixed size or variable size.\n\n`FixedSizeCodecs` have a `fixedSize` number attribute that tells us exactly how big their encoded data is in bytes.\n\n```ts\nconst myCodec: FixedSizeCodec<number> = getU32Codec();\nmyCodec.fixedSize; // 4 bytes.\n```\n\nOn the other hand, `VariableSizeCodecs` do not know the size of their encoded data in advance. Instead, they will grab that information either from the provided encoded data or from the value to encode. For the former, we can simply access the length of the `Uint8Array`. For the latter, it provides a `getSizeFromValue` that tells us the encoded byte size of the provided value.\n\n```ts\nconst myCodec: VariableSizeCodec<string> = addCodecSizePrefix(getUtf8Codec(), getU32Codec());\nmyCodec.getSizeFromValue('hello world'); // 4 + 11 bytes.\n```\n\nAlso note that, if the `VariableSizeCodec` is bounded by a maximum size, it can be provided as a `maxSize` number attribute.\n\nThe following type guards are available to identify and/or assert the size of codecs: `isFixedSize`, `isVariableSize`, `assertIsFixedSize` and `assertIsVariableSize`.\n\nFinally, note that the same is true for `Encoders` and `Decoders`.\n\n- A `FixedSizeEncoder` has a `fixedSize` number attribute.\n- A `VariableSizeEncoder` has a `getSizeFromValue` function and an optional `maxSize` number attribute.\n- A `FixedSizeDecoder` has a `fixedSize` number attribute.\n- A `VariableSizeDecoder` has an optional `maxSize` number attribute.\n\n## Creating custom codecs\n\nIf composing codecs isn’t enough for you, you may implement your own codec logic by using the `createCodec` function. This function requires an object with a `read` and a `write` function telling us how to read from and write to an existing byte array.\n\nThe `read` function accepts the `bytes` to decode from and the `offset` at each we should start reading. It returns an array with two items:\n\n- The first item should be the decoded value.\n- The second item should be the next offset to read from.\n\n```ts\ncreateCodec({\n    read(bytes, offset) {\n        const value = bytes[offset];\n        return [value, offset + 1];\n    },\n    // ...\n});\n```\n\nReciprocally, the `write` function accepts the `value` to encode, the array of `bytes` to write the encoded value to and the `offset` at which it should be written. It should encode the given value, insert it in the byte array, and provide the next offset to write to as the return value.\n\n```ts\ncreateCodec({\n    write(value, bytes, offset) {\n        bytes.set(value, offset);\n        return offset + 1;\n    },\n    // ...\n});\n```\n\nAdditionally, we must specify the size of the codec. If we are defining a `FixedSizeCodec`, we must simply provide the `fixedSize` number attribute. For `VariableSizeCodecs`, we must provide the `getSizeFromValue` function as described in the previous section.\n\n```ts\n// FixedSizeCodec.\ncreateCodec({\n    fixedSize: 1,\n    // ...\n});\n\n// VariableSizeCodec.\ncreateCodec({\n    getSizeFromValue: (value: string) => value.length,\n    // ...\n});\n```\n\nHere’s a concrete example of a custom codec that encodes any unsigned integer in a single byte. Since a single byte can only store integers from 0 to 255, if any other integer is provided it will take its modulo 256 to ensure it fits in a single byte. Because it always requires a single byte, that codec is a `FixedSizeCodec` of size `1`.\n\n```ts\nconst getModuloU8Codec = () =>\n    createCodec<number>({\n        fixedSize: 1,\n        read(bytes, offset) {\n            const value = bytes[offset];\n            return [value, offset + 1];\n        },\n        write(value, bytes, offset) {\n            bytes.set(value % 256, offset);\n            return offset + 1;\n        },\n    });\n```\n\nNote that, it is also possible to create custom encoders and decoders separately by using the `createEncoder` and `createDecoder` functions respectively and then use the `combineCodec` function on them just like we were doing with composed codecs.\n\nThis approach is recommended to library maintainers as it allows their users to tree-shake any of the encoders and/or decoders they don’t need.\n\nHere’s our previous modulo u8 example but split into separate `Encoder`, `Decoder` and `Codec` instances.\n\n```ts\nconst getModuloU8Encoder = () =>\n    createEncoder<number>({\n        fixedSize: 1,\n        write(value, bytes, offset) {\n            bytes.set(value % 256, offset);\n            return offset + 1;\n        },\n    });\n\nconst getModuloU8Decoder = () =>\n    createDecoder<number>({\n        fixedSize: 1,\n        read(bytes, offset) {\n            const value = bytes[offset];\n            return [value, offset + 1];\n        },\n    });\n\nconst getModuloU8Codec = () => combineCodec(getModuloU8Encoder(), getModuloU8Decoder());\n```\n\nHere’s another example returning a `VariableSizeCodec`. This one transforms a simple string composed of characters from `a` to `z` to a buffer of numbers from `1` to `26` where `0` bytes are spaces.\n\n```ts\nconst alphabet = ' abcdefghijklmnopqrstuvwxyz';\n\nconst getCipherEncoder = () =>\n    createEncoder<string>({\n        getSizeFromValue: value => value.length,\n        write(value, bytes, offset) {\n            const bytesToAdd = [...value].map(char => alphabet.indexOf(char));\n            bytes.set(bytesToAdd, offset);\n            return offset + bytesToAdd.length;\n        },\n    });\n\nconst getCipherDecoder = () =>\n    createDecoder<string>({\n        read(bytes, offset) {\n            const value = [...bytes.slice(offset)].map(byte => alphabet.charAt(byte)).join('');\n            return [value, bytes.length];\n        },\n    });\n\nconst getCipherCodec = () => combineCodec(getCipherEncoder(), getCipherDecoder());\n```\n\n## Transforming codecs\n\nIt is possible to transform a `Codec<T>` to a `Codec<U>` by providing two mapping functions: one that goes from `T` to `U` and one that does the opposite.\n\nFor instance, here’s how you would map a `u32` integer into a `string` representation of that number.\n\n```ts\nconst getStringU32Codec = () =>\n    transformCodec(\n        getU32Codec(),\n        (integerAsString: string): number => parseInt(integerAsString),\n        (integer: number): string => integer.toString(),\n    );\n\ngetStringU32Codec().encode('42'); // new Uint8Array([42])\ngetStringU32Codec().decode(new Uint8Array([42])); // \"42\"\n```\n\nIf a `Codec` has [different From and To types](#different-from-and-to-types), say `Codec<OldFrom, OldTo>`, and we want to map it to `Codec<NewFrom, NewTo>`, we must provide functions that map from `NewFrom` to `OldFrom` and from `OldTo` to `NewTo`.\n\nTo illustrate that, let’s take our previous `getStringU32Codec` example but make it use a `getU64Codec` codec instead as it returns a `Codec<number | bigint, bigint>`. Additionally, let’s make it so our `getStringU64Codec` function returns a `Codec<number | string, string>` so that it also accepts numbers when encoding values. Here’s what our mapping functions look like:\n\n```ts\nconst getStringU64Codec = () =>\n    transformCodec(\n        getU64Codec(),\n        (integerInput: number | string): number | bigint =>\n            typeof integerInput === 'string' ? BigInt(integerAsString) : integerInput,\n        (integer: bigint): string => integer.toString(),\n    );\n```\n\nNote that the second function that maps the decoded type is optional. That means, you can omit it to simply update or loosen the type to encode whilst keeping the decoded type the same.\n\nThis is particularly useful to provide default values to object structures. For instance, here’s how we can map our `Person` codec to give a default value to its `age` attribute.\n\n```ts\ntype Person = { name: string; age: number; }\nconst getPersonCodec = (): Codec<Person> => { /*...*/ }\n\ntype PersonInput = { name: string; age?: number; }\nconst getPersonWithDefaultValueCodec = (): Codec<PersonInput, Person> =>\n    transformCodec(\n        getPersonCodec(),\n        (person: PersonInput): Person => { ...person, age: person.age ?? 42 }\n    )\n```\n\nSimilar helpers exist to map `Encoder` and `Decoder` instances allowing you to separate your codec logic into tree-shakeable functions. Here’s our `getStringU32Codec` written that way.\n\n```ts\nconst getStringU32Encoder = () =>\n    transformEncoder(getU32Encoder(), (integerAsString: string): number => parseInt(integerAsString));\nconst getStringU32Decoder = () => transformDecoder(getU32Decoder(), (integer: number): string => integer.toString());\nconst getStringU32Codec = () => combineCodec(getStringU32Encoder(), getStringU32Decoder());\n```\n\n## Fixing the size of codecs\n\nThe `fixCodecSize` function allows you to bind the size of a given codec to the given fixed size.\n\nFor instance, say you want to represent a base-58 string that uses exactly 32 bytes when decoded. Here’s how you can use the `fixCodecSize` helper to achieve that.\n\n```ts\nconst get32BytesBase58Codec = () => fixCodecSize(getBase58Codec(), 32);\n```\n\nYou may also use the `fixEncoderSize` and `fixDecoderSize` functions to separate your codec logic like so:\n\n```ts\nconst get32BytesBase58Encoder = () => fixEncoderSize(getBase58Encoder(), 32);\nconst get32BytesBase58Decoder = () => fixDecoderSize(getBase58Decoder(), 32);\nconst get32BytesBase58Codec = () => combineCodec(get32BytesBase58Encoder(), get32BytesBase58Decoder());\n```\n\n## Prefixing codecs with their size\n\nThe `addCodecSizePrefix` function allows you to store the byte size of any codec as a number prefix. This allows you to contain variable-size codecs to their actual size.\n\nWhen encoding, the size of the encoded data is stored before the encoded data itself. When decoding, the size is read first to know how many bytes to read next.\n\nFor example, say we want to represent a variable-size base-58 string using a `u32` size prefix. Here’s how you can use the `addCodecSizePrefix` function to achieve that.\n\n```ts\nconst getU32Base58Codec = () => addCodecSizePrefix(getBase58Codec(), getU32Codec());\n\ngetU32Base58Codec().encode('hello world');\n// 0x0b00000068656c6c6f20776f726c64\n//   |       └-- Our encoded base-58 string.\n//   └-- Our encoded u32 size prefix.\n```\n\nYou may also use the `addEncoderSizePrefix` and `addDecoderSizePrefix` functions to separate your codec logic like so:\n\n```ts\nconst getU32Base58Encoder = () => addEncoderSizePrefix(getBase58Encoder(), getU32Encoder());\nconst getU32Base58Decoder = () => addDecoderSizePrefix(getBase58Decoder(), getU32Decoder());\nconst getU32Base58Codec = () => combineCodec(getU32Base58Encoder(), getU32Base58Decoder());\n```\n\n## Adding sentinels to codecs\n\nAnother way of delimiting the size of a codec is to use sentinels. The `addCodecSentinel` function allows us to add a sentinel to the end of the encoded data and to read until that sentinel is found when decoding. It accepts any codec and a `Uint8Array` sentinel responsible for delimiting the encoded data.\n\n```ts\nconst codec = addCodecSentinel(getUtf8Codec(), new Uint8Array([255, 255]));\ncodec.encode('hello');\n// 0x68656c6c6fffff\n//   |        └-- Our sentinel.\n//   └-- Our encoded string.\n```\n\nNote that the sentinel _must not_ be present in the encoded data and _must_ be present in the decoded data for this to work. If this is not the case, dedicated errors will be thrown.\n\n```ts\nconst sentinel = new Uint8Array([108, 108]); // 'll'\nconst codec = addCodecSentinel(getUtf8Codec(), sentinel);\n\ncodec.encode('hello'); // Throws: sentinel is in encoded data.\ncodec.decode(new Uint8Array([1, 2, 3])); // Throws: sentinel missing in decoded data.\n```\n\nSeparate `addEncoderSentinel` and `addDecoderSentinel` functions are also available.\n\n```ts\nconst bytes = addEncoderSentinel(getUtf8Encoder(), sentinel).encode('hello');\nconst value = addDecoderSentinel(getUtf8Decoder(), sentinel).decode(bytes);\n```\n\n## Adjusting the size of codecs\n\nThe `resizeCodec` helper re-defines the size of a given codec by accepting a function that takes the current size of the codec and returns a new size. This works for both fixed-size and variable-size codecs.\n\n```ts\n// Fixed-size codec.\nconst getBiggerU32Codec = () => resizeCodec(getU32Codec(), size => size + 4);\ngetBiggerU32Codec().encode(42);\n// 0x2a00000000000000\n//   |       └-- Empty buffer space caused by the resizeCodec function.\n//   └-- Our encoded u32 number.\n\n// Variable-size codec.\nconst getBiggerUtf8Codec = () => resizeCodec(getUtf8Codec(), size => size + 4);\ngetBiggerUtf8Codec().encode('ABC');\n// 0x41424300000000\n//   |     └-- Empty buffer space caused by the resizeCodec function.\n//   └-- Our encoded string.\n```\n\nNote that the `resizeCodec` function doesn't change any encoded or decoded bytes, it merely tells the `encode` and `decode` functions how big the `Uint8Array` should be before delegating to their respective `write` and `read` functions. In fact, this is completely bypassed when using the `write` and `read` functions directly. For instance:\n\n```ts\nconst getBiggerU32Codec = () => resizeCodec(getU32Codec(), size => size + 4);\n\n// Using the encode function.\ngetBiggerU32Codec().encode(42);\n// 0x2a00000000000000\n\n// Using the lower-level write function.\nconst myCustomBytes = new Uint8Array(4);\ngetBiggerU32Codec().write(42, myCustomBytes, 0);\n// 0x2a000000\n```\n\nSo when would it make sense to use the `resizeCodec` function? This function is particularly useful when combined with the `offsetCodec` function described below. Whilst the `offsetCodec` may help us push the offset forward — e.g. to skip some padding — it won't change the size of the encoded data which means the last bytes will be truncated by how much we pushed the offset forward. The `resizeCodec` function can be used to fix that. For instance, here's how we can use the `resizeCodec` and the `offsetCodec` functions together to create a struct codec that includes some padding.\n\n```ts\nconst personCodec = getStructCodec([\n    ['name', fixCodecSize(getUtf8Codec(), 8)],\n    // There is a 4-byte padding between name and age.\n    [\n        'age',\n        offsetCodec(\n            resizeCodec(getU32Codec(), size => size + 4),\n            { preOffset: ({ preOffset }) => preOffset + 4 },\n        ),\n    ],\n]);\n\npersonCodec.encode({ name: 'Alice', age: 42 });\n// 0x416c696365000000000000002a000000\n//   |               |       └-- Our encoded u32 (42).\n//   |               └-- The 4-bytes of padding we are skipping.\n//   └-- Our 8-byte encoded string (\"Alice\").\n```\n\nAs usual, the `resizeEncoder` and `resizeDecoder` functions can also be used to achieve that.\n\n```ts\nconst getBiggerU32Encoder = () => resizeEncoder(getU32Codec(), size => size + 4);\nconst getBiggerU32Decoder = () => resizeDecoder(getU32Codec(), size => size + 4);\nconst getBiggerU32Codec = () => combineCodec(getBiggerU32Encoder(), getBiggerU32Decoder());\n```\n\n## Offsetting codecs\n\nThe `offsetCodec` function is a powerful codec primitive that allows you to move the offset of a given codec forward or backwards. It accepts one or two functions that takes the current offset and returns a new offset.\n\nTo understand how this works, let's take our previous `biggerU32Codec` example which encodes a `u32` number inside an 8-byte buffer.\n\n```ts\nconst biggerU32Codec = resizeCodec(getU32Codec(), size => size + 4);\nbiggerU32Codec.encode(0xffffffff);\n// 0xffffffff00000000\n//   |       └-- Empty buffer space caused by the resizeCodec function.\n//   └-- Our encoded u32 number.\n```\n\nNow, let's say we want to move the offset of that codec 2 bytes forward so that the encoded number sits in the middle of the buffer. To achieve, this we can use the `offsetCodec` helper and provide a `preOffset` function that moves the \"pre-offset\" of the codec 2 bytes forward.\n\n```ts\nconst u32InTheMiddleCodec = offsetCodec(biggerU32Codec, {\n    preOffset: ({ preOffset }) => preOffset + 2,\n});\nu32InTheMiddleCodec.encode(0xffffffff);\n// 0x0000ffffffff0000\n//       └-- Our encoded u32 number is now in the middle of the buffer.\n```\n\nWe refer to this offset as the \"pre-offset\" because, once the inner codec is encoded or decoded, an additional offset will be returned which we refer to as the \"post-offset\". That \"post-offset\" is important as, unless we are reaching the end of our codec, it will be used by any further codecs to continue encoding or decoding data.\n\nBy default, that \"post-offset\" is simply the addition of the \"pre-offset\" and the size of the encoded or decoded inner data.\n\n```ts\nconst u32InTheMiddleCodec = offsetCodec(biggerU32Codec, {\n    preOffset: ({ preOffset }) => preOffset + 2,\n});\nu32InTheMiddleCodec.encode(0xffffffff);\n// 0x0000ffffffff0000\n//   |   |       └-- Post-offset.\n//   |   └-- New pre-offset: The original pre-offset + 2.\n//   └-- Pre-offset: The original pre-offset before we adjusted it.\n```\n\nHowever, you may also provide a `postOffset` function to adjust the \"post-offset\". For instance, let's push the \"post-offset\" 2 bytes forward as well such that any further codecs will start doing their job at the end of our 8-byte `u32` number.\n\n```ts\nconst u32InTheMiddleCodec = offsetCodec(biggerU32Codec, {\n    preOffset: ({ preOffset }) => preOffset + 2,\n    postOffset: ({ postOffset }) => postOffset + 2,\n});\nu32InTheMiddleCodec.encode(0xffffffff);\n// 0x0000ffffffff0000\n//   |   |       |   └-- New post-offset: The original post-offset + 2.\n//   |   |       └-- Post-offset: The original post-offset before we adjusted it.\n//   |   └-- New pre-offset: The original pre-offset + 2.\n//   └-- Pre-offset: The original pre-offset before we adjusted it.\n```\n\nBoth the `preOffset` and `postOffset` functions offer the following attributes:\n\n- `bytes`: The entire byte array being encoded or decoded.\n- `preOffset`: The original and unaltered pre-offset.\n- `wrapBytes`: A helper function that wraps the given offset around the byte array length. E.g. `wrapBytes(-1)` will refer to the last byte of the byte array.\n\nAdditionally, the post-offset function also provides the following attributes:\n\n- `newPreOffset`: The new pre-offset after the pre-offset function has been applied.\n- `postOffset`: The original and unaltered post-offset.\n\nNote that you may also decide to ignore these attributes to achieve absolute offsets. However, relative offsets are usually recommended as they won't break your codecs when composed with other codecs.\n\n```ts\nconst u32InTheMiddleCodec = offsetCodec(biggerU32Codec, {\n    preOffset: () => 2,\n    postOffset: () => 8,\n});\nu32InTheMiddleCodec.encode(0xffffffff);\n// 0x0000ffffffff0000\n```\n\nAlso note that any negative offset or offset that exceeds the size of the byte array will throw a `AtlasError` of code `SOLANA_ERROR__CODECS__OFFSET_OUT_OF_RANGE`.\n\n```ts\nconst u32InTheEndCodec = offsetCodec(biggerU32Codec, { preOffset: () => -4 });\nu32InTheEndCodec.encode(0xffffffff);\n// throws new AtlasError(SOLANA_ERROR__CODECS__OFFSET_OUT_OF_RANGE)\n```\n\nTo avoid this, you may use the `wrapBytes` function to wrap the offset around the byte array length. For instance, here's how we can use the `wrapBytes` function to move the pre-offset 4 bytes from the end of the byte array.\n\n```ts\nconst u32InTheEndCodec = offsetCodec(biggerU32Codec, {\n    preOffset: ({ wrapBytes }) => wrapBytes(-4),\n});\nu32InTheEndCodec.encode(0xffffffff);\n// 0x00000000ffffffff\n```\n\nAs you can see, the `offsetCodec` helper allows you to jump all over the place with your codecs. This non-linear approach to encoding and decoding data allows you to achieve complex serialization strategies that would otherwise be impossible.\n\nAs usual, the `offsetEncoder` and `offsetDecoder` functions can also be used to split your codec logic into tree-shakeable functions.\n\n```ts\nconst getU32InTheMiddleEncoder = () => offsetEncoder(biggerU32Encoder, { preOffset: ({ preOffset }) => preOffset + 2 });\nconst getU32InTheMiddleDecoder = () => offsetDecoder(biggerU32Decoder, { preOffset: ({ preOffset }) => preOffset + 2 });\nconst getU32InTheMiddleCodec = () => combineCodec(getU32InTheMiddleEncoder(), getU32InTheMiddleDecoder());\n```\n\n## Padding codecs\n\nThe `padLeftCodec` and `padRightCodec` helpers can be used to add padding to the left or right of a given codec. They accept an `offset` number that tells us how big the padding should be.\n\n```ts\nconst getLeftPaddedCodec = () => padLeftCodec(getU16Codec(), 4);\ngetLeftPaddedCodec().encode(0xffff);\n// 0x00000000ffff\n//   |       └-- Our encoded u16 number.\n//   └-- Our 4-byte padding.\n\nconst getRightPaddedCodec = () => padRightCodec(getU16Codec(), 4);\ngetRightPaddedCodec().encode(0xffff);\n// 0xffff00000000\n//   |   └-- Our 4-byte padding.\n//   └-- Our encoded u16 number.\n```\n\nNote that both the `padLeftCodec` and `padRightCodec` functions are simple wrappers around the `offsetCodec` and `resizeCodec` functions. For more complex padding strategies, you may want to use the `offsetCodec` and `resizeCodec` functions directly instead.\n\nAs usual, encoder-only and decoder-only helpers are available for these padding functions. Namely, `padLeftEncoder`, `padRightEncoder`, `padLeftDecoder` and `padRightDecoder`.\n\n```ts\nconst getMyPaddedEncoder = () => padLeftEncoder(getU16Encoder());\nconst getMyPaddedDecoder = () => padLeftDecoder(getU16Decoder());\nconst getMyPaddedCodec = () => combineCodec(getMyPaddedEncoder(), getMyPaddedDecoder());\n```\n\n## Reversing codecs\n\nThe `reverseCodec` helper reverses the bytes of the provided `FixedSizeCodec`.\n\n```ts\nconst getBigEndianU64Codec = () => reverseCodec(getU64Codec());\n```\n\nNote that number codecs can already do that for you via their `endian` option.\n\n```ts\nconst getBigEndianU64Codec = () => getU64Codec({ endian: Endian.Big });\n```\n\nAs usual, the `reverseEncoder` and `reverseDecoder` functions can also be used to achieve that.\n\n```ts\nconst getBigEndianU64Encoder = () => reverseEncoder(getU64Encoder());\nconst getBigEndianU64Decoder = () => reverseDecoder(getU64Decoder());\nconst getBigEndianU64Codec = () => combineCodec(getBigEndianU64Encoder(), getBigEndianU64Decoder());\n```\n\n## Byte helpers\n\nThis package also provides utility functions for managing bytes such as:\n\n- `mergeBytes`: Concatenates an array of `Uint8Arrays` into a single `Uint8Array`.\n- `padBytes`: Pads a `Uint8Array` with zeroes (to the right) to the specified length.\n- `fixBytes`: Pads or truncates a `Uint8Array` so it has the specified length.\n- `containsBytes`: Checks if a `Uint8Array` contains another `Uint8Array` at a given offset.\n\n```ts\n// Merge multiple Uint8Array buffers into one.\nmergeBytes([new Uint8Array([1, 2]), new Uint8Array([3, 4])]); // Uint8Array([1, 2, 3, 4])\n\n// Pad a Uint8Array buffer to the given size.\npadBytes(new Uint8Array([1, 2]), 4); // Uint8Array([1, 2, 0, 0])\npadBytes(new Uint8Array([1, 2, 3, 4]), 2); // Uint8Array([1, 2, 3, 4])\n\n// Pad and truncate a Uint8Array buffer to the given size.\nfixBytes(new Uint8Array([1, 2]), 4); // Uint8Array([1, 2, 0, 0])\nfixBytes(new Uint8Array([1, 2, 3, 4]), 2); // Uint8Array([1, 2])\n\n// Check if a Uint8Array contains another Uint8Array at a given offset.\ncontainsBytes(new Uint8Array([1, 2, 3, 4]), new Uint8Array([2, 3]), 1); // true\ncontainsBytes(new Uint8Array([1, 2, 3, 4]), new Uint8Array([2, 3]), 2); // false\n```\n\n---\n\nTo read more about the available codecs and how to use them, check out the documentation of the main [`@atlas/codecs` package](https://github.com/anza-xyz/kit/tree/main/packages/codecs).\n","readmeFilename":"README.md","_rev":"1-d09809b63136d00a68687cbfd807a85a"}