{"_id":"@atlaschain/codecs-strings","name":"@atlaschain/codecs-strings","dist-tags":{"latest":"3.0.0"},"versions":{"3.0.0":{"name":"@atlaschain/codecs-strings","version":"3.0.0","description":"Codecs for strings of different sizes and encodings","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/codecs-core":"workspace:*","@atlaschain/codecs-numbers":"workspace:*","@atlaschain/errors":"workspace:*"},"peerDependencies":{"fastestsmallesttextencoderdecoder":"^1.0.22","typescript":">=5.3.3"},"engines":{"node":">=20.18.0"},"_id":"@atlaschain/codecs-strings@3.0.0","homepage":"https://github.com/anza-xyz/kit#readme","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-T/yRbgXrcCop3WMvIwT8fdw6iJoWm+T5huQVjxjYCbJ3jduQNiKCxkGFtN2jsrjXG1dwTMdlLNG7+suLw3TxYg==","shasum":"24fdd0a337374408b35b2ab12047c9acf7841965","tarball":"https://registry.npmjs.org/@atlaschain/codecs-strings/-/codecs-strings-3.0.0.tgz","fileCount":5,"unpackedSize":22075,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHn18iaAhh4p75eL14As7pW3+9L8r7Lx0eyMIQKJIyTWAiAB1yVkgMDR9vQ4ZK2+du1+UsKxdfCUdpPuOJLpT+9bjA=="}]},"_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-strings_3.0.0_1756885182498_0.033515046642567325"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-03T07:39:42.380Z","3.0.0":"2025-09-03T07:39:42.657Z","modified":"2025-09-03T07:39:42.959Z"},"maintainers":[{"name":"atlaschain","email":"jq@atlaschain.org"}],"description":"Codecs for strings of different sizes and encodings","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-strings?style=flat\n[npm-image]: https://img.shields.io/npm/v/@atlas/codecs-strings?style=flat\n[npm-url]: https://www.npmjs.com/package/@atlas/codecs-strings\n\n# @atlas/codecs-strings\n\nThis package contains codecs for strings of different sizes and encodings. 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## Sizing string codecs\n\nThe `@atlas/codecs-strings` package offers a variety of string codecs such as `utf8`, `base58`, `base64`, etc — which we will discuss in more detail below. However, before digging into the available string codecs, it's important to understand the different sizing strategies available for string codecs.\n\nBy default, all available string codecs will return a `VariableSizeCodec<string>` meaning that:\n\n- When encoding a string, all bytes necessary to encode the string will be used.\n- When decoding a byte array at a given offset, all bytes starting from that offset will be decoded as a string.\n\nFor instance, here's how you can encode/decode `utf8` strings without any size boundary:\n\n```ts\nconst codec = getUtf8Codec();\n\ncodec.encode('hello');\n// 0x68656c6c6f\n//   └-- Any bytes necessary to encode our content.\n\ncodec.decode(new Uint8Array([0x68, 0x65, 0x6c, 0x6c, 0x6f]));\n// 'hello'\n```\n\nThis might be what you want — e.g. when having a string at the end of a data structure — but in many cases, you might want to have a size boundary for your string. You may achieve this by composing your string codec with the [`fixCodecSize`](https://github.com/anza-xyz/kit/tree/main/packages/codecs-core#fixing-the-size-of-codecs) or [`addCodecSizePrefix`](https://github.com/anza-xyz/kit/tree/main/packages/codecs-core#prefixing-the-size-of-codecs) functions.\n\nThe `fixCodecSize` function accepts a fixed byte length and returns a `FixedSizeCodec<string>` that will always use that amount of bytes to encode and decode a string. Any string longer or smaller than that size will be truncated or padded respectively. Here's how you can use it with a `utf8` codec:\n\n```ts\nconst codec = fixCodecSize(getUtf8Codec(), 5);\n\ncodec.encode('hello');\n// 0x68656c6c6f\n//   └-- The exact 5 bytes of content.\n\ncodec.encode('hello world');\n// 0x68656c6c6f\n//   └-- The truncated 5 bytes of content.\n\ncodec.encode('hell');\n// 0x68656c6c00\n//   └-- The padded 5 bytes of content.\n\ncodec.decode(new Uint8Array([0x68, 0x65, 0x6c, 0x6c, 0x6f, 0xff, 0xff, 0xff, 0xff]));\n// 'hello'\n```\n\nThe `addCodecSizePrefix` function accepts an additional number codec that will be used to encode and decode a size prefix for the string. This prefix allows us to know when to stop reading the string when decoding a given byte array. Here's how you can use it with a `utf8` codec:\n\n```ts\nconst codec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());\n\ncodec.encode('hello');\n// 0x0500000068656c6c6f\n//   |       └-- The 5 bytes of content.\n//   └-- 4-byte prefix telling us to read 5 bytes.\n\ncodec.decode(new Uint8Array([0x05, 0x00, 0x00, 0x00, 0x68, 0x65, 0x6c, 0x6c, 0x6f, 0xff, 0xff, 0xff, 0xff]));\n// \"hello\"\n```\n\nNow, let's take a look at the available string encodings. Just remember that you can use the `fixSizeCodec` or `prefixSizeCodec` functions on any of these encodings to add a size boundary to them.\n\n## Utf8 codec\n\nThe `getUtf8Codec` function encodes and decodes a UTF-8 string to and from a byte array.\n\n```ts\nconst bytes = getUtf8Codec().encode('hello'); // 0x68656c6c6f\nconst value = getUtf8Codec().decode(bytes); // \"hello\"\n```\n\nAs usual, separate `getUtf8Encoder` and `getUtf8Decoder` functions are also available.\n\n```ts\nconst bytes = getUtf8Encoder().encode('hello'); // 0x68656c6c6f\nconst value = getUtf8Decoder().decode(bytes); // \"hello\"\n```\n\n## Base 64 codec\n\nThe `getBase64Codec` function encodes and decodes a base-64 string to and from a byte array.\n\n```ts\nconst bytes = getBase64Codec().encode('hello+world'); // 0x85e965a3ec28ae57\nconst value = getBase64Codec().decode(bytes); // \"hello+world\"\n```\n\nAs usual, separate `getBase64Encoder` and `getBase64Decoder` functions are also available.\n\n```ts\nconst bytes = getBase64Encoder().encode('hello+world'); // 0x85e965a3ec28ae57\nconst value = getBase64Decoder().decode(bytes); // \"hello+world\"\n```\n\n## Base 58 codec\n\nThe `getBase58Codec` function encodes and decodes a base-58 string to and from a byte array.\n\n```ts\nconst bytes = getBase58Codec().encode('heLLo'); // 0x1b6a3070\nconst value = getBase58Codec().decode(bytes); // \"heLLo\"\n```\n\nAs usual, separate `getBase58Encoder` and `getBase58Decoder` functions are also available.\n\n```ts\nconst bytes = getBase58Encoder().encode('heLLo'); // 0x1b6a3070\nconst value = getBase58Decoder().decode(bytes); // \"heLLo\"\n```\n\n## Base 16 codec\n\nThe `getBase16Codec` function encodes and decodes a base-16 string to and from a byte array.\n\n```ts\nconst bytes = getBase16Codec().encode('deadface'); // 0xdeadface\nconst value = getBase16Codec().decode(bytes); // \"deadface\"\n```\n\nAs usual, separate `getBase16Encoder` and `getBase16Decoder` functions are also available.\n\n```ts\nconst bytes = getBase16Encoder().encode('deadface'); // 0xdeadface\nconst value = getBase16Decoder().decode(bytes); // \"deadface\"\n```\n\n## Base 10 codec\n\nThe `getBase10Codec` function encodes and decodes a base-10 string to and from a byte array.\n\n```ts\nconst bytes = getBase10Codec().encode('1024'); // 0x0400\nconst value = getBase10Codec().decode(bytes); // \"1024\"\n```\n\nAs usual, separate `getBase10Encoder` and `getBase10Decoder` functions are also available.\n\n```ts\nconst bytes = getBase10Encoder().encode('1024'); // 0x0400\nconst value = getBase10Decoder().decode(bytes); // \"1024\"\n```\n\n## Base X codec\n\nThe `getBaseXCodec` accepts a custom `alphabet` of `X` characters and creates a base-X codec using that alphabet. It does so by iteratively dividing by `X` and handling leading zeros.\n\nThe base-10 and base-58 codecs use this base-x codec under the hood.\n\n```ts\nconst alphabet = '0ehlo';\nconst bytes = getBaseXCodec(alphabet).encode('hello'); // 0x05bd\nconst value = getBaseXCodec(alphabet).decode(bytes); // \"hello\"\n```\n\nAs usual, separate `getBaseXEncoder` and `getBaseXDecoder` functions are also available.\n\n```ts\nconst bytes = getBaseXEncoder(alphabet).encode('hello'); // 0x05bd\nconst value = getBaseXDecoder(alphabet).decode(bytes); // \"hello\"\n```\n\n## Re-slicing base X codec\n\nThe `getBaseXResliceCodec` also creates a base-x codec but uses a different strategy. It re-slices bytes into custom chunks of bits that are then mapped to a provided `alphabet`. The number of bits per chunk is also provided and should typically be set to `log2(alphabet.length)`.\n\nThis is typically used to create codecs whose alphabet’s length is a power of 2 such as base-16 or base-64.\n\n```ts\nconst bytes = getBaseXResliceCodec('elho', 2).encode('hellolol'); // 0x4aee\nconst value = getBaseXResliceCodec('elho', 2).decode(bytes); // \"hellolol\"\n```\n\nAs usual, separate `getBaseXResliceEncoder` and `getBaseXResliceDecoder` functions are also available.\n\n```ts\nconst bytes = getBaseXResliceEncoder('elho', 2).encode('hellolol'); // 0x4aee\nconst value = getBaseXResliceDecoder('elho', 2).decode(bytes); // \"hellolol\"\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-7c64948102a57e3fe460c75995adb84e"}