{"_id":"@danwithabox/typeful-tuples","_rev":"2-e858218952be35d32ec29050f081a65c","name":"@danwithabox/typeful-tuples","dist-tags":{"latest":"0.3.2"},"versions":{"0.3.0":{"name":"@danwithabox/typeful-tuples","version":"0.3.0","keywords":["typeful-tuples","type-safe","typesafe","tuples","tuple","arrays","array"],"author":{"url":"https://github.com/danwithabox","name":"danwithabox","email":"danwithabox@gmail.com"},"license":"MIT","_id":"@danwithabox/typeful-tuples@0.3.0","maintainers":[{"name":"danwithabox","email":"danwithabox@gmail.com"}],"homepage":"https://github.com/danwithabox/typeful-tuples#readme","bugs":{"url":"https://github.com/danwithabox/typeful-tuples/issues"},"bin":{"vitest-ts-workspace-gen":"bin/vitest-ts-workspace-gen/main.ts"},"dist":{"shasum":"99d1a65d190f517eaac3c5017163a4c3d944ce76","tarball":"https://registry.npmjs.org/@danwithabox/typeful-tuples/-/typeful-tuples-0.3.0.tgz","fileCount":10,"integrity":"sha512-4DY2Cq5i332zfTPgarVPUdAR5jsu7VK8byMESkw9vUcNZnLYlJRjcLBJ6Lq4OXoZekA7njytGslDj8Wa0mb/EQ==","signatures":[{"sig":"MEQCIFA3/ZKJ4wWjg9M6PekIy0arfu4PXyc6kZ5CTn9X20XtAiA+lNJytXJYnlctgtC5Hx7njFwOIsGN30li55svQOZDLw==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@danwithabox%2ftypeful-tuples@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":56511},"main":"./lib/index.cjs","type":"module","types":"./lib/index.d.ts","module":"./lib/index.js","engines":{"node":"^18.18.0 || >=20.0.0"},"exports":{".":{"import":{"types":"./lib/index.d.ts","default":"./lib/index.js"},"require":{"types":"./lib/index.d.cts","default":"./lib/index.cjs"}}},"gitHead":"2580e94b1fc2cda4c7ddeb598f6057c78b8817e8","scripts":{"test":"vitest run","build":"tsup && publint","prepack":"publint","prepare":"husky || true","type-check":"tsc --noEmit","changeset:help":"echo You probably want to run `npx changeset`. Check out `.changeset/README.md` for more.","prepublishOnly":"publint"},"_npmUser":{"name":"danwithabox","email":"danwithabox@gmail.com"},"repository":{"url":"git+https://github.com/danwithabox/typeful-tuples.git","type":"git"},"_npmVersion":"10.8.2","description":"typeful-tuples","directories":{},"_nodeVersion":"20.18.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ora":"^8.1.0","tsx":"^4.19.1","desm":"^1.3.1","glob":"^11.0.0","tsup":"^8.3.0","chalk":"^5.3.0","execa":"^9.4.1","husky":"^9.1.6","pathe":"^1.1.2","eslint":"^9.13.0","vitest":"^2.1.3","publint":"^0.2.11","fs-extra":"^11.2.0","commander":"^12.0.0","type-fest":"^4.26.1","typescript":"^5.6.3","@types/node":"^20.16.14","editorconfig":"^2.0.0","@changesets/cli":"^2.27.9","@commitlint/cli":"^19.5.0","@types/fs-extra":"^11.0.4","@typescript/vfs":"^1.6.0","typescript-5.4.2":"npm:typescript@5.4.2","typescript-5.5.2":"npm:typescript@5.5.2","typescript-5.6.2":"npm:typescript@5.6.2","@inquirer/prompts":"^7.0.0","@vitest/coverage-v8":"^2.1.3","@danwithabox/eslint-entree":"^0.5.2","@commander-js/extra-typings":"^12.0.1","@commitlint/config-conventional":"^19.5.0"},"peerDependencies":{"typescript":"^5.5.3"},"_npmOperationalInternal":{"tmp":"tmp/typeful-tuples_0.3.0_1729596075851_0.9467950208025637","host":"s3://npm-registry-packages"}},"0.3.1":{"name":"@danwithabox/typeful-tuples","version":"0.3.1","keywords":["typeful-tuples","type-safe","typesafe","tuples","tuple","arrays","array"],"author":{"url":"https://github.com/danwithabox","name":"danwithabox","email":"danwithabox@gmail.com"},"license":"MIT","_id":"@danwithabox/typeful-tuples@0.3.1","maintainers":[{"name":"danwithabox","email":"danwithabox@gmail.com"}],"homepage":"https://github.com/danwithabox/typeful-tuples#readme","bugs":{"url":"https://github.com/danwithabox/typeful-tuples/issues"},"bin":{"vitest-ts-workspace-gen":"bin/vitest-ts-workspace-gen/main.ts"},"dist":{"shasum":"03452c9f7186c14010ad1638a4e9552a0683e323","tarball":"https://registry.npmjs.org/@danwithabox/typeful-tuples/-/typeful-tuples-0.3.1.tgz","fileCount":10,"integrity":"sha512-v1stjcxPoRXcSIIbsuvo1TdrMX6obIOUIDlPoxWjfnlAQyWRwPPmH6kuRyBLm30fHaYiE4jGLSo4JTdL365+rQ==","signatures":[{"sig":"MEUCIQDh9fgSMRh7vV19762umkSQFiziGbyO2l9wDlHqxG5pWQIgFNDnsUe61BlivG+1jOlYBEPZK7Mo0h6ec4p6K0hfg1U=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@danwithabox%2ftypeful-tuples@0.3.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":56579},"main":"./lib/index.cjs","type":"module","types":"./lib/index.d.ts","module":"./lib/index.js","engines":{"node":"^18.18.0 || >=20.0.0"},"exports":{".":{"import":{"types":"./lib/index.d.ts","default":"./lib/index.js"},"require":{"types":"./lib/index.d.cts","default":"./lib/index.cjs"}}},"gitHead":"ee1bc41a466448e2069db4e3c0606278189b4e98","scripts":{"test":"vitest run","build":"tsup && publint","prepack":"publint","prepare":"husky || true","type-check":"tsc --noEmit && echo type-check ✅","changeset:help":"echo You probably want to run `npx changeset`. Check out `.changeset/README.md` for more.","prepublishOnly":"publint"},"_npmUser":{"name":"danwithabox","email":"danwithabox@gmail.com"},"repository":{"url":"git+https://github.com/danwithabox/typeful-tuples.git","type":"git"},"_npmVersion":"10.8.2","description":"TypeScript tuples are good, but they can be better 👉👉","directories":{},"_nodeVersion":"20.18.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ora":"^8.1.0","tsx":"^4.19.1","desm":"^1.3.1","glob":"^11.0.0","tsup":"^8.3.0","chalk":"^5.3.0","execa":"^9.4.1","husky":"^9.1.6","pathe":"^1.1.2","eslint":"^9.13.0","vitest":"^2.1.3","publint":"^0.2.11","fs-extra":"^11.2.0","commander":"^12.0.0","type-fest":"^4.26.1","typescript":"^5.6.3","@types/node":"^20.16.14","editorconfig":"^2.0.0","@changesets/cli":"^2.27.9","@commitlint/cli":"^19.5.0","@types/fs-extra":"^11.0.4","@typescript/vfs":"^1.6.0","typescript-5.4.2":"npm:typescript@5.4.2","typescript-5.5.2":"npm:typescript@5.5.2","typescript-5.6.2":"npm:typescript@5.6.2","@inquirer/prompts":"^7.0.0","@vitest/coverage-v8":"^2.1.3","@danwithabox/eslint-entree":"^0.5.2","@commander-js/extra-typings":"^12.0.1","@commitlint/config-conventional":"^19.5.0"},"peerDependencies":{"typescript":"^5.5.3"},"_npmOperationalInternal":{"tmp":"tmp/typeful-tuples_0.3.1_1729597698257_0.0011343797943199618","host":"s3://npm-registry-packages"}},"0.3.2":{"name":"@danwithabox/typeful-tuples","description":"TypeScript tuples are good, but they can be better 👉👉","version":"0.3.2","type":"module","engines":{"node":"^18.18.0 || >=20.0.0"},"keywords":["typeful-tuples","type-safe","typesafe","tuples","tuple","arrays","array"],"author":{"name":"danwithabox","email":"danwithabox@gmail.com","url":"https://github.com/danwithabox"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/danwithabox/typeful-tuples.git"},"publishConfig":{"access":"public"},"main":"./lib/index.cjs","module":"./lib/index.js","types":"./lib/index.d.ts","exports":{".":{"require":{"types":"./lib/index.d.cts","default":"./lib/index.cjs"},"import":{"types":"./lib/index.d.ts","default":"./lib/index.js"}}},"scripts":{"prepack":"publint","prepublishOnly":"publint","prepare":"husky || true","build":"tsup && publint","test":"vitest run","type-check":"tsc --noEmit && echo type-check ✅","changeset:help":"echo You probably want to run `npx changeset`. Check out `.changeset/README.md` for more."},"bin":{"vitest-ts-workspace-gen":"bin/vitest-ts-workspace-gen/main.ts"},"devDependencies":{"@changesets/cli":"^2.27.12","@commander-js/extra-typings":"^13.1.0","@commitlint/cli":"^19.7.1","@commitlint/config-conventional":"^19.7.1","@danwithabox/eslint-entree":"^0.6.0","@inquirer/prompts":"^7.3.1","@types/fs-extra":"^11.0.4","@types/node":"^20.16.14","@typescript/vfs":"^1.6.1","@vitest/coverage-v8":"3.0.5","chalk":"^5.4.1","commander":"^13.1.0","desm":"^1.3.1","editorconfig":"^2.0.1","eslint":"^9.20.1","execa":"^9.5.2","fs-extra":"^11.3.0","glob":"^11.0.1","husky":"^9.1.7","ora":"^8.2.0","pathe":"^2.0.3","publint":"^0.3.5","tsup":"^8.3.6","tsx":"^4.19.2","type-fest":"^4.34.1","typescript":"^5.6.3","typescript-5.4.2":"npm:typescript@5.4.2","typescript-5.5.2":"npm:typescript@5.5.2","typescript-5.6.2":"npm:typescript@5.6.2","typescript-5.7.3":"npm:typescript@5.7.3","vitest":"3.0.5"},"peerDependencies":{"typescript":"^5.5.3"},"_id":"@danwithabox/typeful-tuples@0.3.2","gitHead":"ddc656ec9942a8eea5dbbe0ade3c9d37805aaeba","bugs":{"url":"https://github.com/danwithabox/typeful-tuples/issues"},"homepage":"https://github.com/danwithabox/typeful-tuples#readme","_nodeVersion":"20.18.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-QtPmYorUn1aJ0ZTst/AKksaSLJWqaTPlNcZxjjUpeXWJZmua2UuHRWHiclrnEwqLGRhQou7wzMpktKkrlZKgKA==","shasum":"e9502ad0242e2f94b0fc765deb6780ef3955be72","tarball":"https://registry.npmjs.org/@danwithabox/typeful-tuples/-/typeful-tuples-0.3.2.tgz","fileCount":10,"unpackedSize":56648,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@danwithabox%2ftypeful-tuples@0.3.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCMrgoWj+fhCKSMZpWBS29AWe5uoa+UCBUfFT/FPzMLdQIhAJn46uIQa2JOTQPHirIvhkVprysa7I1rpWk702e8L6lI"}]},"_npmUser":{"name":"danwithabox","email":"danwithabox@gmail.com"},"directories":{},"maintainers":[{"name":"danwithabox","email":"danwithabox@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/typeful-tuples_0.3.2_1739626063589_0.8321521131554503"},"_hasShrinkwrap":false}},"time":{"created":"2024-10-22T11:21:15.757Z","modified":"2025-02-15T13:27:44.315Z","0.3.0":"2024-10-22T11:21:16.061Z","0.3.1":"2024-10-22T11:48:18.467Z","0.3.2":"2025-02-15T13:27:43.775Z"},"bugs":{"url":"https://github.com/danwithabox/typeful-tuples/issues"},"author":{"name":"danwithabox","email":"danwithabox@gmail.com","url":"https://github.com/danwithabox"},"license":"MIT","homepage":"https://github.com/danwithabox/typeful-tuples#readme","keywords":["typeful-tuples","type-safe","typesafe","tuples","tuple","arrays","array"],"repository":{"type":"git","url":"git+https://github.com/danwithabox/typeful-tuples.git"},"description":"TypeScript tuples are good, but they can be better 👉👉","maintainers":[{"name":"danwithabox","email":"danwithabox@gmail.com"}],"readme":"# @danwithabox/typeful-tuples\n\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nTypeScript tuples are good, but they can be better 👉👉\n\n## Install\n\n```bash\n$ npm install @danwithabox/typeful-tuples --save\n```\n\n> [!IMPORTANT]\n> This package has a peer dependency of `typescript@>=5.4.2`, versions below are not supported as this depends on [inference improvements from TypeScript 5.4](https://devblogs.microsoft.com/typescript/announcing-typescript-5-4/)!\n\n## Overview\n\nEver been annoyed by `as const` returning readonly arrays? It's a thing of the past!\n```ts\nconst nay = [\"foo\", \"bar\"] as const;\nconst yay = tuple([\"foo\", \"bar\"]); // not readonly!\n```\nGreat, but what if you'd like to narrow the allowed elements?\n```ts\nconst yay = tupleOf<\"foo\" | \"baz\">()([\"foo\", \"bar\"]); // and realize that you meant `\"baz\"` instead of `\"bar\"`!\n```\nOr did you want to express well-known values, without the risk of duplicates?\n```ts\nconst colorOptions = tupleUnique([\"gray\", \"red\", \"blue\", \"light green\", \"gold\", \"red\", \"lime green\"]); // a red squiggle will mark the embarrassing doubled option!\n```\nAnd again, narrowing the allowed elements:\n```ts\nconst colorOptionsButBoring = tupleUniqueOf<\"red\" | \"blue\">()([\"gray\", \"red\", \"blue\", \"light green\", \"gold\", \"red\", \"lime green\"]); // lots more red squiggles now, enforcing a really boring color picker!\n```\nBut what if you not only want to narrow, but enforce the provided elements?\n```ts\nconst colorOptionsForSure = tupleExhaustiveOf<\"red\" | \"green\" | \"blue\">()([\"red\", \"blue\"]); // missing something!\n```\n\nIn summary:\n\n|                               | uniqueness?   | narrowed?     | exhaustive?   |\n| ----------------------------- | ------------- | ------------- | ------------- |\n| `tuple()`                     | ❌           | ❌            | ❌           |\n| `tupleUnique()`               | ✅           | ❌            | ❌           |\n| `tupleOf<T>()()`              | ❌           | ✅            | ❌           |\n| `tupleUniqueOf<T>()()`        | ✅           | ✅            | ❌           |\n| `tupleExhaustiveOf<T>()()`    | ✅           | ✅            | ✅           |\n\n## Example\n\n![output](https://github.com/danwithabox/typeful-tuples/assets/144792741/2e46bee7-e8f0-4d91-b80c-204a895e2261)\n\n```ts\nimport { tuple, tupleOf, tupleUnique, tupleUniqueOf, tupleExhaustiveOf } from \"@danwithabox/typeful-tuples\";\n\ntype Allowed = \"foo\" | \"bar\" | 42 | \"baz\";\n\n// Behaves like `[] as const`, except the result array is not `readonly`\ntuple([\"foo\", \"foo\"]);\n\n// Non-unique elements are rejected with a `never` type\ntupleUnique([\"foo\", \"bar\", \"baz\"]);\n\n// Same as `tuple()`, but only accepts the provided types\ntupleOf<Allowed>()([\"bar\", \"foo\", \"foo\", \"bar\"]);\n\n// Same as `tupleUnique()`, but only accepts the provided types\ntupleUniqueOf<Allowed>()([\"foo\", \"bar\"]);\n\n// Same as `tupleUniqueOf()`, but all provided types are required in the tuple\ntupleExhaustiveOf<Allowed>()([\"baz\", 42, \"bar\", \"foo\"]);\n\n```\n\n## Assurances\n\n### Performance\nTypechecking speed is excellent and scales linearly - but way before that could become a problem, TS may throw `Type instantiation is excessively deep and possibly infinite.ts(2589)`. This [tends to happen with advanced types](https://github.com/sindresorhus/type-fest/pull/650), unfortunately. From what I've seen, unique tuples should not throw below ~40 elements. Meaningful hand-written tuples are rarely that large, but I'm not entriely happy with it anyway, and may improve it in the future.\n\n### Reliability\nWhile the type algebra I use for this package is non-trivial, it's also non-volatile - the TypeScript features exploited in here *are supposed to be stable*.\n\n**However**, TypeScript is very lax with breaking changes: [TypeScript’s Versioning Policy - Semantic Versioning for TypeScript Types (semver-ts.org)](https://www.semver-ts.org/1-background.html)\n\nAs such, I have created robusts tests and embedded a CLI tool in this project:\n- the tests cover multiple TypeScript versions, and also assert IDE and language server messages (autocompletes and \"red squiggles\")\n- consumers of the package see nothing of this\n- people who wish to mess with the source should check the `\"bin\"` property in `package.json`\n\n> **TLDR**: not even wild TypeScript updates may break this package\n\n## Limitations\nNot a lot!\n\nOne limitation is the `Type instantiation is excessively deep and possibly infinite.ts(2589)` issue mentioned above.\n\n`NaN`, `Symbol`s and other such special values that look distinct, but are actually not unique literals according to the type system, also cause issues. Do not use them as elements for now.\n\nIf you are wondering why `tupleOf<T>()()`, `tupleUniqueOf<T>()()`, and `tupleExhaustiveOf<>()()` are curried functions, it's because of the need for a user-defined generic type parameter. The upstream TypeScript issue that blocks them from becoming non-curried, or to even be merged with `tuple()` and `tupleUnique()`, is this: [Proposal: Partial Type Argument Inference #26242](https://github.com/microsoft/TypeScript/issues/26242)\n<!-- Incorporating typeful tuples into function signatures as parameters, e.g. telling a function to expect a unique tuple, cannot be simplified much. -->\n\n## Acknowledgements\nInitial inspiration by: https://ja.nsommer.dk/articles/type-checked-unique-arrays.html\n\nGrateful for this TypeScript feature finally landing: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html#const-type-parameters\n\n## Feedback & Contribution\nI welcome feedback about use cases where this package may fall short, but within the scope of \"tuple element uniqueness checks\".\n\nMy motivation to create this was slowly built up over years of slight frustrations with tuples, if you have similar pet peeves, do tell.\n\nAs with any advanced TypeScript stuff, the types powering this are not for the faint of heart, and I do not wish to complicate them much further - post issues with this in mind.\n","readmeFilename":"README.md"}