{"id":20147270,"url":"https://github.com/voodooattack/txjson","last_synced_at":"2025-04-09T19:35:53.331Z","repository":{"id":154119178,"uuid":"631862731","full_name":"voodooattack/txjson","owner":"voodooattack","description":"An extension of JSON5 with rich inline type information.","archived":false,"fork":false,"pushed_at":"2025-03-10T09:26:40.000Z","size":2154,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-06T15:55:38.414Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voodooattack.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-04-24T08:11:05.000Z","updated_at":"2025-03-10T09:26:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"a79dce4a-3283-4784-83f4-8f7cc9eecf04","html_url":"https://github.com/voodooattack/txjson","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voodooattack%2Ftxjson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voodooattack%2Ftxjson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voodooattack%2Ftxjson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voodooattack%2Ftxjson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voodooattack","download_url":"https://codeload.github.com/voodooattack/txjson/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247526746,"owners_count":20953143,"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-11-13T22:28:16.357Z","updated_at":"2025-04-09T19:35:53.298Z","avatar_url":"https://github.com/voodooattack.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm version](https://badge.fury.io/js/txjson.svg)](https://badge.fury.io/js/txjson)\n\n# TxJSON\n\n\u003e An extension of JSON5 with rich inline type information.\n\nTxJSON allows you to define typed values and define deserialisers for said values at runtime.\n\nSyntax:\n\n```js\n{\n  x: date \"2001-01-01\", // it can handle custom deserializers!\n  y: 123n, // it can handle `BigInt` out of the box!\n  z: /^I\\sCAN\\sPARSE\\sREGEX$/im, // ...and also regular expressions!\n  backquote: `Hello\nWorld!`, // multi-line template strings are supported! (sans placeholders)\n  w: undefined, // ...and even `undefined`!\n}\n```\n\nPerfect for configuration files and programmatic generation of tests!\n\n### Schema\n\nPerhaps, the best example of a TxJSON document is a TxJSON schema:\n\n```js\nschema {\n  /// Use `:document` to restrict the type of a document's root.\n  \":document\": arrayOf Place,\n  // a literal object signature\n  Place: object {\n    // `id` can be a string or a number\n    id: oneOf [string, number],\n    name: string,\n    cat: Category,\n    // `maybe` makes the following type optional (e.g can be `undefined` or `null`)\n    description: maybe string,\n    coords: maybe oneOf [arrayOf Point, Point],\n    region: arrayOf Point,\n    address: maybe string,\n    phone: maybe string,\n    // `tags` is a dynamic string array of any length.\n    tags: maybe arrayOf string,\n    // You can pass literal values to match against. This can be used to define enums with `oneOf`!\n    status: oneOf [\"published\", \"private\", \"hidden\"],\n  },\n  Category: oneOf [\n    \"accomodation\",\n    \"shopping\",\n    \"parks_and_recreation\",\n    \"restaurant\",\n  ],\n  // Definition of a GeoJSON point.\n  Point: oneOf [\n    // A plain object.\n    object {\n      type: \"Point\", // A fixed string!\n      coordinates: arrayOf [number, number, maybe number], // A fixed array signature\n      bbox: maybe arrayOf [number, number, number, number], // `maybe` makes this field optional\n    },\n    // A class version of the same object.\n    class [number, number]\n  ],\n}\n```\n\n---\n\n## Prerequisites\n\nThis project requires NodeJS (version 8 or later) and NPM.\n[Node](http://nodejs.org/) and [NPM](https://npmjs.org/) are really easy to install.\nTo make sure you have them available on your machine,\ntry running the following command.\n\n```sh\n$ npm -v \u0026\u0026 node -v\n6.4.1\nv8.16.0\n```\n\nDuring development, you must have a version of Java installed, this is required by `antlr4ng` for use in generating the parser.\n\n---\n\n## Table of contents\n\n- [TxJSON](#TxJSON)\n  - [Prerequisites](#prerequisites)\n  - [Table of contents](#table-of-contents)\n  - [Getting Started](#getting-started)\n  - [Installation](#installation)\n  - [API](#api)\n    - [parse](#parse)\n    - [parseSchema](#parseSchema)\n    - [createSchema](#createSchema)\n  - [Contributing](#contributing)\n  - [Versioning](#versioning)\n  - [Authors](#authors)\n  - [License](#license)\n\n---\n\n## Getting Started\n\nThese instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.\n\n---\n\n## Installation\n\n**BEFORE YOU INSTALL:** please read the [prerequisites](#prerequisites)\n\nTo install and set up the library, run:\n\n```sh\n$ npm install txjson\n```\n\nOr if you prefer using Yarn:\n\n```sh\n$ yarn add txjson\n```\n\n---\n\n## API\n\n### parse\n\n```ts\nfunction parse\u003cT\u003e(\n  input: string,\n  schema?: Partial\u003cISchema\u003e,\n  fileName?: string\n): T\n```\n\nParses a TxJSON file and returns a JavaScript value.\n\n#### Arguments:\n\n`input: string`: The input to be parsed.\n\n`schema?: Partial\u003cISchema\u003e`\n\n| Field | Default value | Description |\n| --- | --- | --- |\n| `deserializers` | {...} | A mapping of `[name]: Deserializer` pairs |\n| `validators` | {...} | A mapping of `[name]: Validator` pairs |\n| `classes` | {...} | A mapping of user classes, constructible using the constructor syntax: `MyClass(x, y, z)` |\n| `prototypes` | {...} | A mapping of user classes, constructible using the prototype assignment syntax: `MyClass... { field1: \"value\", ... }` |\n| `preprocessors` | {...} | A mapping of user preprocessors, these will run before any validation occurs. |\n| `meta` | {...} | A dictionary to store user metadata. |\n\nIf no schema is supplied, this function will use the [default schema](#createSchema).\n\n`fileName?: string`: An optional file name to include in error messages.\n\nExample:\n\n```ts\n  import {parse} from \"txjson\";\n\n  parse(`12`);          // ok\n  parse(`int 12`);      // ok\n  parse(`float 12.3`);  // ok\n  parse(`int 12.3`);    // error!\n```\n\n### parseSchema\n\n```ts\nfunction parseSchema(\n  document: string,\n  baseSchema?: Schema,\n  schemaFileName?: string\n): Schema\n```\n\nParses a schema document.\n\n#### Arguments:\n\n`definition: string`: The schema string.\n\n`baseSchema?: Schema`: the original schema to extend/apply these definitions to. (optional)\n\n`schemaFileName?: string`: An optional file name to include in error messages.\n\nExample:\n```ts\n  import {parse, parseSchema} from \"txjson\";\n\n  const schema = parseSchema(`\n    schema {\n      intOrBigInt: oneOf [int, bigint],\n      optionalInt: maybe int,\n      strOrNumber: oneOf [string, number],\n      date: strOrNumber,\n      MyClass: class [string, number],\n      MyProto: proto {\n        a: string,\n        b: number,\n      },\n    }\n  `, {\n    classes: {\n      MyClass: class MyClass {\n        constructor(public a: string, public b: number) {}\n      }\n    },\n    prototypes: {\n      MyProto: class MyProto {\n        public a: string;\n        public b: number;\n      }\n    },\n    deserializers: {\n      'Date': (acc: ValueAccessor) =\u003e new Date(acc.rawValue),\n    }\n  })\n\n  parse(`intOrBigInt 1`) // ok\n  parse(`intOrBigInt int 1`) // ok\n  parse(`intOrBigInt bigint \"123\"`) // ok\n  parse(`intOrBigInt 123n`) // ok\n  parse(`intOrBigInt 13.3`) // error!\n\n  parse(`optionalInt null`) // ok\n  parse(`optionalInt 0`) // ok\n  parse(`optionalInt \"x\"`) // error!\n\n  parse(`date 0`) // ok!\n  parse(`date \"2001-01-01\"`) // ok!\n  parse(`date 123n`) // error!\n\n  parse(`MyClass(\"a\", 2)`) // ok!\n  parse(`MyClass(\"a\")`) // error, missing argument!\n  parse(`MyClass(1, 2)`) // error, invalid argument!\n  parse(`MyClass... {a: \"a\", b: 2}`) // error, not a proto!\n\n  parse(`MyProto... {a: \"a\", b: 2}`) // ok!\n  parse(`MyProto... {a: \"a\", b: 2, c: 212}`) // error, extra field!\n  parse(`MyProto... {a: 1, b: \"a\"}`) // error, invalid field!\n  parse(`MyProto... {a: 1}`) // error, missing field!\n  parse(`MyProto(\"a\", 2)`) // error, constructor call on proto is not supported!\n\n```\n\n### createSchema\n\n```ts\nfunction createSchema(\n  overrides?: Partial\u003cISchema\u003e\n): Schema\n```\n\nCreates a new schema with default types. (e.g `int`, `bigint`, `UInt8Array`, ...)\n\n#### Arguments:\n\n`overrides`: (optional) Pass another schema to override the defaults.\n\n---\n\n## Contributing\n\n1.  Fork it!\n2.  Create your feature branch: `git checkout -b my-new-feature`\n3.  Add your changes: `git add .`\n4.  Commit your changes: `git commit -am 'Add some feature'`\n5.  Push to the branch: `git push origin my-new-feature`\n6.  Submit a pull request :sunglasses:\n\n---\n\n## Versioning\n\nWe use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/voodooattack/txjson/tags).\n\n---\n## Authors\n\n* **Abdullah Ali** - *Initial work* - [GitHub](https://github.com/voodooattack)\n\nSee also the list of [contributors](https://github.com/your/project/contributors) who participated in this project.\n\n---\n## License\n\n[MIT License](https://andreasonny.mit-license.org/2019) © Abdullah Ali\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoodooattack%2Ftxjson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoodooattack%2Ftxjson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoodooattack%2Ftxjson/lists"}