{"id":28098496,"url":"https://github.com/elyukai/tsondb","last_synced_at":"2026-03-06T09:06:08.056Z","repository":{"id":289278943,"uuid":"960972382","full_name":"elyukai/tsondb","owner":"elyukai","description":"A TypeScript DSL for creating and managing Git-optimized JSON databases.","archived":false,"fork":false,"pushed_at":"2026-02-23T21:18:04.000Z","size":1389,"stargazers_count":1,"open_issues_count":13,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-24T04:09:54.133Z","etag":null,"topics":["codegen","dbms","node","nosql","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elyukai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"patreon":"optolith"}},"created_at":"2025-04-05T13:29:25.000Z","updated_at":"2026-02-23T21:18:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"3a5515b0-1b38-4bac-8024-df6936ac72f4","html_url":"https://github.com/elyukai/tsondb","commit_stats":null,"previous_names":["elyukai/tsondb"],"tags_count":95,"template":false,"template_full_name":null,"purl":"pkg:github/elyukai/tsondb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elyukai%2Ftsondb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elyukai%2Ftsondb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elyukai%2Ftsondb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elyukai%2Ftsondb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elyukai","download_url":"https://codeload.github.com/elyukai/tsondb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elyukai%2Ftsondb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30168623,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T07:56:45.623Z","status":"ssl_error","status_checked_at":"2026-03-06T07:55:55.621Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["codegen","dbms","node","nosql","typescript"],"created_at":"2025-05-13T17:57:54.007Z","updated_at":"2026-03-06T09:06:08.045Z","avatar_url":"https://github.com/elyukai.png","language":"TypeScript","funding_links":["https://patreon.com/optolith"],"categories":[],"sub_categories":[],"readme":"# TSON-DB\n\nTSON-DB is a specialized DBMS for file-based databases. The database schema is defined in TypeScript using type functions. With options provided in these functions, a graphical user interface is generated that can be accessed through a browser.\n\nTSON-DB can also be used to render type declarations in multiple languages or vocabularies like TypeScript (as actual types) or JSON Schema for the defined schema, but custom renderers can also be defined and used to support any output you need.\n\n## Installation\n\n```sh\nnpm install tsondb\n```\n\n## Configuration\n\nTo configure `tsondb`, create a configuration file at the location from where you are going to run its commands, usually the project root. The following file names are possible and are checked in the given order:\n\n1. `tsondb.config.mts`\n2. `tsondb.config.ts`\n3. `tsondb.config.mjs`\n4. `tsondb.config.js`\n\nYou need to export an object conforming to the `Config` type as the default export.\n\n```ts\n// tsondb.config.ts\nimport { join } from \"node:path\"\nimport { type Config, Schema } from \"tsondb\"\nimport { JsonSchemaOutput } from \"tsondb/renderer/jsonschema\"\nimport { TypeScriptOutput } from \"tsondb/renderer/ts\"\n\nexport default {\n  schema: new Schema(\n    [\n      // add your entities here\n    ]\n  ),\n  outputs: [\n    TypeScriptOutput({\n      targetPath: join(import.meta.dirname, \"gen\", \"ts\"),\n    }),\n    JsonSchemaOutput({\n      targetPath: join(import.meta.dirname, \"gen\", \"schema\"),\n    }),\n  ],\n  dataRootPath: join(import.meta.dirname, \"data\"),\n} satisfies Config\n```\n\nSee the following sections for details on how the different parts come together.\n\n## Terms\n\nThe following list will define common terms used in TSONDB.\n\n- **Entity:** The type of group of values, e.g. employees.\n- **Instance:** A singular group of values of an *entity*, e.g. Jane Doe.\n\n## Define a Schema\n\nYou define a schema by declarations that consist of types.\n\n```ts\nimport { Entity, Object, Required, String } from \"tsondb/schema/def\"\n\nconst User = Entity(import.meta.url, {\n  name: \"User\",\n  namePlural: \"Users\",\n  comment: \"A user in the application.\",\n  type: () =\u003e Object({\n    name: Required({\n      comment: \"The user’s full name.\",\n      type: String({ minLength: 1 }),\n    }),\n  }),\n})\n```\n\nThis defines a user entity with a single property called `name`. Its type is a non-empty string.\n\nYou can see how constraints are added by passing an object to the type function. This is a pattern used throughout. When a type is generic, like `Array` or `Object`, the option parameter is usually the second.\n\nYou can also add comments that, while not displayed by IDEs during the development of the schema, are used when generating outputs.\n\nNote that some imports may shadow global objects (like `String` and `Object` in the example above). If you need a different name for an import, instead renaming an import, you can import a longer version of all declaration and type functions \u0026mdash; declarations have a `Decl` suffix (e.g. `EntityDecl`) and types have a `Type` suffix (e.g. `StringType`). The simple imports are preferred due to simplicity, but you can also always use the suffixed names if you prefer to not shadow global objects.\n\nMake sure to always pass `import.meta.url` as the first parameter to each declaration function, otherwise some functionality will not work at all or will not work as expected.\n\nTo actually add `Ùser` to your schema, either list it in the array passed to the `Schema` function or reference it in an entity that is already listed.\n\n### Available Declarations\n\n#### `Entity` or `EntityDecl`\n\nEach entity has to be an object (and so the `type` option always has to return an `Object` type) and its instances have their own directory within the database root. TSON-DB automatically sets an `id` property on the object, so you cannot define an `id` by yourself. The identifier is a UUID that is also reflected in the instance’s file name.\n\n#### `Enum` or `EnumDecl`\n\nAn enumeration consists of one or more cases that are defined using `EnumCase` (or `EnumCaseDecl`) declarations. In the database files, they are represented using a discriminator property.\n\n#### `TypeAlias` or `TypeAliasDecl`\n\nWith a type alias you can give another type a descriptive name in generated outputs. Note that this is different from just assigning a type to a variable and using it. If you use a variable directly, it is merged into the declaration when generating outputs.\n\n### Available Types\n\n#### `Array` or `ArrayType`\n\nAn array type where you can define length and uniqueness constraints.\n\n#### `Enum` or `EnumType`\n\nYou do not use this type directly, it is used internally and is only exported if you want to write your output renderer.\n\n#### `Object` or `ObjectType`\n\nAn object type where you can define length constraints. Use in conjunction with the `Required` and `Optional` functions for defining object properties.\n\n#### `Boolean` or `BooleanType`\n\nA boolean type. This is not configurable.\n\n#### `Date` or `DateType`\n\nA date type where you can define whether to include time or not.\n\n#### `Float` or `FloatType`\n\nA floating-point number type with bound and factor constraints.\n\n#### `Integer` or `IntegerType`\n\nAn integer type with bound and factor constraints.\n\n#### `String` or `StringType`\n\nA string type with length and pattern constraints.\n\n#### `GenericArgumentIdentifier` or `GenericArgumentIdentifierType`\n\nA type that references a type argument. Only useful with generic declarations (see *Type Parameters (Generics)* below).\n\n#### `IncludeIdentifier` or `IncludeIdentifierType`\n\nA type that references a type alias. There is a `Gen` version to reference generic type aliases (see *Type Parameters (Generics)* below).\n\n#### `NestedEntityMap` or `NestedEntityMapType`\n\nA keyed dictionary type where the keys are references to instances of another type. Often used for translations where the keys represent the locale identifier.\n\n#### `ReferenceIdentifier` or `ReferenceIdentifierType`\n\nA type that defines a reference to an instance of an entity.\n\n### Type Parameters (Generics)\n\nThere are some declarations where you can define type parameters if you want it to be more flexible. In that case, you can import a declaration with a `Gen` prefix. `Entity` declarations do not support type parameters, but the other declaration types do (e.g. `GenTypeAlias`). In these cases, you have to define the `parameters` option, which must be an array of the type parameters you want to define via the `Param` function. You can optionally define type constraints for a type parameter using normal type functions.\n\nTo use these parameters in its definition, define them as parameters to the defining function and use the `GenericArgumentIdentifier` type to reference them.\n\n```ts\nconst ValueAtName = GenTypeAlias(import.meta.url, {\n  name: \"ValueAtName\",\n  parameters: [Parameter(\"Value\")],\n  type: (Value) =\u003e Object({\n    name: Required({\n      type: GenericArgumentIdentifier(Value),\n    }),\n  }),\n})\n```\n\nTo reference a type alias in another declaration, use the `GenIncludeIdentifier` function.\n\n```ts\nconst OtherEntity = Entity(import.meta.url, {\n  name: \"OtherEntity\",\n  namePlural: \"OtherEntities\",\n  type: () =\u003e Object({\n    arbitraryName: Required({\n      type: GenIncludeIdentifier(ValueAtName, [String()]),\n    }),\n  }),\n})\n```\n\n## GUI\n\nTo generate the graphical user interface, you need to create a `ModelContainer` with the schema you created before. Call either the `serve` or `generateValidateAndServe` functions with the created `ModelContainer`. You’ll be able to access the web interface at \u003chttp://localhost:3000\u003e.\n\n**Important:** If you only call the `serve` function, make sure the database has been validated before using either the `validate` or `generateAndValidate` functions.\n\nIf the database is in a Git repository, you’ll also get a simple Git GUI for managing branches and commits.\n\n## Generate typings\n\nTo generate typings, you have to define the `outputs` property in the configuration file.\n\n```ts\nexport default {\n  // ...\n  outputs: [\n    TypeScriptOutput({\n      targetPath: join(import.meta.dirname, \"gen\", \"types.d.ts\"),\n    }),\n    JsonSchemaOutput({\n      targetPath: join(import.meta.dirname, \"gen\", \"schema\"),\n      rendererOptions: {\n        preserveFiles: true,\n      },\n    }),\n  ],\n} satisfies Config\n```\n\nYou specify a target path where to save each generated content, and you can optionally provide custom settings to the respective renderers.\n\nIf the `preserveFiles` option is set to `true`, the target path is treated as a directory and the structure of your schema definitions is preserved. For example, if you have two files with definitions, `User.ts` and `Address.ts`, instead of outputting everything in `types.d.ts` (as specified above), a `types.d.ts` directory is created with `User.d.ts` and `Address.d.ts` files, where each file contains the declarations you put in each respectively.\n\nThis is possible due to the first argument to each declaration function, which should always be `import.meta.url`. If it is not set to this value, the `preserveFiles` option will behave differently according to the different path you set.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felyukai%2Ftsondb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felyukai%2Ftsondb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felyukai%2Ftsondb/lists"}