{"id":13809025,"url":"https://github.com/jetify-com/tyson","last_synced_at":"2025-05-15T17:08:06.555Z","repository":{"id":177125343,"uuid":"657676804","full_name":"jetify-com/tyson","owner":"jetify-com","description":"🥊  TypeScript as a Configuration Language. TySON stands for TypeScript Object Notation","archived":false,"fork":false,"pushed_at":"2025-03-07T23:01:36.000Z","size":69,"stargazers_count":551,"open_issues_count":5,"forks_count":4,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-04-08T10:13:26.409Z","etag":null,"topics":["config","configuration","configuration-language","data","json","ts","tson","typescript","tyson"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jetify-com.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null}},"created_at":"2023-06-23T15:25:58.000Z","updated_at":"2025-03-08T07:22:47.000Z","dependencies_parsed_at":"2025-01-18T20:46:07.269Z","dependency_job_id":"3b229476-ba0a-4578-83b0-96a927c3345d","html_url":"https://github.com/jetify-com/tyson","commit_stats":null,"previous_names":["jetpack-io/tyson","jetify-com/tyson"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetify-com%2Ftyson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetify-com%2Ftyson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetify-com%2Ftyson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetify-com%2Ftyson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jetify-com","download_url":"https://codeload.github.com/jetify-com/tyson/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384988,"owners_count":22062422,"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":["config","configuration","configuration-language","data","json","ts","tson","typescript","tyson"],"created_at":"2024-08-04T01:01:58.383Z","updated_at":"2025-05-15T17:08:01.538Z","avatar_url":"https://github.com/jetify-com.png","language":"Go","funding_links":[],"categories":["Go","typescript"],"sub_categories":[],"readme":"# TySON (TypeScript Object Notation) 🥊\n\n### TypeScript as a Configuration Language\n\n## What is it?\n\nTySON (TypeScript Object Notation) is a subset of TypeScript, chosen to be useful as an\nembeddable configuration language that generates JSON.\nYou can think of TySON as **JSON + comments + types + basic logic** using\nTypeScript syntax. TySON files use the `.tson` extension.\n\nThe goal is to make it possible for _all major programming languages_ to read\nconfiguration written in TypeScript using _native libraries_. That is, a `go` program\nshould be able to read TySON using a `go` library, a `rust` program should be able to\nread TySON using a `rust` library, and so on. Our first implementation is written in pure\n`go`, and a `rust` implementation will follow.\n\nHere's an example `.tson` file:\n\n```typescript\n// example.tson\n{\n  // Single-line comments are supported\n  array_field: [1, 2, 3],\n  boolean_field: true,\n  /* As well as multi-line comments, and multi-line strings.\n   *\n   * Multi-line strings are TypeScript template literals, so they also support\n   * interpolation.\n   */\n  multi_line_string_field: `\n    line 1\n    line 2\n    line ${1 + 2}\n  `,\n  number_field: 123,\n  string_field: 'string',\n  object_field: {\n    // Notice that, unlike JSON, field names can be unquoted if they're a valid\n    // TypeScript identifier.\n    nested_field: \"nested\",\n  }, // Trailing commas are allowed\n}\n```\n\nThe above evaluates to the following JSON:\n\n```json\n{\n    \"array_field\": [1, 2, 3],\n    \"boolean_field\": true,\n    \"multi_line_string_field\": \"\\n    line 1\\n    line 2\\n    line 3\\n  \",\n    \"number_field\": 123,\n    \"object_field\": {\n        \"nested_field\": \"nested\"\n    },\n    \"string_field\": \"string\"\n}\n```\n\nTySON was originally developed by [jetify](https://www.jetify.com). We are exploring\nusing it as a configuration language for [Devbox](https://github.com/jetify-com/devbox).\n\n## Benefits of using TySON\n\n**Type safety**: Use TypeScript's type system to ensure that your configuration is valid.\n\n```typescript\ntype Config = {\n    // This field is required\n    required_field: string;\n    // This field is optional\n    optional_field?: number;\n};\n\n// When there are multiple expressions in a file, we need to `export default` the one\n// that should be evaluated as JSON:\nexport default {\n    optional_field: '1', // Type error: expected number, got string\n    rquired_field: 'bar', // This typo will be caught by the TypeScript compiler\n} satisfies Config;\n```\n\n**Programmable**: You can generate configuration programmatically.\nFor example, you can import and override values like this:\n\n```typescript\nimport otherConfig from './your_other_config.tson';\n\n// Import otherConfig and override some values:\nexport default {\n    ...otherConfig, // Spread operator is supported\n    valuesToOverride: 'values1',\n};\n```\n\nOr you can define functions and use them in your configuration:\n\n```typescript\n// We can write a function to help us generate configuration:\nfunction person(first_name: string, last_name: string) {\n    return {\n        first_name,\n        last_name,\n        full_name: `${first_name} ${last_name}`,\n    };\n}\n\nexport default {\n    people: [person('Alyssa', 'Hacker'), person('Ben', 'Bitdiddle')],\n};\n```\n\n**Nicer Syntax**: Unlike JSON, TypeScript supports comments, trailing commas,\nand multi-line strings, in addition to types and functions. Unlike languages\n`dhall`, `cue`, `jsonnet`, or `nickel`, you don't have to learn a new language\nif you're already familiar with TypeScript.\n\n**Editor Support**: Because TySON is a subset of TypeScript, your editor already\nsupports syntax highlighting, formatting and auto-completion for it.\nSimply configure your editor to treat `.tson` files as TypeScript files.\n\n## Why?\n\nAlmost all developer tools require some form of configuration. In our opinion,\nan ideal configuration language should be:\n\n-   **Easy to read and write by humans**\n-   **Easy to parse and generate by machines**\n-   **Type safe** - so that it's easy to validate the output\n-   **Programmable** – so that you can abstract complex configuration patterns\n    into reusable functions\n-   **Secure** - if we want programmable configuration, its execution should\n    not affect the application that loads it.\n-   **Have a well-understood syntax** - without major gotchas that can result in errors\n-   **Based on a widely used standard** – nobody wants to have to learn a new\n    language just to configure a tool\n-   **Easy to migrate to** - tools that already use JSON for configuration should\n    be able to gradually adopt the new language, while retaining compatibility\n    with existing JSON configuration files.\n\nTraditionally, the most popular choices for configuration have been: JSON, YAML\nor TOML, but they each have drawbacks:\n\n-   **JSON**: doesn't support comments, trailing commas, or multi-line strings.\n-   **YAML**: has an ambiguous syntax. For example the token `no` is interpreted\n    as a boolean, often in cases where you want it to be a string. See\n    https://noyaml.com/ for more examples.\n-   **TOML**: Gets unwieldy when there's multiple levels of nesting.\n\nAs a response to these issues, and the lack of programmability, a number of new configuration languages have emerged including `dhall`, `cue`, `jsonnet`, and\n`nickel`. These languages address several of the issues above, **but** they all\nrequire users to learn new syntax.\n\nIn a playful way, we like to call this the Tarpit Law,\nnamed so after the [Turing Tarpit](https://en.wikipedia.org/wiki/Turing_tarpit) and\n[Greenspun's Tenth Rule](https://en.wikipedia.org/wiki/Greenspun%27s_tenth_rule):\n\n\u003e **The Tarpit Law of Programming**:\n\u003e \"Every configuration language that supports logic, eventually evolves into an ad-hoc,\n\u003e informally-specified, bug-ridden, and slow implementation of a Turing-complete language.\"\n\nThis is meant to be tongue-in-cheek: many of the above languages are well-specified, and not buggy, some are not even Turing-complete ... but still, while trying to adopt them,\nwe found ourselves frustrated, wishing that instead of learning a new syntax, we could just\nuse an existing, widely adopted language like TypeScript instead.\n\nSo we asked ourselves, why _don't_ we already use TypeScript as a configuration language?\nWhat's stopping us? In fact, within the JavaScript ecosystem, most tools _already_ allow\nusers to use TypeScript for configuration. Why don't we do the same in other ecosystems?\n\nWe realized that the blocker for us was the lack of native libraries for evaluating TypeScript-based\nconfigs and converting them to JSON. We decided to build TySON to address this issue.\nOur first implementation is a library in pure `go`, that can evaluate TySON files and convert\nthem to JSON. Implementations for other languages will follow suit.\n\n## Command Line Tool\n\nTySON comes with a command line tool that can be used to convert TySON files to\nJSON. To install it, run:\n\n```bash\ncurl -fsSL https://get.jetify.com/tyson | bash\n```\n\nTo convert the file `input.tson` into JSON, run:\n\n```bash\ntyson eval input.tson\n```\n\nThe resulting JSON will be printed to stdout.\n\n## Next Steps\n\nWe're sharing TySON as an early developer preview, to get feedback from the\ncommunity before we solidify the spec.\n\nAt the moment we offer:\n\n1. A `golang` library that can parse TySON files and evaluate them to JSON.\n   It is built on top of the widely adopted, and rock-solid `esbuild`.\n1. A command line tool, compiled as a single binary, that can parse and\n   evaluate TySON files to JSON.\n\nBased on feedback from the community, we plan to add:\n\n1. A formal spec for TySON (once we feel confident we can retain backwards compatibility).\n1. Implementations for other languages including `rust`.\n\n# Related Work\n\nAlternative configuration languages that can be converted to JSON, include:\n\n-   [dhall](https://dhall-lang.org/)\n-   [cue](https://cuelang.org/)\n-   [jsonnet](https://jsonnet.org/)\n-   [nickel](https://nickel-lang.org/)\n\nIf you are willing to learn a new syntax for your configuration then these alternatives\ncan provide different guarantees. As an examples:\n\n-   Dhall works hard to be a [total language](https://dhall-lang.org/)\n    instead of being Turing complete\n-   Cue has a type-system based on graph unification\n    that makes it easy to combine values in any order and still get the same result,\n    which is sometimes easier to reason with.\n\nTySON's main differentiator is that we use TypeScript as the underlying language.\nIt makes it possible to immediately get started with a familiar syntax, and reuse\nexisting editor (and ecosystem) support for TypeScript.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjetify-com%2Ftyson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjetify-com%2Ftyson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjetify-com%2Ftyson/lists"}