@rljson/rljson 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rljson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.architecture.md

@@ -0,0 +1,268 @@
+# Rljson Architecture
+
+This document describes the architecture of the Rljson format.
+
+## Table of Contents <!-- omit in toc -->
+
+- [What is Rljson?](#what-is-rljson)
+- [Principles](#principles)
+  - [JSON](#json)
+  - [Relational](#relational)
+  - [Normalized](#normalized)
+  - [Deeply Hashed](#deeply-hashed)
+  - [Immutable](#immutable)
+  - [Comparable](#comparable)
+  - [Database-Oriented](#database-oriented)
+  - [Decentralized](#decentralized)
+- [Concepts](#concepts)
+  - [Tables](#tables)
+  - [Rows \& Columns](#rows--columns)
+  - [Column Data Types](#column-data-types)
+  - [Hashes](#hashes)
+  - [Linking Tables Using References](#linking-tables-using-references)
+- [Data Types](#data-types)
+  - [Properties](#properties)
+  - [IdSet](#idset)
+  - [Collection](#collection)
+  - [Cake](#cake)
+  - [Buffet](#buffet)
+
+## What is Rljson?
+
+Rljson is a JSON-based exchange format inspired by relational databases,
+designed for efficient synchronization of large datasets across networks.
+
+## Principles
+
+### JSON
+
+Rljson uses JSON as its base format.
+
+### Relational
+
+Data is organized into normalized tables, similar to relational databases. This
+allows Rljson data to be easily imported into existing database systems.
+
+### Normalized
+
+Rljson is designed to transmit normalized, redundancy-free data that can be
+efficiently joined on the client side.
+
+### Deeply Hashed
+
+Hashes are added to all data using the `@rljson/hash` package.
+
+### Immutable
+
+Hashes serve as primary keys, making datasets immutable by default.
+
+### Comparable
+
+Hashes enable easy comparison of Rljson data.
+
+### Database-Oriented
+
+Since Rljson follows a database-oriented structure, importing and exporting data
+to and from databases is streamlined.
+
+### Decentralized
+
+Rljson hashes can be created without requiring a server, making it well-suited
+for Web 3.0 applications.
+
+## Concepts
+
+### Tables
+
+An Rljson file consists of a collection of tables. The table name is the key,
+and the table data is structured as dictionaries:
+
+```json
+{
+  "table0": {},
+  "table1": {},
+  "table2": {}
+}
+```
+
+Each table follows the `RljsonTable` interface, which defines a `_data` property
+containing the table rows and a `_type` property describing the table type:
+
+```json
+{
+  "table0": {
+    "_type": "properties",
+    "_data": []
+  }
+}
+```
+
+### Rows & Columns
+
+The `_data` section in an Rljson file contains a list of rows. Each row is a
+JSON object that maps column names to values. The example below shows a table
+with two columns, `language` and `greeting`, and two rows for English (`en`) and
+German (`de`):
+
+```json
+{
+  "table0": {
+    "_data": [
+      { "language": "en", "greeting": "Hello" },
+      { "language": "de", "greeting": "Hallo" }
+    ]
+  }
+}
+```
+
+### Column Data Types
+
+Columns can contain any of the Rljson-supported data types: `string | number |
+boolean | null | Json | JsonArray`.
+
+### Hashes
+
+Rljson uses hashes to identify and reference data. Using the `hash-in-place`
+(`hip`) method from `@rljson/hash`, hashes are deeply embedded into Rljson data:
+
+```js
+const jsonWithHashes = hip({
+  a: {
+    _data: [{ a: 10 }],
+    _type: 'properties',
+  },
+});
+```
+
+This results in:
+
+```json
+{
+  "_hash": "D1CtRUBswzGVc1o9yHQKEh",
+  "a": {
+    "_data": [
+      {
+        "_hash": "LeFJOCQVgToOfbUuKJQ-GO",
+        "a": 10
+      }
+    ],
+    "_hash": "FfCIOVQsrK1g5o5_G-AxP4",
+    "_type": "properties"
+  }
+}
+```
+
+### Linking Tables Using References
+
+Hashes allow tables to be linked using the `Ref` prefix. In the example below,
+table `b` references table `a` using `aRef`:
+
+```json
+{
+  "b": {
+    "_data": [{ "aRef": "LeFJOCQVgToOfbUuKJQ-GO" }],
+    "_type": "properties"
+  }
+}
+```
+
+This reference structure enables automated denormalization of JSON data.
+
+## Data Types
+
+Rljson provides several core data structures and table types to manage and
+synchronize large datasets.
+
+### Properties
+
+`Properties` are the fundamental data concept. A `PropertiesTable` contains
+key-value pairs representing property assignments:
+
+```json
+{
+  "sizes": {
+    "_type": "properties",
+    "_data": [
+      { "w": 10, "h": 20 },
+      { "w": 30, "h": 40 }
+    ]
+  }
+}
+```
+
+### IdSet
+
+For efficient management of large collections, item IDs are separated from their
+properties. This allows fetching IDs first and retrieving details later. The
+following `IdSet` defines a set of three IDs:
+
+```json
+{
+  "add": ["id0", "id1", "id2"],
+  "_hash": "IDS0"
+}
+```
+
+Derived `IdSets` can be created by modifying an existing set:
+
+```json
+{
+  "base": "IDS0",
+  "add": ["id3", "id4"],
+  "remove": ["id0"],
+  "_hash": "IDS1"
+}
+```
+
+### Collection
+
+A `Collection` consists of an `IdSet` and a mapping that links item IDs to their
+properties:
+
+```json
+{
+  "idSetsTable": "personIds",
+  "idSet": "IDS0",
+  "properties": "addresses",
+  "assign": {
+    "id0": "P0HASH",
+    "id1": "P1HASH"
+  },
+  "_hash": "C0HASH"
+}
+```
+
+### Cake
+
+Rljson supports `Cake` as a native data structure:
+
+- A `Cake` consists of layers, each representing a collection of items (slices).
+- All layers share the same item IDs (slice structure).
+- Each layer assigns different properties to the same items.
+
+```json
+{
+  "itemIdsTable": "ingredientIds",
+  "itemIds": "IDS1",
+  "layersTable": "HASH",
+  "assign": {
+    "base": "HASH15",
+    "cherries": "HASH16",
+    "creme": "HASH17"
+  }
+}
+```
+
+### Buffet
+
+A `Buffet` is a heterogeneous collection of different but related items, such as
+cakes, collections, or properties:
+
+```json
+{
+  "items": [
+    { "table": "drinks", "ref": "HASH20" },
+    { "table": "cakes", "ref": "HASH21" }
+  ]
+}
+```

package/README.blog.md

@@ -0,0 +1,3 @@
+# Blog
+
+Add latest posts at the end.

package/README.contributors.md

@@ -0,0 +1,151 @@
+# Contributors
+
+## Important
+
+⚠️ IMPORTANT: On `Windows, please checkout the repo on drive C`.
+There is a bug in the Vscode vitest extension v 1.14.4, making debugging tests
+not work. <https://github.com/vitest-dev/vscode/issues/548>
+Please check from time to time, if the issue is fixed and remove this hint.
+
+## Report issues
+
+Visit <https://github.com/rljson/rljson/issues>
+
+Check if there is already an issue for your problem
+
+If no, report the issue
+
+## Install pnpm
+
+Windows:
+
+```bash
+corepack enable pnpm
+```
+
+Mac:
+
+```bash
+sudo corepack enable pnpm
+```
+
+## Check out
+
+```bash
+mkdir rljson
+cd rljson
+git clone https://github.com/rljson/rljson.git
+cd rljson
+```
+
+## Install dependencies
+
+```bash
+npm install
+```
+
+## Run the tests
+
+```bash
+npm run test
+```
+
+## Build the package
+
+```bash
+npm run build
+```
+
+## Publish the package
+
+Open `package.json`
+
+Increase `version`
+
+Make sure all dependencies are listed in `peerDependencies`
+
+Make sure no file references are contained
+
+Open `vite.config.mts` right beside `package.json`
+
+Make sure all `peerDependencies` are listed in `rollupOptions/external`
+
+Compile typescript:
+
+```bash
+npm run build
+```
+
+Make publish dry-run
+
+```bash
+npm publish --access=public --dry-run
+```
+
+Check the changes to uploaded
+
+Publish the package
+
+```bash
+npm publish --access=public
+```
+
+## Architecture
+
+Reade [README.architecture.md](./README.architecture.md) to get an overview
+of the package's architecture.
+
+## Install Vscode extensions
+
+Open this project in `vscode`.
+
+Press `Cmd+Shift+P`.
+
+Type `Extensions: Show Recommended Extensions` and press `Enter`.
+
+The recommended extensions will be shown.
+
+Make sure, all recommended extensions are shown.
+
+## Uninstall all test extensions, e.g. Jest or Jasmine
+
+Jest or Jasmine extensions conflict with the `Vitest` extension used for this
+project.
+
+Uninstall them, if you have installed them.
+
+## Debug tests
+
+In Vscode: At the `left side bar` click on the `Test tube` icon to open the `Test explorer`.
+
+At the `top`, click on the `refresh` icon to show update the tests.
+
+Open a test file (`*.spec.ts`)
+
+Set a breakpoint.
+
+Press `alt` and click on the play button left beside the test.
+
+Execution should stop at the breakpoint.
+
+## Update goldens
+
+In various tests we are creating golden files, that are reference files that
+are compared against the files created in the tests.
+
+If change is detected, the fest fail.
+
+An example is `test/goldens/README.md` which is compared against
+`dist/README.md`.
+
+If the changes are desired, update the golden files:
+
+Open `update-goldens.ts`
+
+Set `export const updateGoldens` to `true`
+
+Run tests again.
+
+Set `export const updateGoldens` to `false`.
+
+Run tests again.

package/README.md

@@ -0,0 +1,18 @@
+# @rljson/rljson
+
+The RLJSON data format specification
+
+## Users
+
+| File                                 | Purpose                     |
+| ------------------------------------ | --------------------------- |
+| [README.public.md](README.public.md) | Install and use the package |
+
+## Contributors
+
+| File                                             | Purpose                       |
+| ------------------------------------------------ | ----------------------------- |
+| [README.contributors.md](README.contributors.md) | Run, debug, build and publish |
+| [README.architecture.md](README.architecture.md) | Software architecture guide   |
+| [README.trouble.md](README.trouble.md)           | Errors & solutions            |
+| [README.blog.md](README.blog.md)                 | Blog                          |

package/README.public.md

@@ -0,0 +1,7 @@
+# @rljson/
+
+Todo: Add description here
+
+## Example
+
+[src/example.ts](src/example.ts)

package/README.trouble.md

@@ -0,0 +1,36 @@
+<!--
+
+-->
+
+# Trouble shooting
+
+## Table of contents <!-- omit in toc -->
+
+- [Vscode Windows: Debugging is not working](#vscode-windows-debugging-is-not-working)
+- [GitHub actions: Cannot find module @rollup/rollup-linux-x64-gnu](#github-actions-cannot-find-module-rolluprollup-linux-x64-gnu)
+
+## Vscode Windows: Debugging is not working
+
+Date: 2025-03-08
+
+⚠️ IMPORTANT: On Windows, please check out the repo on drive C. There is a bug
+in the VS Code Vitest extension (v1.14.4), which prevents test debugging from
+working: <https://github.com/vitest-dev/vscode/issues/548> Please check from
+time to time if the issue has been fixed and remove this note once it is
+resolved.
+
+## GitHub actions: Cannot find module @rollup/rollup-linux-x64-gnu
+
+⚠️ Error: Cannot find module @rollup/rollup-linux-x64-gnu. npm has a bug related to
+optional dependencies (<https://github.com/npm/cli/issues/4828>). Please try `npm
+i` again after removing both package-lock.json and node_modules directory.
+
+Solution:
+
+```bash
+rm -rf node_modules
+rm package-lock.json
+npm install
+```
+
+Then push `package-lock.yaml` again

package/dist/README.architecture.md

@@ -0,0 +1,268 @@
+# Rljson Architecture
+
+This document describes the architecture of the Rljson format.
+
+## Table of Contents <!-- omit in toc -->
+
+- [What is Rljson?](#what-is-rljson)
+- [Principles](#principles)
+  - [JSON](#json)
+  - [Relational](#relational)
+  - [Normalized](#normalized)
+  - [Deeply Hashed](#deeply-hashed)
+  - [Immutable](#immutable)
+  - [Comparable](#comparable)
+  - [Database-Oriented](#database-oriented)
+  - [Decentralized](#decentralized)
+- [Concepts](#concepts)
+  - [Tables](#tables)
+  - [Rows \& Columns](#rows--columns)
+  - [Column Data Types](#column-data-types)
+  - [Hashes](#hashes)
+  - [Linking Tables Using References](#linking-tables-using-references)
+- [Data Types](#data-types)
+  - [Properties](#properties)
+  - [IdSet](#idset)
+  - [Collection](#collection)
+  - [Cake](#cake)
+  - [Buffet](#buffet)
+
+## What is Rljson?
+
+Rljson is a JSON-based exchange format inspired by relational databases,
+designed for efficient synchronization of large datasets across networks.
+
+## Principles
+
+### JSON
+
+Rljson uses JSON as its base format.
+
+### Relational
+
+Data is organized into normalized tables, similar to relational databases. This
+allows Rljson data to be easily imported into existing database systems.
+
+### Normalized
+
+Rljson is designed to transmit normalized, redundancy-free data that can be
+efficiently joined on the client side.
+
+### Deeply Hashed
+
+Hashes are added to all data using the `@rljson/hash` package.
+
+### Immutable
+
+Hashes serve as primary keys, making datasets immutable by default.
+
+### Comparable
+
+Hashes enable easy comparison of Rljson data.
+
+### Database-Oriented
+
+Since Rljson follows a database-oriented structure, importing and exporting data
+to and from databases is streamlined.
+
+### Decentralized
+
+Rljson hashes can be created without requiring a server, making it well-suited
+for Web 3.0 applications.
+
+## Concepts
+
+### Tables
+
+An Rljson file consists of a collection of tables. The table name is the key,
+and the table data is structured as dictionaries:
+
+```json
+{
+  "table0": {},
+  "table1": {},
+  "table2": {}
+}
+```
+
+Each table follows the `RljsonTable` interface, which defines a `_data` property
+containing the table rows and a `_type` property describing the table type:
+
+```json
+{
+  "table0": {
+    "_type": "properties",
+    "_data": []
+  }
+}
+```
+
+### Rows & Columns
+
+The `_data` section in an Rljson file contains a list of rows. Each row is a
+JSON object that maps column names to values. The example below shows a table
+with two columns, `language` and `greeting`, and two rows for English (`en`) and
+German (`de`):
+
+```json
+{
+  "table0": {
+    "_data": [
+      { "language": "en", "greeting": "Hello" },
+      { "language": "de", "greeting": "Hallo" }
+    ]
+  }
+}
+```
+
+### Column Data Types
+
+Columns can contain any of the Rljson-supported data types: `string | number |
+boolean | null | Json | JsonArray`.
+
+### Hashes
+
+Rljson uses hashes to identify and reference data. Using the `hash-in-place`
+(`hip`) method from `@rljson/hash`, hashes are deeply embedded into Rljson data:
+
+```js
+const jsonWithHashes = hip({
+  a: {
+    _data: [{ a: 10 }],
+    _type: 'properties',
+  },
+});
+```
+
+This results in:
+
+```json
+{
+  "_hash": "D1CtRUBswzGVc1o9yHQKEh",
+  "a": {
+    "_data": [
+      {
+        "_hash": "LeFJOCQVgToOfbUuKJQ-GO",
+        "a": 10
+      }
+    ],
+    "_hash": "FfCIOVQsrK1g5o5_G-AxP4",
+    "_type": "properties"
+  }
+}
+```
+
+### Linking Tables Using References
+
+Hashes allow tables to be linked using the `Ref` prefix. In the example below,
+table `b` references table `a` using `aRef`:
+
+```json
+{
+  "b": {
+    "_data": [{ "aRef": "LeFJOCQVgToOfbUuKJQ-GO" }],
+    "_type": "properties"
+  }
+}
+```
+
+This reference structure enables automated denormalization of JSON data.
+
+## Data Types
+
+Rljson provides several core data structures and table types to manage and
+synchronize large datasets.
+
+### Properties
+
+`Properties` are the fundamental data concept. A `PropertiesTable` contains
+key-value pairs representing property assignments:
+
+```json
+{
+  "sizes": {
+    "_type": "properties",
+    "_data": [
+      { "w": 10, "h": 20 },
+      { "w": 30, "h": 40 }
+    ]
+  }
+}
+```
+
+### IdSet
+
+For efficient management of large collections, item IDs are separated from their
+properties. This allows fetching IDs first and retrieving details later. The
+following `IdSet` defines a set of three IDs:
+
+```json
+{
+  "add": ["id0", "id1", "id2"],
+  "_hash": "IDS0"
+}
+```
+
+Derived `IdSets` can be created by modifying an existing set:
+
+```json
+{
+  "base": "IDS0",
+  "add": ["id3", "id4"],
+  "remove": ["id0"],
+  "_hash": "IDS1"
+}
+```
+
+### Collection
+
+A `Collection` consists of an `IdSet` and a mapping that links item IDs to their
+properties:
+
+```json
+{
+  "idSetsTable": "personIds",
+  "idSet": "IDS0",
+  "properties": "addresses",
+  "assign": {
+    "id0": "P0HASH",
+    "id1": "P1HASH"
+  },
+  "_hash": "C0HASH"
+}
+```
+
+### Cake
+
+Rljson supports `Cake` as a native data structure:
+
+- A `Cake` consists of layers, each representing a collection of items (slices).
+- All layers share the same item IDs (slice structure).
+- Each layer assigns different properties to the same items.
+
+```json
+{
+  "itemIdsTable": "ingredientIds",
+  "itemIds": "IDS1",
+  "layersTable": "HASH",
+  "assign": {
+    "base": "HASH15",
+    "cherries": "HASH16",
+    "creme": "HASH17"
+  }
+}
+```
+
+### Buffet
+
+A `Buffet` is a heterogeneous collection of different but related items, such as
+cakes, collections, or properties:
+
+```json
+{
+  "items": [
+    { "table": "drinks", "ref": "HASH20" },
+    { "table": "cakes", "ref": "HASH21" }
+  ]
+}
+```

package/dist/README.blog.md

@@ -0,0 +1,3 @@
+# Blog
+
+Add latest posts at the end.

package/dist/README.contributors.md

@@ -0,0 +1,151 @@
+# Contributors
+
+## Important
+
+⚠️ IMPORTANT: On `Windows, please checkout the repo on drive C`.
+There is a bug in the Vscode vitest extension v 1.14.4, making debugging tests
+not work. <https://github.com/vitest-dev/vscode/issues/548>
+Please check from time to time, if the issue is fixed and remove this hint.
+
+## Report issues
+
+Visit <https://github.com/rljson/rljson/issues>
+
+Check if there is already an issue for your problem
+
+If no, report the issue
+
+## Install pnpm
+
+Windows:
+
+```bash
+corepack enable pnpm
+```
+
+Mac:
+
+```bash
+sudo corepack enable pnpm
+```
+
+## Check out
+
+```bash
+mkdir rljson
+cd rljson
+git clone https://github.com/rljson/rljson.git
+cd rljson
+```
+
+## Install dependencies
+
+```bash
+npm install
+```
+
+## Run the tests
+
+```bash
+npm run test
+```
+
+## Build the package
+
+```bash
+npm run build
+```
+
+## Publish the package
+
+Open `package.json`
+
+Increase `version`
+
+Make sure all dependencies are listed in `peerDependencies`
+
+Make sure no file references are contained
+
+Open `vite.config.mts` right beside `package.json`
+
+Make sure all `peerDependencies` are listed in `rollupOptions/external`
+
+Compile typescript:
+
+```bash
+npm run build
+```
+
+Make publish dry-run
+
+```bash
+npm publish --access=public --dry-run
+```
+
+Check the changes to uploaded
+
+Publish the package
+
+```bash
+npm publish --access=public
+```
+
+## Architecture
+
+Reade [README.architecture.md](./README.architecture.md) to get an overview
+of the package's architecture.
+
+## Install Vscode extensions
+
+Open this project in `vscode`.
+
+Press `Cmd+Shift+P`.
+
+Type `Extensions: Show Recommended Extensions` and press `Enter`.
+
+The recommended extensions will be shown.
+
+Make sure, all recommended extensions are shown.
+
+## Uninstall all test extensions, e.g. Jest or Jasmine
+
+Jest or Jasmine extensions conflict with the `Vitest` extension used for this
+project.
+
+Uninstall them, if you have installed them.
+
+## Debug tests
+
+In Vscode: At the `left side bar` click on the `Test tube` icon to open the `Test explorer`.
+
+At the `top`, click on the `refresh` icon to show update the tests.
+
+Open a test file (`*.spec.ts`)
+
+Set a breakpoint.
+
+Press `alt` and click on the play button left beside the test.
+
+Execution should stop at the breakpoint.
+
+## Update goldens
+
+In various tests we are creating golden files, that are reference files that
+are compared against the files created in the tests.
+
+If change is detected, the fest fail.
+
+An example is `test/goldens/README.md` which is compared against
+`dist/README.md`.
+
+If the changes are desired, update the golden files:
+
+Open `update-goldens.ts`
+
+Set `export const updateGoldens` to `true`
+
+Run tests again.
+
+Set `export const updateGoldens` to `false`.
+
+Run tests again.

package/dist/README.md

@@ -0,0 +1,18 @@
+# @rljson/rljson
+
+The RLJSON data format specification
+
+## Users
+
+| File                                 | Purpose                     |
+| ------------------------------------ | --------------------------- |
+| [README.public.md](README.public.md) | Install and use the package |
+
+## Contributors
+
+| File                                             | Purpose                       |
+| ------------------------------------------------ | ----------------------------- |
+| [README.contributors.md](README.contributors.md) | Run, debug, build and publish |
+| [README.architecture.md](README.architecture.md) | Software architecture guide   |
+| [README.trouble.md](README.trouble.md)           | Errors & solutions            |
+| [README.blog.md](README.blog.md)                 | Blog                          |

package/dist/README.public.md

@@ -0,0 +1,7 @@
+# @rljson/
+
+Todo: Add description here
+
+## Example
+
+[src/example.ts](src/example.ts)

package/dist/README.trouble.md

@@ -0,0 +1,36 @@
+<!--
+
+-->
+
+# Trouble shooting
+
+## Table of contents <!-- omit in toc -->
+
+- [Vscode Windows: Debugging is not working](#vscode-windows-debugging-is-not-working)
+- [GitHub actions: Cannot find module @rollup/rollup-linux-x64-gnu](#github-actions-cannot-find-module-rolluprollup-linux-x64-gnu)
+
+## Vscode Windows: Debugging is not working
+
+Date: 2025-03-08
+
+⚠️ IMPORTANT: On Windows, please check out the repo on drive C. There is a bug
+in the VS Code Vitest extension (v1.14.4), which prevents test debugging from
+working: <https://github.com/vitest-dev/vscode/issues/548> Please check from
+time to time if the issue has been fixed and remove this note once it is
+resolved.
+
+## GitHub actions: Cannot find module @rollup/rollup-linux-x64-gnu
+
+⚠️ Error: Cannot find module @rollup/rollup-linux-x64-gnu. npm has a bug related to
+optional dependencies (<https://github.com/npm/cli/issues/4828>). Please try `npm
+i` again after removing both package-lock.json and node_modules directory.
+
+Solution:
+
+```bash
+rm -rf node_modules
+rm package-lock.json
+npm install
+```
+
+Then push `package-lock.yaml` again

package/dist/example.d.ts

@@ -0,0 +1,4 @@
+/**
+ * The example function demonstrates how the package works
+ */
+export declare const example: () => void;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { type Rljson } from './rljson.ts';

package/dist/rljson.d.ts

@@ -0,0 +1,168 @@
+import { Json, JsonValue } from '@rljson/json';
+/**
+ * A ref is a hash that references to another element
+ */
+export type Ref = string;
+/**
+ * An `id` is a *user defined* name or identifier of an item.
+ * It exists in parallel with the auto generated `_hash`.
+ */
+export type ItemId = string;
+/**
+ * A table id reference to a table. The table ids are used as keys in the top
+ * level structure of an Rljson data object.
+ */
+export type TableName = ItemId;
+/**
+ * Types of tables that can be stored in an Rljson object
+ *
+ * - `buffets` Tables containing buffets
+ * - `cakes` Tables containing cakes
+ * - `collections` Tables containing collections
+ * - `ids` Tables containing item ids
+ * - `properties` Tables containing item properties
+ */
+export type TableType = 'buffet' | 'cake' | 'collection' | 'ids' | 'properties';
+/** A table in the rljson format */
+export interface RljsonTable<Data extends Json, Type extends TableType> extends Json {
+    /** The data rows of the table */
+    _data: Data[];
+    /**  The type of the table */
+    _type: Type;
+}
+/**
+ * A reference to a properties row in a properties table
+ */
+export type PropertiesRef = Ref;
+/**
+ * A table containing item properties
+ */
+export type PropertiesTable = RljsonTable<Json, 'properties'>;
+/**
+ * An IdSetRef is a hash pointing to an Ids
+ */
+export type IdSetRef = Ref;
+/**
+ * An Ids manages list of item ids
+ */
+export interface IdSet extends Json {
+    /**
+     * The hash of another item id list which is extended by this one.
+     * Must be empty or null, when the list is the root.
+     */
+    base: IdSetRef | null;
+    /**
+     * The item ids added to base
+     */
+    add: ItemId[];
+    /**
+     * The item ids removed from base
+     */
+    remove: ItemId[];
+}
+/**
+ * A table containing item ids
+ */
+export type IdSetsTable = RljsonTable<IdSet, 'ids'>;
+/**
+ * A CollectionRef is a hash pointing to a collection
+ */
+export type CollectionRef = Ref;
+/**
+ * A collection assigns properties to item ids
+ */
+export interface Collection extends Json {
+    /**
+     * `base` an optional base collection that is extended by this collection
+     */
+    base: CollectionRef | null;
+    /**
+     * The table containing the item set of this collection
+     */
+    idSetsTable: TableName;
+    /**
+     * A reference to the ids of the items the collection is based on
+     */
+    idSet: IdSetRef;
+    /**
+     * The table containing the properties assigned to the items of this collection
+     */
+    properties: TableName;
+    /**
+     * Assign properties to each item of the collection.
+     */
+    assign: Record<ItemId, PropertiesRef>;
+}
+/**
+ * A table containing collections
+ */
+export type CollectionsTable = RljsonTable<Collection, 'collection'>;
+/**
+ * A `CakeLayerId` assigns an id or name to a cake layer
+ */
+export type CakeLayerId = ItemId;
+/**
+ * A `CakeLayerIds` is a set of cake layer ids / cake layer names
+ */
+export type CakeLayerIds = IdSet;
+/**
+ * A cake is a collection of layers.
+ *
+ * A layer is a collection of items.
+ * All layers of a cake refer to the same items.
+ */
+export interface Cake extends Json {
+    /**
+     * The table containing the item ids of the cake
+     */
+    itemIdsTable: TableName;
+    /**
+     * All layers of a cake share the same item ids.
+     */
+    itemIds: IdSetRef;
+    /**
+     * The table containing the layers of this cake
+     */
+    layersTable: TableName;
+    /**
+     * Assigns a collection to each layer of the cake.
+     */
+    layers: {
+        [layerId: CakeLayerId]: CollectionRef;
+    };
+}
+/**
+ * A table containing cakes
+ */
+export type CakesTable = RljsonTable<Cake, 'cake'>;
+/**
+ * A buffet id is a name or id of a buffet
+ */
+export type BuffetId = ItemId;
+/**
+ * A buffet is a collection of arbitrary but related items, e.g. cakes,
+ * collections, or items.
+ */
+export interface Buffet extends Json {
+    /**
+     * The items of the buffet
+     */
+    items: Array<{
+        table: TableName;
+        ref: Ref;
+        [key: string]: JsonValue;
+    }>;
+}
+/**
+ * A table containing buffets
+ */
+export type BuffetsTable = RljsonTable<Buffet, 'buffet'>;
+/**
+ * One of the supported Rljson table types
+ */
+export type RljsonTableType = BuffetsTable | PropertiesTable | CollectionsTable | IdSetsTable | CakesTable;
+/** The rljson data format */
+export interface Rljson extends Json {
+    [tableId: TableName]: RljsonTableType | string;
+}
+export declare const exampleRljson: () => Rljson;

package/dist/rljson.js

@@ -0,0 +1 @@
+

package/dist/src/example.ts

@@ -0,0 +1,18 @@
+// @license
+// Copyright (c) 2025 Rljson
+//
+// Use of this source code is governed by terms that can be
+// found in the LICENSE file in the root of this package.
+
+import { exampleRljson } from './rljson.ts';
+
+/**
+ * The example function demonstrates how the package works
+ */
+export const example = () => {
+  const print = console.log;
+  const stringify = JSON.stringify;
+
+  const rljson = exampleRljson();
+  print(stringify(rljson, null, 2));
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@rljson/rljson",
+  "version": "0.0.1",
+  "packageManager": "pnpm@10.6.2",
+  "description": "The RLJSON data format specification",
+  "homepage": "https://github.com/rljson/rljson",
+  "bugs": "https://github.com/rljson/rljson/issues",
+  "private": false,
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rljson/rljson.git"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "npx vite build && tsc && cp README* dist && mkdir dist/src && cp src/example.ts dist/src",
+    "test": "npx vitest run --coverage && npm run lint",
+    "prebuild": "npm run test",
+    "prepublishOnly": "npm run build && npm run test",
+    "lint": "npx eslint",
+    "updateGoldens": "cross-env UPDATE_GOLDENS=true npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "@typescript-eslint/eslint-plugin": "^8.26.1",
+    "@typescript-eslint/parser": "^8.26.1",
+    "@vitest/coverage-v8": "^3.0.8",
+    "cross-env": "^7.0.3",
+    "eslint": "^9.22.0",
+    "eslint-plugin-jsdoc": "^50.6.3",
+    "eslint-plugin-tsdoc": "^0.4.0",
+    "globals": "^16.0.0",
+    "jsdoc": "^4.0.4",
+    "typescript": "~5.8.2",
+    "typescript-eslint": "^8.26.1",
+    "vite": "^6.2.1",
+    "vite-node": "^3.0.8",
+    "vite-plugin-dts": "^4.5.3",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.0.8",
+    "vitest-dom": "^0.1.1"
+  },
+  "peerDependencies": {
+    "@rljson/hash": "^0.0.5",
+    "@rljson/json": "^0.0.4"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}