{"id":26186652,"url":"https://github.com/socialaccess-network/isa","last_synced_at":"2026-04-22T00:31:20.536Z","repository":{"id":147208853,"uuid":"618122603","full_name":"socialaccess-network/isa","owner":"socialaccess-network","description":"A simple and lightweight library for creating and validating javascript variables. It is designed to be used with typescript, but can also be used with plain javascript.","archived":false,"fork":false,"pushed_at":"2023-12-05T23:20:11.000Z","size":26335,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-27T09:56:08.969Z","etag":null,"topics":["javascript","type-guards","typescript","validation","validation-library"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/socialaccess-network.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":"2023-03-23T19:54:59.000Z","updated_at":"2023-03-23T21:00:46.000Z","dependencies_parsed_at":"2025-03-11T23:37:49.163Z","dependency_job_id":null,"html_url":"https://github.com/socialaccess-network/isa","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/socialaccess-network/isa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socialaccess-network%2Fisa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socialaccess-network%2Fisa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socialaccess-network%2Fisa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socialaccess-network%2Fisa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/socialaccess-network","download_url":"https://codeload.github.com/socialaccess-network/isa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socialaccess-network%2Fisa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32115752,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T11:25:29.218Z","status":"ssl_error","status_checked_at":"2026-04-21T11:25:28.499Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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","type-guards","typescript","validation","validation-library"],"created_at":"2025-03-11T23:22:50.944Z","updated_at":"2026-04-22T00:31:20.531Z","avatar_url":"https://github.com/socialaccess-network.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @sa-net/isa\n\nA simple and lightweight library for creating and validating javascript variables. It is designed to be used with [typescript](https://www.typescriptlang.org/), but can also be used with plain javascript.\n\nIf using typescript, it requires version 5.0 or higher as it makes heavy use of `const` generics.\n\n## Installation\n\n```bash\nyarn add @sa-net/isa\n# or\nnpm install @sa-net/isa\n```\n\n## Examples\n\n### Basic usage\n\n```typescript\nimport { isa } from '@sa-net/isa';\n\nconst isaUser = isa.record({\n\tname: isa.string\n\tage: isa.number\n})\n\n// ...\n\nconst user: unknown = {\n\tname: 'John Doe',\n\tage: 42\n}\n\nif (isaUser(user)) {\n\t// user is now of type { name: string, age: number }\n\tconsole.log(user.name, user.email)\n}\n```\n\n### Unions and Intersections\n\nisa checks can be combined using `isa.union` and `isa.intersection` to create more complex checks.\n\n```typescript\nconst hasName = isa.record({\n\tname: isa.string,\n})\n\nconst hasAge = isa.record({\n\tage: isa.number,\n})\n\n// has type { name: string } | { age: number }\nconst hasNameOrAge = isa.union(hasName, hasAge)\n\n// has type\n// { name: string, age: number }\nconst hasNameAndAge = isa.intersection(hasName, hasAge)\n```\n\n### Optional and Nullable\n\nisa checks can be made optional or nullable using `isa.optional` and `isa.nullable`.\n\n```typescript\n// has type { name: Optional\u003cstring\u003e, age: Nullable\u003cnumber\u003e }\nconst isUser = isa.record({\n\tname: isa.optional(isa.string),\n\tage: isa.nullable(isa.number),\n})\n```\n\nNotice with optional how the `name` property in the previous example does not have a `?:`. This means typescript is expecting the `name` property to exist on the object, but it can be `undefined`.\n\n`isa.record` will still validate records missing a `name` property provided the check for it allows `undefined` as a value.\n\nThis is a current limitation of isa, but hopefully will be fixed in the future by looking for properties with the `Optional` type.\n\nTo get around this currently, you can provide a type to the `isa.record` function.\n\n```typescript\n// has type { name?: Optional\u003cstring\u003e }\nconst isUser = isa.record\u003c{ name?: Optional\u003cstring\u003e }\u003e({\n\tname: isa.optional(isa.string),\n})\n```\n\n### Combining isa checks\n\n```typescript\nconst hasName = isa.record({\n\tname: isa.string\n})\n\nconst hasAge = isa.record({\n\tage: isa.number\n})\n\n// has type { name: string, age: number }\nconst hasNameAndAge = isa.intersection(hasName, hasAge)\n\n// has type\n// { name: string, age: number, roles: Array\u003c'admin' | 'user'\u003e }\nconst isUser = isa.intersection(hasNameAndAge, isa.record({\n\troles: isa.array(isa.exact('admin'), isa.exact('user'))\n}))\n\n// has type\n// { msgs: Array\u003cstring\u003e | string, user: Nullable\u003c{ name: string, age: number, roles: Array\u003c'admin' | 'user'\u003e }\u003e }\nconst isData = isa.record({\n\tmsgs: isa.union(isa.array(isa.string), isa.string)\n\tuser: isa.nullable(isUser)\n})\n```\n\n## Custom isa functions\n\nisa functions are just typescript type guards. However, a utility function is provided that can be used to create type guards with a additional `@` type-only property that can be used to get the type of what the type guard is checking for.\n\n```typescript\nimport { checkFor, IsaType } from '@sa-net/isa'\n\nclass User {\n\tdeclare name: string\n}\n\nexport const isaUser = checkFor\u003cUser\u003e(value =\u003e value instanceof User)\n\n// User\ntype ExtractedType = IsaType\u003ctypeof isaUser\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocialaccess-network%2Fisa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsocialaccess-network%2Fisa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocialaccess-network%2Fisa/lists"}