{"id":16848746,"url":"https://github.com/etianen/js-types","last_synced_at":"2025-03-18T07:43:22.845Z","repository":{"id":57112168,"uuid":"51919620","full_name":"etianen/js-types","owner":"etianen","description":"Runtime type checking of untrusted data.","archived":false,"fork":false,"pushed_at":"2016-04-19T11:42:47.000Z","size":38,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-25T08:20:30.851Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/etianen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-17T12:04:23.000Z","updated_at":"2016-02-17T13:03:02.000Z","dependencies_parsed_at":"2022-08-21T10:31:10.487Z","dependency_job_id":null,"html_url":"https://github.com/etianen/js-types","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etianen%2Fjs-types","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etianen%2Fjs-types/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etianen%2Fjs-types/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etianen%2Fjs-types/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/etianen","download_url":"https://codeload.github.com/etianen/js-types/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244181356,"owners_count":20411601,"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-10-13T13:12:27.097Z","updated_at":"2025-03-18T07:43:22.817Z","avatar_url":"https://github.com/etianen.png","language":"TypeScript","readme":"# @etianen/types\n\nRuntime type checking of untrusted data.\n\n\n## Installing\n\n``` bash\nnpm install '@etianen/types'\n```\n\n**TypeScript:** To take advantage of typings, be sure to set `moduleResolution` to `\"node\"` in your `tsconfig.json`.\n\n\n## Overview\n\nWhen receiving JSON data from an untrusted source, it's tempting to just assume the data is of the expected type and shape. This can lead to confusing errors appearing deep in your code.\n\n@etianen/types provides a mechanism to check that untrusted data is the correct shape, or throw a useful debugging error.\n\n``` ts\nimport {numberType, arrayOf, ValueError, fromJSON} from \"@etianen/types\";\n\nconst numberArrayType = arrayOf(numberType);\nnumberArrayType.isTypeOf([1]);  // =\u003e true\nnumberArrayType.isTypeOf([\"foo\"]);  // =\u003e false\nnumberArrayType.isTypeOf(true);  // =\u003e false\n\ntry {\n    const trustedValue = fromJSON(untrustedString);\n} catch (ex) {\n    if (ex instanceof ValueError) {\n        console.log(ex.toString());\n    }\n}\n```\n\n\n## API\n\n### fromJS()\n\nCasts `value` to `Type`, or throws a `ValueError`.\n\n``` ts\nfromJS\u003cT\u003e(value: Object, type: Type\u003cT\u003e): T;\n```\n\n\n### fromJSON()\n\nParses `value` as JSON and casts to `Type`, or throws a `ValueError`.\n\n``` ts\nfromJSON\u003cT\u003e(value: string, type: Type\u003cT\u003e): T;\n```\n\n\n### Type\n\nA description of a runtime type.\n\n\n#### Type.isTypeOf()\n\nChecks that `value` is of this `Type`.\n\n``` ts\nType.isTypeOf\u003cT\u003e(value: Object): value is T;\n```\n\n\n#### Type.getName()\n\nReturns the descriptive name of `Type`.\n\n``` ts\nType.getName(): string;\n```\n\n\n#### Type.equals()\n\nPerforms a value equality check on two values of this `Type`.\n\n``` ts\nType.equals\u003cT\u003e(a: T, b: T): boolean;\n```\n\n\n### ValueError\n\nError thrown when a value is of the incorrect type.\n\n\n#### ValueError.message\n\nA description of the problem.\n\n``` ts\nValueError.message: string;\n```\n\n\n#### ValueError.stack\n\nA stack trace to the source of the problem.\n\n``` ts\nValueError.message: string;\n```\n\n\n#### ValueError.value\n\nThe value that caused the error.\n\n``` ts\nValueError\u003cT\u003e.value: T;\n```\n\n\n#### ValueError.toString\n\nA description of the problem, including the value that caused the error.\n\n``` ts\nValueError.toString(): string;\n```\n\n\n## Built-in types\n\nThe library of built-in types is designed to be as strict as possible, avoiding\nunexpected behavior deep within your code. This means:\n\n* A `Type` does not accept `null` unless explicitly allowed via `nullableOf()`.\n* A `Type` does not accept `undefined` unless explicitly allowed via `optionalOf()`.\n\n\n### stringType\n\nA `Type` representing `string`.\n\n```ts\nconst stringType: Type\u003cstring\u003e;\n```\n\n\n### numberType\n\nA `Type` representing `number`.\n\n```ts\nconst numberType: Type\u003cnumber\u003e;\n```\n\n\n### booleanType\n\nA `Type` representing `boolean`.\n\n```ts\nconst booleanType: Type\u003cboolean\u003e;\n```\n\n\n### anyType\n\nA `Type` representing any value that is not `null` or `undefined`.\n\n``` ts\nconst anyType: Type\u003cObject\u003e;\n```\n\n**Typescript note:** The `Object` type is used in place of `any` to avoid \"poisoning\" the rest of your codebase with cascading `any`. Use explicit type casts to convert `Object` to known types elsewhere in your codebase, or use `intersectionOf()` if multiple types are allowed.\n\n\n### `nullableOf()`\n\nA `Type` modifier representing a value that may be `null`.\n\n``` ts\nnullableOf\u003cT\u003e(value: Object): Type\u003cT\u003e;\n```\n\n\n### `optionalOf()`\n\nA `Type` modifier representing a value that may be `undefined`.\n\n``` ts\noptionalOf\u003cT\u003e(value: Object): Type\u003cT\u003e;\n```\n\n\n### `intersectionOf()`\n\nA `Type` modifier representing a value that must be either of two `Type`s.\n\n``` ts\nintersectionOf\u003cA, B\u003e(typeA: Type\u003cA\u003e, typeB: Type\u003cB\u003e): Type\u003cA | B\u003e;\n```\n\n\n### `unionOf()`\n\nA `Type` modifier representing a value must be both of two `Type`s.\n\n``` ts\nunionOf\u003cA, B\u003e(typeA: Type\u003cA\u003e, typeB: Type\u003cB\u003e): Type\u003cA \u0026 B\u003e;\n```\n\n\n### `arrayOf()`\n\nA container `Type` representing a homogenous array of another `Type`.\n\n``` ts\narrayOf\u003cT\u003e(valueType: Type\u003cT\u003e): Type\u003cArray\u003cT\u003e\u003e;\n```\n\n\n### `objectOf()`\n\nA container `Type` representing a homogenous object of another `Type`.\n\n``` ts\nobjectOf\u003cT\u003e(valueType: Type\u003cT\u003e): ObjectOf\u003cT\u003e;\n```\n\n\n### `tupleOf()`\n\nA container `Type` representing a heterogenous array of other `Type`s.\n\n``` ts\ntupleOf\u003cA\u003e(types: Array\u003cType\u003cA\u003e\u003e): Type\u003c[A]\u003e;\ntupleOf\u003cA, B\u003e(types: Array\u003cType\u003cA\u003e, Type\u003cB\u003e\u003e): Type\u003c[A, B]\u003e;\ntupleOf\u003cA, B, C\u003e(types: Array\u003cType\u003cA\u003e, Type\u003cB\u003e, Type\u003cC\u003e\u003e): Type\u003c[A, B, C]\u003e;\ntupleOf\u003cA, B, C, C\u003e(types: Array\u003cType\u003cA\u003e, Type\u003cB\u003e, Type\u003cC\u003e, Type\u003cD\u003e\u003e): Type\u003c[A, B, C, D]\u003e;\ntupleOf\u003cA, B, C, C, D\u003e(types: Array\u003cType\u003cA\u003e, Type\u003cB\u003e, Type\u003cC\u003e, Type\u003cD\u003e, Type\u003cE\u003e\u003e): Type\u003c[A, B, C, D, E]\u003e;\ntupleOf(types: Array\u003cType\u003cObject\u003e\u003e): Type\u003cArray\u003cObject\u003e\u003e\n```\n\n**Typescript note:** For tuples of more than 5 items, an explicit type cast will be required.\n\n``` ts\n// No explicit type cast required.\nconst smallTupleType: Type\u003c[string, string]\u003e = tupleOf([stringType, stringType]);\n\n// Explicit type cast required.\ntype BigTuple = [string, string, string, string, string, string];\nconst bigTupleType: Type\u003cBigTuple\u003e = tupleOf([stringType, stringType, stringType, stringType, stringType, stringType]) as Type[BigTuple];\n```\n\n\n### `shapeOf()`\n\nA container `Type` representing a heterogenous object of other `Type`s.\n\n``` ts\nshapeOf(types: ObjectOf\u003cType\u003cObject\u003e\u003e): Type\u003cObject\u003e;\n```\n\n**Typescript note:** Due to lack of support in the Typescript compiler, an explicit type cast is always required.\n\n``` ts\ninterface MyShape {\n    foo: string;\n    bar: number;\n}\n\n// Explicit type cast required.\nconst myShapeType: Type\u003cMyShape\u003e = shapeOf({\n    foo: stringType,\n    bar: stringType,\n}) as Type\u003cMyShape\u003e;\n```\n\n\n### `referenceOf()`\n\nA reference `Type`, representing a reference to another `Type`.\n\n``` ts\nreferenceOf\u003cT\u003e(getType: () =\u003e Type\u003cT\u003e): Type\u003cT\u003e;\n```\n\nUse this to implement circular references in `Type`s.\n\n``` js\nconst circularType = shapeOf({\n    title: stringType,\n    children: arrayOf(referenceOf(circularType)),\n});\n```\n\n\n## Build status\n\nThis project is built on every push using the Travis-CI service.\n\n[![Build Status](https://travis-ci.org/etianen/js-types.svg?branch=master)](https://travis-ci.org/etianen/js-types)\n\n\n## Support and announcements\n\nDownloads and bug tracking can be found at the [main project website](http://github.com/etianen/js-types).\n\n\n## More information\n\nThis project was developed by Dave Hall. You can get the code\nfrom the [project site](http://github.com/etianen/js-types).\n\nDave Hall is a freelance web developer, based in Cambridge, UK. You can usually\nfind him on the Internet:\n\n- [Website](http://www.etianen.com/)\n- [Google Profile](http://www.google.com/profiles/david.etianen)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fetianen%2Fjs-types","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fetianen%2Fjs-types","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fetianen%2Fjs-types/lists"}