{"_id":"@atlaschain/codecs-numbers","name":"@atlaschain/codecs-numbers","dist-tags":{"latest":"3.0.0"},"versions":{"3.0.0":{"name":"@atlaschain/codecs-numbers","version":"3.0.0","description":"Codecs for numbers of different sizes and endianness","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":{"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/codecs-core":"workspace:*","@atlaschain/errors":"workspace:*"},"peerDependencies":{"typescript":">=5.3.3"},"engines":{"node":">=20.18.0"},"_id":"@atlaschain/codecs-numbers@3.0.0","homepage":"https://github.com/anza-xyz/kit#readme","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-biBjF8g0PfxT0kyZSunxMaa4IcOsIjHkfVIxYlwFg2pIZZSyVCxMnNmk/+tHuJdf6kpglkqXNm+PV+mpwPWLmQ==","shasum":"6a1644f71419269a75c3adf6239ec2fe16c145b2","tarball":"https://registry.npmjs.org/@atlaschain/codecs-numbers/-/codecs-numbers-3.0.0.tgz","fileCount":5,"unpackedSize":18025,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCQOtIhiRkkkY/arvEEm7wBJoqjky8sSpA1nhXoY5qoQAIgVLW6a6b3zkSCZ1AZ/X5udjx+d+4z1raNriT6oLExVNk="}]},"_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-numbers_3.0.0_1756885180018_0.08138457976774194"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-03T07:39:39.922Z","3.0.0":"2025-09-03T07:39:40.201Z","modified":"2025-09-03T07:39:40.513Z"},"maintainers":[{"name":"atlaschain","email":"jq@atlaschain.org"}],"description":"Codecs for numbers of different sizes and endianness","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-numbers?style=flat\n[npm-image]: https://img.shields.io/npm/v/@atlas/codecs-numbers?style=flat\n[npm-url]: https://www.npmjs.com/package/@atlas/codecs-numbers\n\n# @atlas/codecs-numbers\n\nThis package contains codecs for numbers of different sizes and endianness. 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## Integer codecs\n\nThis package provides ten codecs of five different byte sizes for integers. Five of them store unsigned integers and the other five store signed integers.\n\n```ts\n// Unsigned integers.\ngetU8Codec().encode(42); // 0x2a\ngetU16Codec().encode(42); // 0x2a00\ngetU32Codec().encode(42); // 0x2a000000\ngetU64Codec().encode(42); // 0x2a00000000000000\ngetU128Codec().encode(42); // 0x2a000000000000000000000000000000\n\n// Signed integers.\ngetI8Codec().encode(-42); // 0xd6\ngetI16Codec().encode(-42); // 0xd6ff\ngetI32Codec().encode(-42); // 0xd6ffffff\ngetI64Codec().encode(-42); // 0xd6ffffffffffffff\ngetI128Codec().encode(-42); // 0xd6ffffffffffffffffffffffffffffff\n```\n\nBy default, integers are stored using little endianness but you may change this behaviour via the `endian` option. This option is available for every codec that uses more than a single byte.\n\n```ts\n// Big-endian unsigned integers.\ngetU16Codec({ endian: Endian.Big }).encode(42); // 0x002a\ngetU32Codec({ endian: Endian.Big }).encode(42); // 0x0000002a\ngetU64Codec({ endian: Endian.Big }).encode(42); // 0x000000000000002a\ngetU128Codec({ endian: Endian.Big }).encode(42); // 0x0000000000000000000000000000002a\n\n// Big-endian signed integers.\ngetI16Codec({ endian: Endian.Big }).encode(-42); // 0xffd6\ngetI32Codec({ endian: Endian.Big }).encode(-42); // 0xffffffd6\ngetI64Codec({ endian: Endian.Big }).encode(-42); // 0xffffffffffffffd6\ngetI128Codec({ endian: Endian.Big }).encode(-42); // 0xffffffffffffffffffffffffffffffd6\n```\n\nAll integer codecs are of type `Codec<number>` except for the `u64`, `u128`, `i64` and `i128` codecs which are of type `Codec<number | bigint, bigint>`. This means we can provide either a `number` of a `bigint` value to encode but the decoded value will always be a `bigint`. This is because JavaScript's native `number` type does not support numbers larger than `2^53 - 1` and these large integer codecs have the potential to go over that value.\n\n```ts\nconst bytesFromNumber = getU64Codec().encode(42);\ngetU64Codec().decode(bytesFromNumber); // BigInt(42)\n\n// OR\nconst bytesFromBigInt = getU64Codec().encode(BigInt(42));\ngetU64Codec().decode(bytesFromBigInt); // BigInt(42)\n```\n\nFinally, for each of these `get*Codec` functions, separate `get*Encoder` and `get*Decoder` functions exist to focus on only one side of the serialization and tree-shake the rest of the functions away.\n\n```ts\nconst bytes = getU8Encoder().encode(42);\nconst value = getU8Decoder().decode(bytes);\n```\n\n## Decimal number codecs\n\nThis package also provides two codecs for floating numbers. One using 32 bits and one using 64 bits.\n\n```ts\ngetF32Codec().encode(-1.5); // 0x0000c0bf\ngetF64Codec().encode(-1.5); // 0x000000000000f8bf\n```\n\nSimilarly to the integer codecs, they are stored in little-endian by default but may be stored in big-endian using the `endian` option.\n\n```ts\ngetF32Codec({ endian: Endian.Big }).encode(-1.5); // 0xbfc00000\ngetF64Codec({ endian: Endian.Big }).encode(-1.5); // 0xbff8000000000000\n```\n\nNote that based on the selected codec, some of the precision of the number you are encoding may be lost when decoding it. For instance, when storing `3.1415` using a `f32` codec, you will not get the exact same number back.\n\n```ts\nconst bytes = getF32Codec().encode(3.1415); // 0x560e4940\nconst value = getF32Codec().decode(bytes); // 3.1414999961853027 !== 3.1415\n```\n\nAs usual, separate encoder and decoder functions are available for these codecs.\n\n```ts\ngetF32Encoder().encode(-1.5);\ngetF32Decoder().decode(new Uint8Array([...]));\n\ngetF64Encoder().encode(-1.5);\ngetF64Decoder().decode(new Uint8Array([...]));\n```\n\n## Short u16 codec\n\nThis last integer codec is less common `VariableSizeCodec` that stores an unsigned integer using between 1 to 3 bytes depending on the value of that integer.\n\n```ts\nconst bytes = getShortU16Codec().encode(42); // 0x2a\nconst value = getShortU16Codec().decode(bytes); // 42\n```\n\nIf the provided integer is equal to or lower than `0x7f`, it will be stored as-is, using a single byte. However, if the integer is above `0x7f`, then the top bit is set and the remaining value is stored in the next bytes. Each byte follows the same pattern until the third byte. The third byte, if needed, uses all 8 bits to store the last byte of the original value.\n\nIn other words, this codec provides an extendable size that adapts based on the integer. In the illustration below, you can see the `0` and `1` byte flags for each scenario as well as the available bits to store the integer marked with `X`.\n\n```\n0XXXXXXX <- From 0 to 127.\n1XXXXXXX 0XXXXXXX <- From 128 to 16,383.\n1XXXXXXX 1XXXXXXX XXXXXXXX <- From 16,384 to 4,194,303.\n```\n\nThis codec is mainly used internally when encoding and decoding Atlas transactions.\n\nSeparate encoder and decoder functions are also available via `getShortU16Encoder` and `getShortU16Decoder` respectively.\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-7d7b0ef013bba4549db4150c578446b3"}