{"id":18351647,"url":"https://github.com/UselessPickles/ts-enum-util","last_synced_at":"2025-04-06T11:32:35.322Z","repository":{"id":40643687,"uuid":"121585665","full_name":"UselessPickles/ts-enum-util","owner":"UselessPickles","description":"Strictly typed utilities for working with TypeScript enums","archived":false,"fork":false,"pushed_at":"2024-04-12T21:07:17.000Z","size":1833,"stargazers_count":228,"open_issues_count":9,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-28T04:38:42.521Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/UselessPickles.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-15T02:53:35.000Z","updated_at":"2024-06-18T14:04:48.334Z","dependencies_parsed_at":"2024-04-12T22:23:11.162Z","dependency_job_id":"e2561c6a-c8b6-4ddc-8808-27d4adb525f1","html_url":"https://github.com/UselessPickles/ts-enum-util","commit_stats":{"total_commits":210,"total_committers":3,"mean_commits":70.0,"dds":"0.042857142857142816","last_synced_commit":"b23636056e1c58120b6d979346f90d7339f6b7f8"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UselessPickles%2Fts-enum-util","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UselessPickles%2Fts-enum-util/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UselessPickles%2Fts-enum-util/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UselessPickles%2Fts-enum-util/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UselessPickles","download_url":"https://codeload.github.com/UselessPickles/ts-enum-util/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247478151,"owners_count":20945257,"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-05T21:32:09.361Z","updated_at":"2025-04-06T11:32:34.866Z","avatar_url":"https://github.com/UselessPickles.png","language":"TypeScript","readme":"[![npm version](https://img.shields.io/npm/v/ts-enum-util.svg)](https://www.npmjs.com/package/ts-enum-util)\n[![Join the chat at https://gitter.im/ts-enum-util/Lobby](https://badges.gitter.im/ts-enum-util/Lobby.svg)](https://gitter.im/ts-enum-util/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n[![Build Status](https://travis-ci.org/UselessPickles/ts-enum-util.svg?branch=master)](https://travis-ci.org/UselessPickles/ts-enum-util)\n[![Coverage Status](https://coveralls.io/repos/github/UselessPickles/ts-enum-util/badge.svg?branch=master)](https://coveralls.io/github/UselessPickles/ts-enum-util?branch=master)\n\n# ts-enum-util\n\nStrictly typed utilities for working with TypeScript enums (and string/number literal union types).\n\nNOTE: Be sure to read about supported TypeScript versions in the [Requirements](#requirements) section.\n\n# Contents\n\n\u003c!-- TOC depthFrom:2 --\u003e\n\n-   [What is it?](#what-is-it)\n    -   [Enum Wrapper Utilities](#enum-wrapper-utilities)\n    -   [Enum Value Visitor/Mapper](#enum-value-visitormapper)\n-   [Installation](#installation)\n-   [Getting Started](#getting-started)\n-   [Usage Documentation/Examples](#usage-documentationexamples)\n-   [Requirements](#requirements)\n-   [Why is the main export named `$enum`?](#why-is-the-main-export-named-enum)\n\n\u003c!-- /TOC --\u003e\n\n## What is it?\n\n`ts-enum-util` provides type-safe utilities to improve the usefulness of TypeScript enums.\nThere are two major and distinct aspects to `ts-enum-util`.\n\n### Enum Wrapper Utilities\n\nA wrapper around an enum, or \"enum-like object\", that provides a variety of type-safe\nutilities in terms of the run-time representation fo the enum's keys/values. Some\nexamples include:\n\n-   Get a list of an enum's keys, values, or key/value pairs.\n-   Look up values by key with run-time key validation and optional result defaulting.\n-   Reverse lookup of keys by value (for string enums too!) with run-time value validation and optional result defaulting.\n-   Run-time validation that a specified value or key is valid for a given enum, with compile-time type guards.\n-   Treat an enum similar to an Array of key/value tuples.\n-   Treat an enum similar to a Map of values.\n\nAll of these utilities are very specifically typed for each enum via generics and type inference.\n\n### Enum Value Visitor/Mapper\n\nA visitor pattern for processing a single value whose type is an enum, or union of\nstring/number literals. It's like a switch statement that forces you to implement\nevery possible case (including `null` or `undefined`, if relevant), avoiding bugs\nbecause you forgot to handle one of the enum's values, or because the enum\ndefinition was updated with a new value and you forgot to update existing code to\nhandle the new value.\n\nThe more generalized \"visit\" functionallity has you associate a different function\nwith each possible value of an enum or string/number literal union.\nThe appropriate function is executed (and its return value returned) based on\nwhich value the argument is at run-time.\n\nA streamlined \"map\" functionality has you simply associate values (of any type)\nwith each possible value of an enum or string/number literal union.\nThe appropriate mapped value is returned based on which value the argument is at run-time.\n\n## Installation\n\nInstall via [NPM](https://www.npmjs.com/package/ts-enum-util):\n\n```\nnpm i -s ts-enum-util\n```\n\n## Getting Started\n\nImport `$enum`:\n\n```ts\nimport { $enum } from \"ts-enum-util\";\n```\n\nDefine an `enum`:\n\n```ts\nenum Color {\n    R,\n    G,\n    B\n}\n```\n\nUse `$enum()` as a function to access [Enum Wrapper Utilities](./docs/EnumWrapper.md) for your `enum`:\n\n```ts\n// type of \"values\": Color[]\n// value of \"values\": [0, 1, 2]\nconst values = $enum(Color).getValues();\n```\n\nUse `$enum.visitValue()` or `$enum.mapValue()` to access [Enum Value Visitor/Mapper](./docs/EnumValueVisitor.md) functionality:\n\n```ts\nfunction doColorAction(color: Color): void {\n    $enum.visitValue(color).with({\n        [Color.R]: () =\u003e {\n            window.alert(\"Red Alert!\");\n        },\n        [Color.G]: () =\u003e {\n            window.location = \"http://google.com\";\n        },\n        [Color.B]: () =\u003e {\n            console.log(\"Blue\");\n        }\n    });\n}\n\nfunction getColorLabel(color: Color | undefined): string {\n    return $enum.mapValue(color).with({\n        [Color.R]: \"Red\",\n        [Color.G]: \"Green\",\n        [Color.B]: \"Blue\",\n        [$enum.handleUndefined]: \"Unspecified\"\n    });\n}\n```\n\n## Usage Documentation/Examples\n\nTo keep the size of the README under control, usage documentation and examples have\nbeen split out to separate files:\n\n-   [Enum Wrapper Utilities](./docs/EnumWrapper.md)\n-   [Enum Value Visitor/Mapper](./docs/EnumValueVisitor.md)\n    -   [Migration Guide: from `ts-string-visitor`](./docs/migration_from_ts-string-visitor.md)\n\n## Requirements\n\n-   _TypeScript 2.9+_: `ts-enum-util` is all about strictly type-safe utilities\n    around TypeScript enums, so it would be much less useful in a plain JavaScript\n    project. More specifically, TypeScript 2.9 included advancements in handling\n    number literals as property names of object types, which is necessary for\n    implementing some `ts-enum-util` functionality consistently for both string and\n    number enum types.\n    -   _Stuck with an older version of TypeScript_?\n        -   For Value Visitor/Mapper functionality, check out `ts-string-visitor`\n            ([npm](https://www.npmjs.com/package/ts-string-visitor),\n            [github](https://github.com/UselessPickles/ts-string-visitor)). NOTE:\n            numeric value visiting/mapping not supported!\n        -   For Enum Wrapper\n            functionality, check out v3 or v2 of `ts-enum-util`.\n-   _ES6 Features_: The following ES6 features are used by `ts-enum-util`, so they\n    must exist (either natively or via polyfill) in the run-time environment:\n    -   `Map`\n    -   `WeakMap`\n    -   `Symbol`\n    -   `Symbol.iterator`\n    -   `Symbol.toStringTag`\n\n## Why is the main export named `$enum`?\n\nI wanted something short, simple, and easy to remember that was unlikely to conflict with anything else so that no one would have to alias it when importing it. By exporting a clear, memorable, and uniquely named \"thing\", this allows you to simply start writing code that uses `$enum` and most IDEs can take care of inserting the import { \\$enum } from \"ts-enum-util\"; for you (either automatically, or with a quick keyboard shortcut).\n\nI ended up using inspiration from the naming of jquery's `$()` function. Many javascript developers are familiar with jquery, and the fact that `$()` gives you a wrapper around a raw DOM element to expose additional/simplified functionality around the DOM element.\n\nSimilarly, `$enum()` gives you a wrapper around a raw enum to expose additional/simplified functionality around the enum.\n","funding_links":[],"categories":["Packages","TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FUselessPickles%2Fts-enum-util","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FUselessPickles%2Fts-enum-util","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FUselessPickles%2Fts-enum-util/lists"}