{"_id":"@atlaschain/nominal-types","_rev":"2-b30744707b8391ba038020f45b74a9cb","name":"@atlaschain/nominal-types","dist-tags":{"latest":"3.0.1"},"versions":{"3.0.0":{"name":"@atlaschain/nominal-types","version":"3.0.0","keywords":["blockchain","atlas","web3"],"author":{"name":"Atlas Chain Foundation"},"license":"MIT","_id":"@atlaschain/nominal-types@3.0.0","maintainers":[{"name":"atlaschain","email":"jq@atlaschain.org"}],"homepage":"https://github.com/anza-xyz/kit#readme","bugs":{"url":"https://github.com/anza-xyz/kit/issues"},"dist":{"shasum":"86f7bd476d352e96129c7e85f871c2b21beaaacc","tarball":"https://registry.npmjs.org/@atlaschain/nominal-types/-/nominal-types-3.0.0.tgz","fileCount":4,"integrity":"sha512-a1YUgdeVzQzsbbALVnHhS98v/iMkehLNSo0mbbr/qBM54+tT1BvBm0vxizpm4ZcPRDZ9rbXiMwAjEDBLUgwqBg==","signatures":[{"sig":"MEUCIHNFaVAoVqCNXB0uWTC7+4EobtN10RWin5lDmYFObxx9AiEAtEiuYy0ENXTUi3nX5CBVuF+aFhuMXqi6LJzpNqFNSD0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":11056},"type":"commonjs","types":"./dist/types/index.d.ts","engines":{"node":">=20.18.0"},"scripts":{"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","compile:docs":"typedoc","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))","test:prettier":"TERM_OVERRIDE=\"${TURBO_HASH:+dumb}\" TERM=${TERM_OVERRIDE:-$TERM} jest -c ../../node_modules/@atlas/test-config/jest-prettier.config.ts --rootDir . --silent","prepublishOnly":"pnpm pkg delete devDependencies","test:typecheck":"tsc --noEmit","compile:typedefs":"tsc -p ./tsconfig.declarations.json","publish-packages":"pnpm prepublishOnly && pnpm publish-impl"},"_npmUser":{"name":"atlaschain","email":"jq@atlaschain.org"},"repository":{"url":"git+https://github.com/anza-xyz/kit.git","type":"git"},"_npmVersion":"10.9.0","description":"Type utilties for creating nominal/branded types in TypeScript","directories":{},"sideEffects":false,"_nodeVersion":"22.12.0","browserslist":["supports bigint and not dead","maintained node versions"],"_hasShrinkwrap":false,"peerDependencies":{"typescript":">=5.3.3"},"_npmOperationalInternal":{"tmp":"tmp/nominal-types_3.0.0_1756885029172_0.5382559960893751","host":"s3://npm-registry-packages-npm-production"}},"3.0.1":{"name":"@atlaschain/nominal-types","version":"3.0.1","description":"Type utilties for creating nominal/branded types in TypeScript","types":"./dist/types/index.d.ts","type":"commonjs","sideEffects":false,"keywords":["blockchain","atlas","web3"],"scripts":{"compile:docs":"typedoc","compile:typedefs":"tsc -p ./tsconfig.declarations.json","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/@atlaschain/test-config/jest-lint.config.ts --rootDir . --silent","test:prettier":"TERM_OVERRIDE=\"${TURBO_HASH:+dumb}\" TERM=${TERM_OVERRIDE:-$TERM} jest -c ../../node_modules/@atlaschain/test-config/jest-prettier.config.ts --rootDir . --silent","test:typecheck":"tsc --noEmit"},"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"],"peerDependencies":{"typescript":">=5.3.3"},"engines":{"node":">=20.18.0"},"_id":"@atlaschain/nominal-types@3.0.1","homepage":"https://github.com/anza-xyz/kit#readme","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-lBHC1nBe042wOYrzZ86v3Y/UgBGrey9rdMxt8+gZx919uD4f9x6QJLxONK8SB5+9N5q16aJ/FICKvM6hcdPV4A==","shasum":"9333b1c6a780192efa7435be9953c068e1510325","tarball":"https://registry.npmjs.org/@atlaschain/nominal-types/-/nominal-types-3.0.1.tgz","fileCount":4,"unpackedSize":11066,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEjeif3DRMGaOqVrjDPHpLFJwWO3S8CxaGAaXkOQ8UZEAiEAtpUDa7LeSfuN2Dai8YoDS2DDPaqKOXXvKq+cNGin74M="}]},"_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/nominal-types_3.0.1_1756897857868_0.46634079168845455"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-03T07:37:09.092Z","modified":"2025-09-03T11:10:58.270Z","3.0.0":"2025-09-03T07:37:09.362Z","3.0.1":"2025-09-03T11:10:58.069Z"},"bugs":{"url":"https://github.com/anza-xyz/kit/issues"},"author":{"name":"Atlas Chain Foundation"},"license":"MIT","homepage":"https://github.com/anza-xyz/kit#readme","keywords":["blockchain","atlas","web3"],"repository":{"type":"git","url":"git+https://github.com/anza-xyz/kit.git"},"description":"Type utilties for creating nominal/branded types in TypeScript","maintainers":[{"name":"atlaschain","email":"jq@atlaschain.org"}],"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/nominal-types?style=flat\n[npm-image]: https://img.shields.io/npm/v/@atlas/nominal-types?style=flat\n[npm-url]: https://www.npmjs.com/package/@atlas/nominal-types\n\n# @atlas/nominal-types\n\nThis package contains type utilities for creating nominal types in TypeScript.\n\n## Brands make otherwise equal values distinct at the type level\n\nUse the `Brand` utility to produce a new type that satisfies the original type, but not the other way around. That is to say, the branded type is acceptable wherever the original type is specified, but wherever the branded type is specified, the original type will be insufficient.\n\nYou can use this to create specialized instances of strings, numbers, objects, and more which you would like to assert are special in some way (eg. numbers that are non-negative, strings which represent the names of foods, objects that have passed validation).\n\n```ts\nconst unverifiedName = 'Alice';\nconst verifiedName = unverifiedName as Brand<'Alice', 'VerifiedName'>;\n\n'Alice' satisfies Brand<string, 'VerifiedName'>; // ERROR\n'Alice' satisfies Brand<'Alice', 'VerifiedName'>; // ERROR\nunverifiedName satisfies Brand<string, 'VerifiedName'>; // ERROR\nverifiedName satisfies Brand<'Bob', 'VerifiedName'>; // ERROR\nverifiedName satisfies Brand<'Alice', 'VerifiedName'>; // OK\nverifiedName satisfies Brand<string, 'VerifiedName'>; // OK\n```\n\n## Values can be tagged as compressed data\n\nUse the `CompressedData` utility to produce a new type that satisfies the original type, but adds extra type information that marks the type as containing compressed data.\n\n```ts\nconst untaggedData = new Uint8Array([/ ... *\\/]);\nconst compressedData = untaggedData as CompressedData<typeof untaggedData, 'zstd'>;\n\ncompressedData satisfies CompressedData<Uint8Array, 'zstd'>; // OK\nuntaggedData satisfies CompressedData<Uint8Array, 'zstd'>; // ERROR\n```\n\n## Strings can be tagged as being encoded using a particular scheme\n\n```ts\nconst untaggedString = 'dv1ZAGvdsz5hHLwWXsVnM94hWf1pjbKVau1QVkaMJ92';\nconst encodedString = untaggedString as EncodedString<typeof untaggedString, 'base58'>;\n\nencodedString satisfies EncodedString<'dv1ZAGvdsz5hHLwWXsVnM94hWf1pjbKVau1QVkaMJ92', 'base58'>; // OK\nencodedString satisfies EncodedString<string, 'base58'>; // OK\nencodedString satisfies EncodedString<string, 'base64'>; // ERROR\nuntaggedString satisfies EncodedString<string, 'base58'>; // ERROR\n```\n\n## Brands, compression, and encodings can be combined\n\n```ts\nconst encodedCompressedString = 'abc' as Brand<\n    EncodedString<CompressedData<'abc', 'zstd'>, 'base64'>,\n    'Base64ZstdCompressedData'\n>;\n\nencodedCompressedString satisfies Brand<'abc', 'Base64ZstdCompressedData'>; // OK\nencodedCompressedString satisfies Brand<string, 'Base64ZstdCompressedData'>; // OK\nencodedCompressedString satisfies CompressedData<'abc', 'zstd'>; // OK\nencodedCompressedString satisfies CompressedData<string, 'zstd'>; // OK\nencodedCompressedString satisfies EncodedString<'abc', 'base64'>; // OK\nencodedCompressedString satisfies EncodedString<string, 'base64'>; // OK\nencodedCompressedString satisfies EncodedString<string, 'base58'>; // ERROR\n```\n\n## Custom nominal types\n\n```ts\ntype SweeteningSubstance = 'aspartame' | 'cane-sugar' | 'stevia';\ntype Sweetener<T extends SweeteningSubstance> = NominalType<'sweetener', T>;\n\n// This function accepts sweetened foods, except those with aspartame.\ndeclare function eat(food: string & Sweetener<Exclude<SweeteningSubstance, 'aspartame'>>): void;\n\nconst artificiallySweetenedDessert = 'ice-cream' as string & Sweetener<'aspartame'>;\neat(artificiallySweetenedDessert); // ERROR\n```\n","readmeFilename":"README.md"}