{"id":13485107,"url":"https://github.com/jsr-core/unknownutil","last_synced_at":"2025-08-27T22:09:40.956Z","repository":{"id":43386851,"uuid":"376332638","full_name":"jsr-core/unknownutil","owner":"jsr-core","description":"A lightweight utility pack for handling unknown type","archived":false,"fork":false,"pushed_at":"2025-08-14T23:57:20.000Z","size":593,"stargazers_count":67,"open_issues_count":6,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-08-19T12:00:47.221Z","etag":null,"topics":["javascript","jsr","typescript","unknown"],"latest_commit_sha":null,"homepage":"https://jsr.io/@core/unknownutil","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/jsr-core.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["lambdalisue"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"custom":null}},"created_at":"2021-06-12T16:09:55.000Z","updated_at":"2025-08-14T23:54:51.000Z","dependencies_parsed_at":"2023-02-18T01:46:04.187Z","dependency_job_id":"b2fa2a3f-17d0-4e8b-866c-1a8b93d864a1","html_url":"https://github.com/jsr-core/unknownutil","commit_stats":{"total_commits":40,"total_committers":4,"mean_commits":10.0,"dds":0.5,"last_synced_commit":"6c2900b55fb74cf1b3709bf424365769e695a03e"},"previous_names":["jsr-core/unknownutil","lambdalisue/deno-unknownutil"],"tags_count":71,"template":false,"template_full_name":null,"purl":"pkg:github/jsr-core/unknownutil","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsr-core%2Funknownutil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsr-core%2Funknownutil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsr-core%2Funknownutil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsr-core%2Funknownutil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jsr-core","download_url":"https://codeload.github.com/jsr-core/unknownutil/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsr-core%2Funknownutil/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272387507,"owners_count":24925908,"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","status":"online","status_checked_at":"2025-08-27T02:00:09.397Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["javascript","jsr","typescript","unknown"],"created_at":"2024-07-31T17:01:46.236Z","updated_at":"2025-08-27T22:09:40.875Z","avatar_url":"https://github.com/jsr-core.png","language":"TypeScript","funding_links":["https://github.com/sponsors/lambdalisue"],"categories":["TypeScript"],"sub_categories":[],"readme":"# unknownutil\n\n[![jsr](https://jsr.io/badges/@core/unknownutil)](https://jsr.io/@core/unknownutil)\n[![test](https://github.com/jsr-core/unknownutil/workflows/Test/badge.svg)](https://github.com/jsr-core/unknownutil/actions?query=workflow%3ATest)\n[![codecov](https://codecov.io/github/jsr-core/unknownutil/graph/badge.svg?token=pfbLRGU5AM)](https://codecov.io/github/jsr-core/unknownutil)\n\nA utility pack for handling `unknown` type.\n\n[jsr.io]: https://jsr.io/@core/unknownutil\n\n## Usage\n\nIt provides `is` and `as` module for type predicate functions and `assert`,\n`ensure`, and `maybe` helper functions.\n\n### is\\* and as\\*\n\nType predicate function is a function which returns `true` if a given value is\nexpected type. For example, `isString` (or `is.String`) returns `true` if a\ngiven value is `string`.\n\n```typescript\nimport { is } from \"@core/unknownutil\";\n\nconst a: unknown = \"Hello\";\nif (is.String(a)) {\n  // 'a' is 'string' in this block\n}\n```\n\nFor more complex types, you can use `is*Of` (or `is.*Of`) functions and `as*`\n(or `as.*`) like:\n\n```typescript\nimport { as, is, PredicateType } from \"@core/unknownutil\";\n\nconst isArticle = is.ObjectOf({\n  title: is.String,\n  body: is.String,\n  refs: is.ArrayOf(\n    is.UnionOf([\n      is.String,\n      is.ObjectOf({\n        name: is.String,\n        url: is.String,\n      }),\n    ]),\n  ),\n  createTime: as.Optional(is.InstanceOf(Date)),\n  updateTime: as.Optional(is.InstanceOf(Date)),\n});\n\n// Infer the type of `Article` from the definition of `isArticle`\ntype Article = PredicateType\u003ctypeof isArticle\u003e;\n\nconst a: unknown = {\n  title: \"Awesome article\",\n  body: \"This is an awesome article\",\n  refs: [{ name: \"Deno\", url: \"https://deno.land/\" }, \"https://github.com\"],\n};\nif (isArticle(a)) {\n  // a is narrowed to the type of `isArticle`\n  console.log(a.title);\n  console.log(a.body);\n  for (const ref of a.refs) {\n    if (is.String(ref)) {\n      console.log(ref);\n    } else {\n      console.log(ref.name);\n      console.log(ref.url);\n    }\n  }\n}\n```\n\nAdditionally, you can manipulate the predicate function returned from\n`isObjectOf` with `isPickOf`, `isOmitOf`, `isPartialOf`, and `isRequiredOf`\nsimilar to TypeScript's `Pick`, `Omit`, `Partial`, `Required` utility types.\n\n```typescript\nimport { as, is } from \"@core/unknownutil\";\n\nconst isArticle = is.ObjectOf({\n  title: is.String,\n  body: is.String,\n  refs: is.ArrayOf(\n    is.UnionOf([\n      is.String,\n      is.ObjectOf({\n        name: is.String,\n        url: is.String,\n      }),\n    ]),\n  ),\n  createTime: as.Optional(is.InstanceOf(Date)),\n  updateTime: as.Optional(is.InstanceOf(Date)),\n});\n\nconst isArticleCreateParams = is.PickOf(isArticle, [\"title\", \"body\", \"refs\"]);\n// is equivalent to\n//const isArticleCreateParams = is.ObjectOf({\n//  title: is.String,\n//  body: is.String,\n//  refs: is.ArrayOf(\n//    is.UnionOf([\n//      is.String,\n//      is.ObjectOf({\n//        name: is.String,\n//        url: is.String,\n//      }),\n//    ]),\n//  ),\n//});\n\nconst isArticleUpdateParams = is.OmitOf(isArticleCreateParams, [\"title\"]);\n// is equivalent to\n//const isArticleUpdateParams = is.ObjectOf({\n//  body: is.String,\n//  refs: is.ArrayOf(\n//    is.UnionOf([\n//      is.String,\n//      is.ObjectOf({\n//        name: is.String,\n//        url: is.String,\n//      }),\n//    ]),\n//  ),\n//});\n\nconst isArticlePatchParams = is.PartialOf(isArticleUpdateParams);\n// is equivalent to\n//const isArticlePatchParams = is.ObjectOf({\n//  body: as.Optional(is.String),\n//  refs: as.Optional(is.ArrayOf(\n//    is.UnionOf([\n//      is.String,\n//      is.ObjectOf({\n//        name: is.String,\n//        url: is.String,\n//      }),\n//    ]),\n//  )),\n//});\n\nconst isArticleAvailableParams = is.RequiredOf(isArticle);\n// is equivalent to\n//const isArticlePutParams = is.ObjectOf({\n//  body: is.String,\n//  refs: is.ArrayOf(\n//    is.UnionOf([\n//      is.String,\n//      is.ObjectOf({\n//        name: is.String,\n//        url: is.String,\n//      }),\n//    ]),\n//  ),\n//  createTime: is.InstanceOf(Date),\n//  updateTime: is.InstanceOf(Date),\n//});\n```\n\nIf you need an union type or an intersection type, use `isUnionOf` and\n`isIntersectionOf` like:\n\n```typescript\nimport { is } from \"@core/unknownutil\";\n\nconst isFoo = is.ObjectOf({\n  foo: is.String,\n});\n\nconst isBar = is.ObjectOf({\n  bar: is.String,\n});\n\nconst isFooOrBar = is.UnionOf([isFoo, isBar]);\n// { foo: string } | { bar: string }\n\nconst isFooAndBar = is.IntersectionOf([isFoo, isBar]);\n// { foo: string } \u0026 { bar: string }\n```\n\n### assert\n\nThe `assert` function does nothing if a given value is expected type. Otherwise,\nit throws an `AssertError` exception like:\n\n```typescript\nimport { assert, is } from \"@core/unknownutil\";\n\nconst a: unknown = \"Hello\";\n\n// `assert` does nothing or throws an `AssertError`\nassert(a, is.String);\n// a is now narrowed to string\n\n// With custom message\nassert(a, is.String, { message: \"a must be a string\" });\n```\n\n### ensure\n\nThe `ensure` function return the value as-is if a given value is expected type.\nOtherwise, it throws an `AssertError` exception like:\n\n```typescript\nimport { ensure, is } from \"@core/unknownutil\";\n\nconst a: unknown = \"Hello\";\n\n// `ensure` returns `string` or throws an `AssertError`\nconst _: string = ensure(a, is.String);\n\n// With custom message\nconst __: string = ensure(a, is.String, { message: \"a must be a string\" });\n```\n\n### maybe\n\nThe `maybe` function return the value as-is if a given value is expected type.\nOtherwise, it returns `undefined` that suites with\n[nullish coalescing operator (`??`)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing)\nlike:\n\n```typescript\nimport { is, maybe } from \"@core/unknownutil\";\n\nconst a: unknown = \"Hello\";\n\n// `maybe` returns `string | undefined` so it suites with `??`\nconst _: string = maybe(a, is.String) ?? \"default value\";\n```\n\n## License\n\nThe code follows MIT license written in [LICENSE](./LICENSE). Contributors need\nto agree that any modifications sent in this repository follow the license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsr-core%2Funknownutil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjsr-core%2Funknownutil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsr-core%2Funknownutil/lists"}