{"id":14155558,"url":"https://github.com/javascript-studio/schema","last_synced_at":"2025-04-14T01:40:21.067Z","repository":{"id":40548897,"uuid":"141799701","full_name":"javascript-studio/schema","owner":"javascript-studio","description":"🧩 Plain JavaScript objects with runtime type guarantees","archived":false,"fork":false,"pushed_at":"2025-01-23T09:17:08.000Z","size":1461,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T15:06:26.671Z","etag":null,"topics":["json","schema","type-checking","validation"],"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/javascript-studio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","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":"2018-07-21T09:40:39.000Z","updated_at":"2025-01-23T09:17:12.000Z","dependencies_parsed_at":"2024-04-09T09:52:07.502Z","dependency_job_id":"a13985e9-35af-4ac1-b255-7fdc50ccef4d","html_url":"https://github.com/javascript-studio/schema","commit_stats":{"total_commits":269,"total_committers":2,"mean_commits":134.5,"dds":"0.0074349442379182396","last_synced_commit":"d00cb7cf1bf9f1598f3193454e7772c99687547b"},"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javascript-studio%2Fschema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javascript-studio%2Fschema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javascript-studio%2Fschema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javascript-studio%2Fschema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/javascript-studio","download_url":"https://codeload.github.com/javascript-studio/schema/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248809038,"owners_count":21164893,"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":["json","schema","type-checking","validation"],"created_at":"2024-08-17T08:03:55.911Z","updated_at":"2025-04-14T01:40:21.048Z","avatar_url":"https://github.com/javascript-studio.png","language":"JavaScript","funding_links":[],"categories":["json"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  Studio Schema\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  🧩 Plain JavaScript objects with runtime type guarantees. For node and\n  browsers.\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/javascript-studio/schema/actions\"\u003e\n    \u003cimg src=\"https://github.com/javascript-studio/schema/workflows/Build/badge.svg\" alt=\"Build Status\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@studio/schema\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/@studio/schema.svg\" alt=\"npm Version\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-MIT-brightgreen.svg\" alt=\"License\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## Usage\n\nDefining a schema:\n\n```js\nconst { schema, object, string, integer, opt } = require('@studio/schema');\n\n/**\n * @typedef {ReturnType\u003ctypeof person\u003e} Person\n */\nconst person = schema(\n  object({\n    name: string, // mandatory\n    age: opt(integer) // optional\n  })\n);\n```\n\n### Schema Validation\n\nThe schema is a function that can be used to validate a given object. It throws\nif non-optional properties are missing, a value has the wrong type, or\nundeclared properties are present.\n\n```js\nperson({ name: 123 }); // throws\nperson({ name: 'Test', customer: true }); // throws\nperson({ name: 'Test', age: true }); // throws\nperson({ name: 'Test', age: 7.5 }); // throws\n\nperson({ name: 'Test' }); // ok\nperson({ name: 'Test', age: 7 }); // ok\n```\n\n### Validators\n\nValidators are functions that verify values and objects. A validator function\nreturns `false` if a value doesn't meet the expectation. Studio Schema comes\nwith a set of pre-defined validators for primitive types, enums, objects,\narrays and maps. Validators can be nested and reused:\n\n```js\nconst { schema, literal, string, object, array } = require('@studio/schema');\n\nconst status = literal('LOADING', 'LOADED', 'SAVING', 'SAVED');\nconst person = object({\n  first_name: string,\n  last_name: string,\n  tags: array(string)\n});\n\n/**\n * @typedef {import('@studio/schema').Infer\u003ctypeof personModel\u003e} PersonModel\n */\nconst personModel = schema(object({ status, person }));\n```\n\n### Readers\n\nA reader validates a given object and returns a [Proxy][1] that makes the\nobject read-only and verifies that only defined properties are accessed.\n\n```js\nconst person = person.read({ name: 'Test', age: 7 });\n\nconst name = person.name; // ok\nconst age = person.age; // ok\nconst customer = person.customer; // throws\nperson.name = 'Changed'; // throws\n```\n\n### Writers\n\nA writer accepts an empty or partial object and returns a [Proxy][1] that\nvalidates any accessed, assigned or deleted properties. To verify that no\nnon-optional properties are missing, use `mySchema.verify(writer)`.\n\n```js\nconst alice = person.write({ name: 'Alice' });\n\nalice.customer = true; // throws\nalice.name = 'Changed'; // ok\nalice.age = 7; // ok\n```\n\n### Errors\n\nAll schema validation errors have a `code` property with the value\n`E_SCHEMA`.\n\n### Types\n\nValidators and schemas creates TypeScript types from the given structure.\nResolve the types like this:\n\n```js\n/**\n * @typedef {import('@studio/schema').Infer\u003ctypeof mySchema\u003e} MySchema\n */\nconst mySchema = schema(someValidator);\n\n/**\n * @typedef {import('@studio/schema').Infer\u003ctypeof myLiteral\u003e} MyLiteral\n */\nconst myLiteral = literal('foo', 'bar');\n```\n\n## API\n\nThis module exports the `schema` function which carries the entire API, so you\ncan require it in two ways:\n\n```js\nconst schema = require('@studio/schema');\n\nconst person = schema({ name: schema.string });\n```\n\nWith [destructuring][2]:\n\n```js\nconst { schema, string } = require('@studio/schema');\n\nconst person = schema({ name: string });\n```\n\n- `schema(validator[, options])`: Returns a new schema with the given validator.\n  `validator` The validator to use for the schema. These options are supported:\n  - `error_code`: The `code` property to define on errors. Defaults to\n    `E_SCHEMA`.\n- `defined`: Is a validator that accepts any value other than `undefined`.\n- `boolean`: Is a validator that accepts `true` and `false`.\n- `number`: Is a validator that accepts finite number values.\n- `number.min(min)`: Is a validator that accepts finite number values \u003e= `min`.\n- `number.max(max)`: Is a validator that accepts finite number values \u003c= `max`.\n- `number.range(min, max)`: Is a validator that accepts finite number values \u003e=\n  `min` and \u003c= `max`.\n- `integer`: Is a validator that accepts finite integer values.\n- `integer.min(min)`: Is a validator that accepts finite integer values \u003e=\n  `min`.\n- `integer.max(max)`: Is a validator that accepts finite integer values \u003c=\n  `max`.\n- `integer.range(min, max)`: Is a validator that accepts finite integer values\n  \u003e = `min` and \u003c= `max`.\n- `string`: Is a validator that accepts string values.\n- `string.regexp(re)`: Is a validator that accepts string values matching the\n  given regular expression.\n- `string.length.{min,max,range}`: Verifies the string length with an integer\n  validator.\n- `literal(value_1, value_2, ...)`: Returns a validator that matches against a\n  list of primitive values. Can be used to define constants or enumerations.\n- `all(validator_1, validator_2, ...)`: Returns a validator where all of the\n  given validators have to match.\n- `one(validator_1, validator_2, ...)`: Returns a validator where one of the\n  given validators has to match.\n- `opt(validator)`: Returns an optional validator.\n- `object(properties)`: Returns an object validator. The given object maps\n  object keys to validators.\n- `object.any`: Is a validator that accepts arbitrary object values.\n- `array(itemValidator)`: Returns an array. Each element in the array has to\n  match the given validator..\n- `array.any`: Is a validator that accepts arbitrary array values.\n- `map(keyValidator, valueValidator)`: Returns a map validator for key-value\n  pairs where `keyValidator` and `valueValidator` are the validators for the\n  object key and value pairs.\n- `validator(test[, toString])`: Creates a custom validator for the given\n  `test` function. The optional `toString` argument can be a function that\n  returns a string, or a string defining the validator name used in error\n  messages. Defaults to `\u003ccustom validator\u003e`.\n- `E_SCHEMA`: The `code` property exposed on schema validation errors.\n\nNote that all validator functions are also exposed on `schema`.\n\n## Schema API\n\nThe schema created by `schema(validator)` is a function that throws a\n`TypeError` if the given value does not match the validator, and returns the\nvalue otherwise. For `object` and `array`, the schema also allows to create\nproxy objects that validate reading, assigning and deleting properties:\n\n- `reader = mySchema.read(data[, options])`: Creates a schema compliant reader\n  for the given data. If the given data does not match the schema, an exception\n  is thrown. The returned reader throws on any property modification or on an\n  attempt to read an undefined property. These options are supported:\n  - `error_code`: The `code` property to define on errors. Defaults to\n    `E_SCHEMA`.\n- `writer = mySchema.write([data[, options]])`: Creates a writer with optional\n  initial data. If the given data does not match the schema, an exception is\n  thrown. The returned writer throws on undefined property modification, if an\n  assigned value is invalid, or on an attempt to read an undefined property.\n  These options are supported:\n  - `error_code`: The `code` property to define on errors. Defaults to\n    `E_SCHEMA`.\n- `data = mySchema.verify(writer)`: Checks if any properties are missing in the\n  given writer and returns the unwrapped data. Throws if the given object is\n  not a schema writer.\n- `data = reader_or_writer.toJSON()`: returns the original object.\n\nNote that schema readers and writers can be safely used with `JSON.stringify`.\n\n## License\n\nMIT\n\n\u003cp align=\"center\"\u003eMade with ❤️ on 🌍\u003cp\u003e\n\n[1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy\n[2]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjavascript-studio%2Fschema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjavascript-studio%2Fschema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjavascript-studio%2Fschema/lists"}