{"id":13463702,"url":"https://github.com/gcanti/tcomb","last_synced_at":"2025-03-25T09:30:59.795Z","repository":{"id":18093378,"uuid":"21159390","full_name":"gcanti/tcomb","owner":"gcanti","description":"Type checking and DDD for JavaScript","archived":true,"fork":false,"pushed_at":"2019-05-12T10:01:36.000Z","size":2112,"stargazers_count":1893,"open_issues_count":31,"forks_count":120,"subscribers_count":43,"default_branch":"master","last_synced_at":"2024-10-29T16:19:37.502Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/gcanti.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-06-24T09:32:26.000Z","updated_at":"2024-05-21T21:32:52.000Z","dependencies_parsed_at":"2022-08-31T08:41:33.204Z","dependency_job_id":null,"html_url":"https://github.com/gcanti/tcomb","commit_stats":null,"previous_names":[],"tags_count":69,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gcanti%2Ftcomb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gcanti%2Ftcomb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gcanti%2Ftcomb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gcanti%2Ftcomb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gcanti","download_url":"https://codeload.github.com/gcanti/tcomb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245435069,"owners_count":20614823,"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-07-31T14:00:26.819Z","updated_at":"2025-03-25T09:30:59.292Z","avatar_url":"https://github.com/gcanti.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","General Programming"],"sub_categories":["Angular"],"readme":"[![build status](https://img.shields.io/travis/gcanti/tcomb/master.svg?style=flat-square)](https://travis-ci.org/gcanti/tcomb)\n[![dependency status](https://img.shields.io/david/gcanti/tcomb.svg?style=flat-square)](https://david-dm.org/gcanti/tcomb)\n![npm downloads](https://img.shields.io/npm/dm/tcomb.svg)\n\n\u003e \"Si vis pacem, para bellum\" - (Vegetius 5th century)\n\ntcomb is a library for Node.js and the browser which allows you to **check the types** of JavaScript values at runtime with a simple and concise syntax. It's great for **Domain Driven Design** and for adding safety to your internal code.\n\n# TypeScript / Flowtype users\n\nYou may want to check out [io-ts](https://github.com/gcanti/io-ts)\n\n# IMPORTANT: Running in production\n\ntcomb is supposed to be used in **development** and is **disabled in production**. \nIf you want type checks in production you may use \n- [tcomb-validation](https://github.com/gcanti/tcomb-validation)\n- [io-ts](https://github.com/gcanti/io-ts)\n\n# Setup\n\n```sh\nnpm install tcomb --save\n```\n\n**Code example**\n\nA type-checked function:\n\n```js\nimport t from 'tcomb';\n\nfunction sum(a, b) {\n  t.Number(a);\n  t.Number(b);\n  return a + b;\n}\n\nsum(1, 's'); // throws '[tcomb] Invalid value \"s\" supplied to Number'\n\n// using babel-plugin-tcomb\nfunction sum(a: number, b: number) {\n  return a + b;\n}\n```\n\nA user defined type:\n\n```js\nconst Integer = t.refinement(t.Number, (n) =\u003e n % 1 === 0, 'Integer');\n```\n\nA type-checked class:\n\n```js\nconst Person = t.struct({\n  name: t.String,              // required string\n  surname: t.maybe(t.String),  // optional string\n  age: t.Integer,                // required integer\n  tags: t.list(t.String)       // a list of strings\n}, 'Person');\n\n// methods are defined as usual\nPerson.prototype.getFullName = function () {\n  return `${this.name} ${this.surname}`;\n};\n\nconst person = Person({\n  surname: 'Canti'\n}); // throws '[tcomb] Invalid value undefined supplied to Person/name: String'\n```\n\nChrome DevTools:\n\n![throws](docs/images/throws.png)\n\n# Docs\n\n- [API](docs/API.md)\n- [A little guide to runtime type checking and runtime type introspection](docs/GUIDE.md) (Work in progress)\n\n# Features\n\n**Lightweight**\n\n3KB gzipped, no dependencies.\n\n**Type safety**\n\nAll models defined with `tcomb` are type-checked.\n\n**Note**. Instances *are not boxed*, this means that `tcomb` works great with lodash, Ramda, etc. And you can of course use them as props to React components.\n\n**Based on set theory**\n\n- Blog post: [JavaScript, Types and Sets - Part I](https://gcanti.github.io/2014/09/29/javascript-types-and-sets.html)\n- Blog post: [JavaScript, Types and Sets - Part II](https://gcanti.github.io/2014/10/07/javascript-types-and-sets-part-II.html)\n\n**Domain Driven Design**\n\nWrite complex domain models in a breeze and with a small code footprint. Supported types / combinators:\n\n* user defined types\n* structs\n* lists\n* enums\n* refinements\n* unions\n* intersections\n* the option type\n* tuples\n* dictionaries\n* functions\n* recursive and mutually recursive types\n* interfaces\n\n**Immutability and immutability helpers**\n\nInstances are immutable using `Object.freeze`. This means you can use standard JavaScript objects and arrays. You don't have to change how you normally code. You can update an immutable instance with the provided `update(instance, spec)` function:\n\n```js\nconst person2 = Person.update(person, {\n  name: { $set: 'Guido' }\n});\n```\n\nwhere `spec` is an object containing *commands*. The following commands are compatible with the [Facebook Immutability Helpers](http://facebook.github.io/react/docs/update.html):\n\n* `$push`\n* `$unshift`\n* `$splice`\n* `$set`\n* `$apply`\n* `$merge`\n\nSee [Updating immutable instances](docs/API.md#updating-immutable-instances) for details.\n\n**Speed**\n\n`Object.freeze` calls and asserts are executed only in development and stripped out in production (using `process.env.NODE_ENV !== 'production'` tests).\n\n**Runtime type introspection**\n\nAll models are inspectable at runtime. You can read and reuse the information stored in your types (in the `meta` static member). See [The meta object](docs/GUIDE.md#the-meta-object) in the docs for details.\n\nLibraries exploiting tcomb's RTI:\n\n- [tcomb-validation](https://github.com/gcanti/tcomb-validation)\n- [tcomb-form](https://github.com/gcanti/tcomb-form)\n- Blog post: [JSON API Validation In Node.js](https://gcanti.github.io/2014/09/15/json-api-validation-in-node.html)\n\n**Easy JSON serialization / deserialization**\n\nEncodes / decodes your domain models to / from JSON for free.\n- Blog post: [JSON Deserialization Into An Object Model](https://gcanti.github.io/2014/09/12/json-deserialization-into-an-object-model.html)\n\n**Debugging with Chrome DevTools**\n\nYou can customize the behavior when an assert fails leveraging the power of Chrome DevTools.\n\n```js\n// use the default...\nt.fail = function fail(message) {\n  throw new TypeError('[tcomb] ' + message); // set \"Pause on exceptions\" on the \"Sources\" panel for a great DX\n};\n\n// .. or define your own behavior\nt.fail = function fail(message) {\n  console.error(message);\n};\n```\n\n**Pattern matching**\n\n```js\nconst result = t.match(1,\n  t.String, () =\u003e 'a string',\n  t.Number, () =\u003e 'a number'\n);\n\nconsole.log(result); // =\u003e 'a number'\n```\n\n**Babel plugin**\n\nUsing [babel-plugin-tcomb](https://github.com/gcanti/babel-plugin-tcomb) you can also write (Flow compatible) type annotations:\n\n```js\nfunction sum(a: number, b: number): number {\n  return a + b;\n}\n```\n\n**TypeScript definition file**\n\n[index.d.ts](index.d.ts)\n\n# Contributors\n\n- [Giulio Canti](https://github.com/gcanti) maintainer\n- [Becky Conning](https://github.com/beckyconning) `func` combinator ideas and documentation\n- [Andrea Lattuada](https://github.com/utaal) `declare` combinator\n\n# How to Build a standalone bundle\n\n```sh\ngit clone git@github.com:gcanti/tcomb.git\ncd tcomb\nnpm install\nnpm run dist\n```\n\nWill output 2 files:\n\n- `dist/tcomb.js` (development)\n- `dist/tcomb.min.js` (production) `Object.freeze` calls and asserts stripped out\n\n# Related libraries\n\n* [tcomb-doc](https://github.com/gcanti/tcomb-doc) Documentation tool for tcomb\n* [tcomb-validation](https://github.com/gcanti/tcomb-validation) Validation library based on type combinators\n* [tcomb-json-schema](https://github.com/gcanti/tcomb-json-schema) Transforms a JSON Schema to a tcomb type\n* [reactuate](https://github.com/reactuate/reactuate) React/Redux stack (not a boilerplate kit)\n* [tcomb-react](https://github.com/gcanti/tcomb-react) Alternative syntax for PropTypes\n* [mongorito-tcomb](https://github.com/xouabita/mongorito-tcomb) Bring schema validation to Mongorito thanks to tcomb\n* [tcomb-form](https://github.com/gcanti/tcomb-form) Forms library for react\n* [tcomb-form-types](https://github.com/Industrial/tcomb-form-types) Adds Types/Validations to tcomb-form\n* [tcomb-form-native](https://github.com/gcanti/tcomb-form-native) Forms library for react-native\n* [tcomb-generate](https://github.com/typeetfunc/tcomb-generate) Generates random data by tcomb type for property-based testing\n* [tcomb-additional-types](http://github.com/eserozvataf/tcomb-additional-types) Provides additional predefined types for your existing tcomb setup\n* [tcomb-builder](https://github.com/cadre/tcomb-builder) An immutable syntax for defining tcomb types and forms\n\n# Similar projects\n\n* [typed-immutable](https://github.com/Gozala/typed-immutable)\n* [immu](https://github.com/scottcorgan/immu)\n* [immutable](https://github.com/facebook/immutable-js)\n* [mori](https://github.com/swannodette/mori)\n* [seamless-immutable](https://github.com/rtfeldman/seamless-immutable)\n* [deep-freeze](https://www.npmjs.com/package/deep-freeze)\n* [freezer](https://github.com/arqex/freezer)\n* [icedam](https://github.com/winkler1/icedam)\n* [ObjectModel](https://github.com/sylvainpolletvillard/ObjectModel)\n* [rfx](https://github.com/ericelliott/rfx)\n\n# License\n\nThe MIT License (MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgcanti%2Ftcomb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgcanti%2Ftcomb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgcanti%2Ftcomb/lists"}