{"id":20838738,"url":"https://github.com/royalicing/pivots","last_synced_at":"2026-04-24T00:33:43.546Z","repository":{"id":57324976,"uuid":"236950721","full_name":"RoyalIcing/pivots","owner":"RoyalIcing","description":"Readable discriminated unions for TypeScript","archived":false,"fork":false,"pushed_at":"2020-11-12T00:03:39.000Z","size":95,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-18T23:02:33.094Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/pivots","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/RoyalIcing.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-29T09:57:12.000Z","updated_at":"2022-10-24T04:18:33.000Z","dependencies_parsed_at":"2022-09-06T09:20:34.718Z","dependency_job_id":null,"html_url":"https://github.com/RoyalIcing/pivots","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoyalIcing%2Fpivots","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoyalIcing%2Fpivots/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoyalIcing%2Fpivots/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoyalIcing%2Fpivots/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RoyalIcing","download_url":"https://codeload.github.com/RoyalIcing/pivots/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243196650,"owners_count":20251860,"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":[],"created_at":"2024-11-18T01:11:23.925Z","updated_at":"2025-12-27T02:34:31.898Z","avatar_url":"https://github.com/RoyalIcing.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pivots\n\n## Readable [discriminated unions](https://www.typescriptlang.org/docs/handbook/advanced-types.html#discriminated-unions) for TypeScript\n\nProblem: you have values which can be one of a possible set of types, such as actions to a reducer, or types of a value.\n\nLet’s take an example of a desk item. It could be a lamp, a notebook of size A5 or A4, or a pen of a specific type.\n\nYou could do something like this:\n\n```typescript\ntype DeskItem =\n  | { type: 'lamp' }\n  | { type: 'notebook'; size: 'A5' | 'A4' }\n  | { type: 'pen'; penType: 'ballpoint' | 'rollerball' | 'fountain' };\n```\n\nYou find this works well. The problem is when there are many type variations, which have many properties. Then legibility suffers (say after using prettier) —\n\n```typescript\ntype DeskItem =\n  | { type: 'lamp' }\n  | { type: 'notebook'; size: 'A5' | 'A4' }\n  | {\n      type: 'pen';\n      penType: 'ballpoint' | 'rollerball' | 'fountain';\n      color: 'black' | 'blue' | 'red' | 'green';\n    };\n```\n\nWouldn’t it be nice if we could make this more readable, whilst also having a system for working with these types? Enter Pivots —\n\n```typescript\ntype DeskItem2 = PivotsType\u003c{\n  lamp: {};\n  notebook: {\n    size: 'A5' | 'A4';\n  };\n  pen: {\n    penType: 'ballpoint' | 'rollerball' | 'fountain';\n    color: 'black' | 'blue' | 'red' | 'green';\n  };\n}\u003e;\n```\n\nThis is the exact same type as `DeskItem`, with a union of different object types each with a distinct `type` property, yet Pivots allowed us to declare it in a much more natural manner.\n\nWe could also use to model an action to dispatch to `useReducer()`:\n\n```typescript\nexport type TodoListAction = PivotsType\u003c{\n  addItem: { id: string; title: string };\n  removeItem: { id: string };\n  moveItem: { id: string; afterID?: string };\n  completeItem: { id: string };\n  uncompleteItem: { id: string };\n}\u003e;\n\nconst [state, dispatch] = useReducer(reducer, initialState);\n\ndispatch({ type: 'addItem', id: '9F8535DA', title: 'New item' });\ndispatch({ type: 'completeItem', id: '9F8535DA' });\n```\n\n## Docs\n\nPivots exports two types:\n\n### `PivotsType\u003cR\u003e`\n\n- Takes one generic argument: the record to be transformed.\n\n```typescript\ntype A = PivotsType\u003c{\n  apple: {\n    color: 'green' | 'red';\n  };\n  orange: {\n    variety: 'valencia' | 'blood';\n  };\n  pear: {};\n}\u003e;\n\ntype B =\n  | { type: 'apple'; color: 'green' | 'red' }\n  | { type: 'orange'; variety: 'valencia' | 'blood' }\n  | { type: 'pear' };\n\n// A and B are equivalent types\n```\n\n### `Pivots\u003cB extends string, R\u003e`\n\n- Takes one generic argument: the key to pivot on (such as `\"type\"` or `\"base\"` or `\"kind\"`), and the record to be transformed.\n\n```typescript\ntype Fruits\u003cR\u003e = Pivots\u003c'fruit', R\u003e;\n\ntype A = Fruits\u003c{\n  apple: {\n    color: 'green' | 'red';\n  };\n  orange: {\n    variety: 'valencia' | 'blood';\n  };\n  pear: {};\n}\u003e;\n\ntype B =\n  | { fruit: 'apple'; color: 'green' | 'red' }\n  | { fruit: 'orange'; variety: 'valencia' | 'blood' }\n  | { fruit: 'pear' };\n\n// A and B are equivalent types\n```\n\n---\n\n## Local Development\n\nThis project was bootstrapped with [TSDX](https://github.com/jaredpalmer/tsdx).\n\nBelow is a list of commands you will probably find useful.\n\n### `npm start` or `yarn start`\n\nRuns the project in development/watch mode. Your project will be rebuilt upon changes. TSDX has a special logger for you convenience. Error messages are pretty printed and formatted for compatibility VS Code's Problems tab.\n\nYour library will be rebuilt if you make edits.\n\n### `npm run build` or `yarn build`\n\nBundles the package to the `dist` folder.\nThe package is optimized and bundled with Rollup into multiple formats (CommonJS, UMD, and ES Module).\n\n### `npm test` or `yarn test`\n\nRuns the test watcher (Jest) in an interactive mode.\nBy default, runs tests related to files changed since the last commit.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froyalicing%2Fpivots","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froyalicing%2Fpivots","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froyalicing%2Fpivots/lists"}