{"id":13623731,"url":"https://github.com/lukemorales/exhaustive","last_synced_at":"2025-04-13T04:58:59.682Z","repository":{"id":65561486,"uuid":"594502871","full_name":"lukemorales/exhaustive","owner":"lukemorales","description":"Exhaustiveness checking in TypeScript","archived":false,"fork":false,"pushed_at":"2024-07-21T23:02:16.000Z","size":186,"stargazers_count":354,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-13T04:58:52.850Z","etag":null,"topics":["exhaustive","exhaustive-check","exhaustiveness-checking","match","pattern-matching","ts-pattern","unreachable"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/exhaustive","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lukemorales.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-28T18:45:27.000Z","updated_at":"2025-03-02T16:06:18.000Z","dependencies_parsed_at":"2024-01-20T05:13:02.098Z","dependency_job_id":"b26429dd-181b-47a3-980a-a38a7facc3e0","html_url":"https://github.com/lukemorales/exhaustive","commit_stats":{"total_commits":10,"total_committers":2,"mean_commits":5.0,"dds":0.4,"last_synced_commit":"91e441e6555f811d7d792d35b0d067c83762cf23"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukemorales%2Fexhaustive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukemorales%2Fexhaustive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukemorales%2Fexhaustive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukemorales%2Fexhaustive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lukemorales","download_url":"https://codeload.github.com/lukemorales/exhaustive/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665759,"owners_count":21142123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["exhaustive","exhaustive-check","exhaustiveness-checking","match","pattern-matching","ts-pattern","unreachable"],"created_at":"2024-08-01T21:01:35.029Z","updated_at":"2025-04-13T04:58:59.664Z","avatar_url":"https://github.com/lukemorales.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/lukemorales/exhaustive\" target=\"\\_parent\"\u003e\u003cimg src=\"https://em-content.zobj.net/thumbs/240/emojidex/112/tired-face_1f62b.png\" alt=\"Factory emoji\" height=\"130\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eExhaustive\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/lukemorales/exhaustive/actions/workflows/tests.yml\" target=\"\\_parent\"\u003e\u003cimg src=\"https://github.com/lukemorales/exhaustive/actions/workflows/tests.yml/badge.svg?branch=main\" alt=\"Latest build\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/exhaustive\" target=\"\\_parent\"\u003e\u003cimg src=\"https://badgen.net/npm/v/exhaustive\" alt=\"Latest published version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://bundlephobia.com/package/exhaustive@latest\" target=\"\\_parent\"\u003e\u003cimg src=\"https://badgen.net/bundlephobia/minzip/exhaustive\" alt=\"Bundlephobia\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://bundlephobia.com/package/exhaustive@latest\" target=\"\\_parent\"\u003e\u003cimg src=\"https://badgen.net/bundlephobia/tree-shaking/exhaustive\" alt=\"Tree shaking available\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/lukemorales/exhaustive\" target=\"\\_parent\"\u003e\u003cimg src=\"https://badgen.net/npm/types/exhaustive\" alt=\"Types included\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/exhaustive\" target=\"\\_parent\"\u003e\u003cimg src=\"https://badgen.net/npm/license/exhaustive\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/exhaustive\" target=\"\\_parent\"\u003e\u003cimg src=\"https://badgen.net/npm/dt/exhaustive\" alt=\"Number of downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/lukemorales/exhaustive\" target=\"\\_parent\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/lukemorales/exhaustive.svg?style=social\u0026amp;label=Star\" alt=\"GitHub Stars\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eExhaustiveness checking in TypeScript\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Tiny bundle footprint for typesafe exhaustiveness checks with helpful type inference\u003cbr /\u003eto ensure you haven’t forgotten any case.\n\u003c/p\u003e\n\n## 📦 Install\n`exhaustive` is available as a package on NPM. Install it with your favorite package manager:\n\n```dircolors\nnpm install exhaustive\n```\n\n## ⚡ Quick start\n```ts\nimport { exhaustive } from \"exhaustive\";\n\nenum Role {\n  ADMIN = 'ADMIN',\n  DEFAULT = 'DEFAULT',\n  VIEWER = 'VIEWER',\n}\n\nenum Permission {\n  DELETE = 'DELETE',\n  EDIT = 'EDIT',\n  VIEW = 'VIEW',\n}\n\nconst getUserPermissions = (role: Role) =\u003e\n  exhaustive(role, {\n    ADMIN: () =\u003e [Permission.DELETE, Permission.EDIT, Permission.VIEW],\n    DEFAULT: () =\u003e [Permission.EDIT, Permission.VIEW],\n    VIEWER: () =\u003e [Permission.VIEW],\n  });\n```\n\n\u003cbr /\u003e\n\n## 📝 Features\n\n### Tagged Unions\nWhen working with `Tagged Unions` (or `Discriminated Unions`), use `exhaustive.tag` to inform what property to discriminate between union members:\n\n```ts\ninterface Square {\n  kind: 'square';\n  size: number;\n}\n\ninterface Rectangle {\n  kind: 'rectangle';\n  width: number;\n  height: number;\n}\n\ninterface Circle {\n  kind: 'circle';\n  radius: number;\n}\n\ntype Shape = Square | Rectangle | Circle;\n\nconst area = (s: Shape) =\u003e {\n  return exhaustive.tag(s, 'kind', {\n    square: (shape) =\u003e shape.size ** 2,\n    rectangle: (shape) =\u003e shape.width * shape.height,\n    circle: (shape) =\u003e Math.PI * shape.radius ** 2,\n  });\n};\n```\n\nAn overload is also available in the core `exhaustive` function: by adding a third parameter to the function, Typescript will fallback to the Tagged Union overload.\n\n```ts\nexhaustive(s, 'kind', {\n  square: (shape) =\u003e shape.size ** 2,\n  rectangle: (shape) =\u003e shape.width * shape.height,\n  circle: (shape) =\u003e Math.PI * shape.radius ** 2,\n});\n```\n\nPS: Note that TypeScript has a limitation inferring the Tagged Union overload via argument types because they are generic values. This means autocomplete for the Tagged Union keys will not exist until you declare an empty object as the third argument:\n\n```ts\nexhaustive(s, 'kind', {});\n//                     ^ this will trigger the Tagged Union overload\n```\n\nThis overload exists so you can use it at your own convenience, but if you prefer the better DX of inferred types from the start, calling `exhaustive.tag` is still preferrable.\n\n### Type Narrowing\nFor every case checked, `exhaustive` will narrow the type of input:\n\n```ts\nconst getRoleLabel = (r: Role) =\u003e\n  exhaustive(r, {\n    ADMIN: (role) =\u003e capitalize(role), // Admin\n    //       ^? role is ADMIN\n    DEFAULT: (role) =\u003e capitalize(role), // Default\n    //         ^? role is DEFAULT\n    VIEWER: (role) =\u003e capitalize(role), // Viewer\n    //        ^? role is VIEWER\n  });\n\nconst area = (s: Shape) =\u003e {\n  return exhaustive.tag(s, 'kind', {\n    square: (shape) =\u003e shape.size ** 2,\n    //         ^? shape is Square\n    rectangle: (shape) =\u003e shape.width * shape.height,\n    //            ^? shape is Rectangle\n    circle: (shape) =\u003e Math.PI * shape.radius ** 2,\n    //         ^? shape is Circle\n  });\n};\n```\n\n\n### Default Fallback\nIf any corrupt values make to the exhaustive checker, it will throw a `TypeError` at runtime. If you don't want `exhaustive` to throw, you can provide a default fallback:\n\n```ts\nenum Food {\n  BANANA = 'BANANA',\n  SALAD = 'SALAD',\n}\n\nconst getFoodType = (food: Food) =\u003e {\n  return exhaustive(food, {\n    BANANA: () =\u003e 'Fruit',\n    SALAD: () =\u003e 'Leaves',\n    _: () =\u003e 'Unknown',\n  });\n};\n```\n\n### Exhaustive Switch Statements\nSometimes it's easier to work with switch statements, especially if you have a lot of cases that are falling-through to a common handler.\n\nTo enforce exhaustiveness checking inside `switch` statements, use the `corrupt` helper as your `default` value, which will make TypeScript complain of unhandled cases, and throw at runtime if the `default` case is reached:\n\n```ts\nimport { corrupt } from \"exhaustive\";\n\ntype Day =\n  | 'Sunday'\n  | 'Monday'\n  | 'Tuesday'\n  | 'Wednesday'\n  | 'Thursday'\n  | 'Friday'\n  | 'Saturday';\n\nconst getLabelForDayOfWeek = (day: Day) =\u003e {\n  switch (day) {\n    case 'Monday':\n    case 'Tuesday':\n    case 'Wednesday':\n    case 'Thursday':\n    case 'Friday':\n      return 'Weekday';\n    case 'Saturday':\n    // case 'Sunday':\n      return 'Weekend';\n    default:\n      corrupt(day);\n    //         ^? Argument of type 'string' is not assignable to parameter of type 'never'\n  }\n};\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukemorales%2Fexhaustive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukemorales%2Fexhaustive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukemorales%2Fexhaustive/lists"}