{"id":16593619,"url":"https://github.com/lucinyan/ts-known","last_synced_at":"2025-10-26T23:04:38.232Z","repository":{"id":97047235,"uuid":"605622372","full_name":"LuciNyan/ts-known","owner":"LuciNyan","description":"This library offers guards for common types, and methods to generate type guards for specific types quickly. Safely handle unpredictable unknown types with ease.","archived":false,"fork":false,"pushed_at":"2023-03-03T14:51:04.000Z","size":110,"stargazers_count":83,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-15T08:02:13.342Z","etag":null,"topics":["guard","ts","type-guards","typescript","utils"],"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/LuciNyan.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":".github/CODEOWNERS","security":null,"support":null,"governance":null}},"created_at":"2023-02-23T14:52:31.000Z","updated_at":"2024-12-02T22:04:03.000Z","dependencies_parsed_at":"2023-07-23T02:30:17.893Z","dependency_job_id":null,"html_url":"https://github.com/LuciNyan/ts-known","commit_stats":{"total_commits":68,"total_committers":4,"mean_commits":17.0,"dds":"0.044117647058823484","last_synced_commit":"df5279bde0ecefb305cedbbc87a64baac9422c7b"},"previous_names":["dodoco-tales/ts-guard"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuciNyan%2Fts-known","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuciNyan%2Fts-known/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuciNyan%2Fts-known/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuciNyan%2Fts-known/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LuciNyan","download_url":"https://codeload.github.com/LuciNyan/ts-known/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243830915,"owners_count":20354850,"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":["guard","ts","type-guards","typescript","utils"],"created_at":"2024-10-11T23:43:38.048Z","updated_at":"2025-10-26T23:04:33.192Z","avatar_url":"https://github.com/LuciNyan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ts-known\nIf you're looking for a ultra-light and non-intrusive utility library to conveniently and safely handle unknown variables in your TypeScript projects, **ts-known** can help. With a collection of guards for common types and functions to generate type-specific guards, **ts-known** allows for easy handling of **unknown** variables caught by try-catch, network-transmitted data, and parsed JSON objects.\n\n## Installation\nTo install **ts-known**, simply use your favorite package manager:\n\n```bash\nnpm install ts-known\n# or\nyarn add ts-known\n```\n\n## Features\n- Provides a collection of guards for common types\n- Allows you to generate type-specific guards with ease\n- Ensures your code is safe when handling unknown type variables\n- Supports handling of circular references\n- Easy to use and integrate into your TypeScript project\n\n## Usage\nUsing **ts-known** is easy. Simply import the library and start using its guards:\n```ts\nimport { isIterator } from 'ts-known'\n\nconst x: unknown\n\nif (isIterator(x)) {\n  // x is now guaranteed to be a iterator\n}\n```\n\n**ts-known** provides operators and guards that can be easily used together with your own type guards. For example, consider the following types and type guard.\n```ts\ntype Person = {\n  name: string;\n  friend: Dog;\n};\n\nclass Dog {}\n\nfunction isDog(x: unknown): x is Dog {\n  return x instanceof Dog;\n}\n\nconst guard = objectOf({\n  name: isString,\n  friend: isDog,\n})\n\nconst x: unknown = {}\n\nif (guard(x)) {\n  type Name = typeof x.name // string\n  type Friend = typeof x.friend // Dog\n}\n```\n\n\nIn addition to the provided guards, you can also generate your own type-specific guards.\n\n### objectOf\nobjectOf is a function that takes an object with property names and associated guards as arguments and returns a function that checks if an object has properties guarded by given guards. If the object has a circular reference, SELF should be used as the guard.\n```ts\nimport { objectOf, isString, isNumber, SELF } from 'ts-known'\n\ntype Elem = {\n  name: string\n  ref: Elem\n}\n\nfunction handleElem(x: Elem) {}\n\nconst guard = objectOf({\n  name: isString,\n  ref: optional(SELF),\n})\n\nconst elem: unknown = { name: 'element' }\nconsole.log(guard(elem)) // true\n\nelem.ref = 1\nconsole.log(guard(elem)) // false\n\nelem.ref = elem\nconsole.log(guard(elem)) // true\n\nhandleElem(elem) // TS: Argument of type 'unknown' is not assignable to parameter of type 'Elem'.\n\nif (guard(elem)) {\n  handleElem(elem) // 🎉\n}\n```\n\n### arrayOf\narrayOf is a function that takes a spread of guards as arguments and returns a function that checks if an array contains only elements that match one of the given guards.\n```ts\nimport { arrayOf, isString, isNumber } from 'ts-known'\n\nconst guard = arrayOf(isNumber, isString)\n\nconsole.log(guard([1])) // true\nconsole.log(guard([1, 'hello'])) // true\nconsole.log(guard(['1', 'hello', '1', 'hello'])) // true\nconsole.log(guard([true])) // false\nconsole.log(guard([1, 'hello', true])) // false\n\n```\n\n### or\nor is a function that takes a spread of guards as arguments and returns a function that checks if a value matches any of the given guards.\n```ts\nimport { or, isString, isNumber, isBoolean } from 'ts-known'\n\nconst guard = or(isString, isNumber, isBoolean)\n\nconsole.log(guard('foo')) // true\nconsole.log(guard(123)) // true\nconsole.log(guard(true)) // true\nconsole.log(guard(undefined)) // false\nconsole.log(guard(null)) // false\nconsole.log(guard({})) // false\nconsole.log(guard([])) // false\n```\n\n### and\nand is a function that takes a spread of guards as arguments and returns a function that checks if a value matches all of the given guards.\n```ts\nimport { and, objectOf, isObject, isString, isNumber } from 'ts-known'\n\nconst guard = and(\n  isObject,\n  objectOf({ name: isString }),\n  objectOf({ age: isNumber })\n)\n\nconsole.log(guard({ name: 'Luci', age: 17 })) // true\nconsole.log(guard(undefined)) // false\nconsole.log(guard(null)) // false\nconsole.log(guard({ name: 'Luci' })) // false\nconsole.log(guard({ age: 30 })) // false\nconsole.log(guard({ name: 123 })) // false\nconsole.log(guard({ name: 'Luci', age: '17' })) // false\n```\n\n### optional\noptional is a function that takes a guard as an argument and returns a function that checks if a value is either undefined or matches the given guard.\n```ts\nconst guard = and(\n  isObject,\n  objectOf({\n    name: optional(isString),\n  }),\n  objectOf({\n    age: optional(isNumber),\n  })\n)\n\nconsole.log(guard({ name: 'Luci', age: 17 })) // true\nconsole.log(guard({ name: 'Luci' })) // true\nconsole.log(guard({ age: 17 })) // true\nconsole.log(guard({})) // true\nconsole.log(guard(undefined)) // false\nconsole.log(guard(null)) // false\nconsole.log(guard({ name: 'Luci', age: '17' })) // false\nconsole.log(guard({ name: 17 })) // false\n```\n  \n\n## Contribution\nWe welcome any contributions to ts-known! Feel free to create a pull request, report a bug, or suggest new features. We appreciate your support!\n\n## License\n**ts-known** is licensed under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucinyan%2Fts-known","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucinyan%2Fts-known","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucinyan%2Fts-known/lists"}