{"id":18428001,"url":"https://github.com/mscharley/generic-type-guard","last_synced_at":"2025-04-04T18:05:01.162Z","repository":{"id":26853137,"uuid":"110298207","full_name":"mscharley/generic-type-guard","owner":"mscharley","description":"Type safe, composable type guards for TypeScript","archived":false,"fork":false,"pushed_at":"2024-10-09T23:04:36.000Z","size":3763,"stargazers_count":52,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-09T23:10:52.550Z","etag":null,"topics":["input-validation","type-guards","type-safety","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/generic-type-guard","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mscharley.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"mscharley","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":"npm/generic-type-guard","community_bridge":null,"liberapay":"mscharley","issuehunt":null,"otechie":null,"custom":null}},"created_at":"2017-11-10T22:23:10.000Z","updated_at":"2024-10-09T23:04:00.000Z","dependencies_parsed_at":"2024-01-06T01:30:00.088Z","dependency_job_id":"1fbec3ff-0e32-4c45-b24b-b58d487b5e02","html_url":"https://github.com/mscharley/generic-type-guard","commit_stats":{"total_commits":752,"total_committers":10,"mean_commits":75.2,"dds":0.5412234042553192,"last_synced_commit":"cccaa1402021d5868508a3232111de5b8b5deff9"},"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mscharley%2Fgeneric-type-guard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mscharley%2Fgeneric-type-guard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mscharley%2Fgeneric-type-guard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mscharley%2Fgeneric-type-guard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mscharley","download_url":"https://codeload.github.com/mscharley/generic-type-guard/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247226213,"owners_count":20904465,"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":["input-validation","type-guards","type-safety","typescript"],"created_at":"2024-11-06T05:12:30.053Z","updated_at":"2025-04-04T18:05:01.141Z","avatar_url":"https://github.com/mscharley.png","language":"TypeScript","funding_links":["https://github.com/sponsors/mscharley","https://tidelift.com/funding/github/npm/generic-type-guard","https://liberapay.com/mscharley"],"categories":[],"sub_categories":[],"readme":"# generic-type-guard\n\n[![npm](https://img.shields.io/npm/v/generic-type-guard.svg)](https://www.npmjs.com/package/generic-type-guard)\n\n## Synopsis\n\nThis library is an attempt to manage creating type guards in a sensible way, making them\ncomposable and reusable.\n\n## Installation\n\n    $ npm i generic-type-guard\n\n## Usage\n\nThe point of this library is to provide a suite of type guard expressions that are\nthemselves both type safe and composable in a type safe way. To that end we define two new\ntypes which are just aliases for the built-in type guard type:\n\n```typescript\nexport type PartialTypeGuard\u003cT, U extends T\u003e = (value: T) =\u003e value is U;\nexport type TypeGuard\u003cT\u003e = PartialTypeGuard\u003cunknown, T\u003e;\n```\n\nA `PartialTypeGuard` is a type guard which given a value of type `T` can prove it is\nactually the specialised type `U`. A `TypeGuard` is a type guard that can prove any value\nto be of type `T`; it is a `PartialTypeGuard\u003cunknown, T\u003e`.\n\n### Type safety\n\nWhat do we mean by type safety when we're talking about something that in a lot of ways\nis inherantly type unsafe? We simply mean that if you change the definition your\ninterface/variable/whatever you are checking then your type guard should no longer\nsuccessfully compile. Most of the type safety comes from leveraging the compiler, therefore\nyou must define your typeguards in the following way to make them the most effective:\n\n```typescript\ninterface Foo {\n\tfoo: string;\n\tbar: number;\n}\n\n// this fails.\nconst isBrokenFoo: tg.TypeGuard\u003cFoo\u003e = tg.isRecord('foo', tg.isString);\n\n// this works.\nconst isFoo: tg.TypeGuard\u003cFoo\u003e = new tg.IsInterface()\n\t.withProperty('foo', tg.isString)\n\t.withProperty('bar', tg.isNumber)\n\t.get();\n\n// This works around the gotchas explained below but has other issues, especially with complex types.\n// All guarantees are void if you use this format.\nconst isFoo = new tg.IsInterface().withProperty('foo', tg.isString).withProperty('bar', tg.isNumber).get();\n```\n\nIt is highly recommended to assign an explicit type to the type guards you create to let the\ncompiler ensure that you've caught everything.\n\n### Examples\n\nSome examples:\n\n```typescript\nimport * as tg from 'generic-type-guard';\n\nexport const isComplexInterface = new tg.IsInterface()\n\t.withProperties({\n\t\tstr: tg.isString,\n\t\tnum: tg.isNumber,\n\t\tb: tg.isBoolean,\n\t\tmaybeString: tg.isOptional(tg.isString),\n\t\tnullableString: tg.isNullable(tg.isString),\n\t})\n\t.get();\nexport type ComplexInterface = tg.GuardedType\u003ctypeof isComplexInterface\u003e;\n```\n\n[There are more detailed examples available.][example-usage]\n\n### Gotchas\n\n#### TypeScript structural typing\n\n`generic-type-guard` works with the TypeScript type system. You are guaranteed that the type guards you write are _sufficient_ to prove\nthat the thing provided to it conforms in one way or another to the type that the type guard checks for. But that doesn't necessarily mean\nthat all valid values of that type will be allowed. Put another way, you are guaranteed to never get a false positive but you may get false\nnegatives. In particular, union types can be troublesome.\n\nAn example helps illustrate this:\n\n```typescript\nimport * as tg from 'generic-type-guard';\n\ntype FooBar = 'foo' | 'bar';\n\nconst isFooBar: tg.TypeGuard\u003cFooBar\u003e = tg.isSingletonString('foo');\n```\n\nThe above example checks for a single value `\"foo\"`. This _is_ a FooBar and so the type system does not complain. But if you try to pass\n`\"bar\"` into this type guard then it will return false.\n\nPerhaps more insidiously:\n\n```typescript\ninterface Foo {\n\tfoo?: string;\n}\n\nconst isFoo: tg.TypeGuard\u003cFoo\u003e = tg.isRecord('foo', tg.isString);\n```\n\nAgain, checking that `foo` is a string is sufficient to prove that it is either a string or undefined.\n\n##### Fix for structural typing issues\n\nIf possible, you should reframe the question. Instead of creating a type to guard against, create a guard and export the type:\n\n```typescript\nconst isFoo = tg.isRecord('foo', tg.isOptional(tg.isString));\ntype Foo = tg.GuardedType\u003ctypeof isFoo\u003e;\n```\n\n[gh-contrib]: https://github.com/mscharley/generic-type-guard/graphs/contributors\n[gh-issues]: https://github.com/mscharley/generic-type-guard/issues\n[license]: https://github.com/mscharley/generic-type-guard/blob/master/LICENSE\n[example-usage]: https://github.com/mscharley/generic-type-guard/blob/main/src/__tests__/examples.ts\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmscharley%2Fgeneric-type-guard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmscharley%2Fgeneric-type-guard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmscharley%2Fgeneric-type-guard/lists"}