@rljson/rljson 0.0.33 → 0.0.34

package/dist/content/buffet.d.ts

@@ -23,6 +23,10 @@ export interface Buffet extends Json {
          */
         ref: Ref;
     }>;
+    /**
+     * An optional ID of the buffet.
+     */
+    id?: BuffetId;
 }
 /**
  * A table containing buffets

package/dist/content/cake.d.ts

@@ -34,6 +34,10 @@ export interface Cake extends Json {
     layers: {
         [layerId: CakeLayerId]: LayerRef;
     };
+    /**
+     * An optional ID of the cake.
+     */
+    id?: string;
 }
 /**
  * A table containing cakes

package/dist/content/ingredients.d.ts

@@ -1,7 +1,6 @@
-import { Json } from '@rljson/json';
 import { NutritionalValues } from '../example/bakery-example.ts';
 import { RljsonTable } from '../rljson.ts';
-import { Ref } from '../typedefs.ts';
+import { JsonWithId, Ref } from '../typedefs.ts';
 /**
  * A reference to a ingredients row in a ingredients table
  */
@@ -9,7 +8,7 @@ export type IngredientsRef = Ref;
 /**
  * A table containing ingredients
  */
-export type IngredientsTable<T extends Json> = RljsonTable<T, 'ingredients'>;
+export type IngredientsTable<T extends JsonWithId> = RljsonTable<T, 'ingredients'>;
 /**
  * Provides an example ingredients table for test purposes
  */

package/dist/content/revision.d.ts

@@ -0,0 +1,37 @@
+import { Json } from '@rljson/json';
+import { RljsonTable } from '../rljson.ts';
+import { Ref, TableKey } from '../typedefs.ts';
+/**
+ * Describes a revision of a row in a table
+ */
+export interface Revision extends Json {
+    /**
+     * The name of the table the revisione row belongs to
+     */
+    table: TableKey;
+    /**
+     * The predecessor of the revision
+     */
+    predecessor: Ref;
+    /**
+     * The successor of the revision
+     */
+    successor: Ref;
+    /**
+     * The UTC timestamp of the revision
+     */
+    timestamp: number;
+    /**
+     * The optional ID of the revisioned element.
+     * Can be used get all revisions of a specific ingredient.
+     */
+    id?: string;
+}
+/**
+ * A table containing revisions
+ */
+export type RevisionsTable = RljsonTable<Revision, 'ingredients'>;
+/**
+ * Example revision object for test purposes
+ */
+export declare const exampleRevision: () => Revision;

package/dist/content/table-cfg.d.ts

@@ -9,10 +9,6 @@ export type TableCfgRef = Ref;
  * A column configuration
  */
 export interface ColumnCfg extends Json {
-    /**
-     * The key of the column used in data
-     */
-    key: ColumnKey;
     /**
      * The type of the column
      */
@@ -43,6 +39,30 @@ export interface TableCfg extends Json {
      * Needs to be increased when new columns are added.
      */
     version: number;
+    /**
+     * Head tables serve as versioning entry points.
+     *
+     * - Head tables must contain an id column
+     * - Rows in an head table must contain a non-null id
+     * - Same row ids must refer to the same physical object
+     * - Head tables have no or only one parent table
+     */
+    isHead: boolean;
+    /**
+     * Root tables are tables that have no parent table.
+     *
+     * - Root tables are also head tables
+     */
+    isRoot: boolean;
+    /**
+     * Shared tables are tables that are used by multiple parents.
+     *
+     * - The don't need an id column
+     * - Same id can refer to different physical objects
+     * - Shared tables can have multiple parents
+     * - Shared tables can not be head or root tables
+     */
+    isShared: boolean;
 }
 /**
  * A table containing columns

package/dist/example.d.ts

@@ -23,7 +23,7 @@ export declare class Example {
             missingReferencedTable: () => Rljson;
         };
         tableCfg: {
-            wrongType: () => import('@rljson/hash').Hashed<Rljson>;
+            wrongType: () => Rljson;
         };
         layers: {
             missingBase: () => Rljson;

package/dist/rljson.d.ts

@@ -3,6 +3,7 @@ import { BuffetsTable } from './content/buffet.ts';
 import { CakesTable } from './content/cake.ts';
 import { IngredientsTable } from './content/ingredients.ts';
 import { LayersTable } from './content/layer.ts';
+import { RevisionsTable } from './content/revision.ts';
 import { SliceIdsTable } from './content/slice-ids.ts';
 import { TableCfgRef, TablesCfgTable } from './content/table-cfg.ts';
 import { ContentType, Ref, TableKey } from './typedefs.ts';
@@ -11,7 +12,7 @@ export declare const reservedTableKeys: string[];
 /**
  * One of the supported Rljson table types
  */
-export type TableType = BuffetsTable | IngredientsTable<any> | LayersTable | SliceIdsTable | CakesTable;
+export type TableType = BuffetsTable | IngredientsTable<any> | LayersTable | SliceIdsTable | CakesTable | RevisionsTable;
 /** The rljson data format */
 export interface Rljson extends Json {
     [tableId: TableKey]: TableType;

package/dist/rljson.js

@@ -9,11 +9,20 @@ const bakeryExample = () => {
     _type: "ingredients",
     _data: [
       {
+        id: "flour",
         energy: 364,
         fat: 0.98,
         protein: 10.33,
         carbohydrates: 76.31,
         _hash: ""
+      },
+      {
+        id: "flour",
+        energy: 364.1,
+        fat: 0.981,
+        protein: 10.331,
+        carbohydrates: 76.311,
+        _hash: ""
       }
     ],
     _hash: ""
@@ -22,7 +31,7 @@ const bakeryExample = () => {
     _type: "ingredients",
     _data: [
       {
-        name: "flour",
+        id: "flour",
         amountUnit: "g",
         nutritionalValuesRef: nutritionalValues._data[0]._hash,
         _hash: ""
@@ -34,6 +43,7 @@ const bakeryExample = () => {
     _type: "ingredients",
     _data: [
       {
+        id: "flour",
         ingredientsRef: ingredients._data[0]._hash,
         quantity: 500,
         _hash: ""
@@ -45,6 +55,7 @@ const bakeryExample = () => {
     _type: "layers",
     _data: [
       {
+        id: "tastyCake",
         ingredientsTable: "recipeIngredients",
         assign: {
           flour: recipeIngredients._data[0]._hash
@@ -70,23 +81,21 @@ const bakeryExample = () => {
     _data: [
       {
         add: ["slice0", "slice1"],
-        remove: [],
-        _hash: ""
+        remove: []
       }
-    ],
-    _hash: ""
+    ]
   });
   const cakes = hip({
     _type: "cakes",
     _data: [
       {
+        id: "cake1",
         sliceIdsTable: "slices",
         sliceIds: slices._data[0]._hash,
         layersTable: "layers",
         layers: {
           flour: layers._data[0]._hash
-        },
-        _hash: ""
+        }
       }
     ]
   });
@@ -94,6 +103,7 @@ const bakeryExample = () => {
     _type: "buffets",
     _data: [
       {
+        id: "salesCounter",
         items: [
           {
             table: "cakes",
@@ -156,37 +166,32 @@ __publicField(_Example, "ok", {
           _hash: "",
           key: "table",
           type: "ingredients",
+          isHead: false,
+          isRoot: false,
+          isShared: true,
           columns: {
             int: {
-              key: "int",
               type: "number"
             },
             double: {
-              key: "double",
               type: "number"
             },
             string: {
-              key: "string",
               type: "string"
             },
             boolean: {
-              key: "boolean",
               type: "boolean"
             },
             null: {
-              key: "null",
               type: "null"
             },
             jsonArray: {
-              key: "jsonArray",
               type: "jsonArray"
             },
             json: {
-              key: "json",
               type: "json"
             },
             jsonValue: {
-              key: "jsonValue",
               type: "jsonValue"
             }
           }
@@ -399,7 +404,10 @@ __publicField(_Example, "broken", {
       const result = _Example.ok.singleRow();
       const tableCfg = result.tableCfgs._data[0];
       tableCfg.columns["int"].type = "numberBroken";
-      return hip(result, true, false);
+      return hip(result, {
+        updateExistingHashes: true,
+        throwOnWrongHashes: false
+      });
     }
   },
   layers: {
@@ -407,13 +415,19 @@ __publicField(_Example, "broken", {
       const result = _Example.ok.complete();
       const layer1 = result.layers._data[1];
       layer1.base = "MISSING";
-      return hip(result, true, false);
+      return hip(result, {
+        updateExistingHashes: true,
+        throwOnWrongHashes: false
+      });
     },
     missingSliceIdSet: () => {
       const result = _Example.ok.complete();
       const layer1 = result.layers._data[1];
       layer1.sliceIds = "MISSING1";
-      return hip(result, true, false);
+      return hip(result, {
+        updateExistingHashes: true,
+        throwOnWrongHashes: false
+      });
     },
     missingAssignedIngredientTable: () => {
       const result = _Example.ok.complete();
@@ -423,27 +437,39 @@ __publicField(_Example, "broken", {
     missingAssignedIngredient: () => {
       const result = _Example.ok.complete();
       result.ingredients._data.splice(1, 2);
-      return hip(result, true, false);
+      return hip(result, {
+        updateExistingHashes: true,
+        throwOnWrongHashes: false
+      });
     }
   },
   cakes: {
     missingSliceIdSet: () => {
       const result = _Example.ok.complete();
       result.cakes._data[0].sliceIds = "MISSING";
-      hip(result.cakes, true, false);
+      hip(result.cakes, {
+        updateExistingHashes: true,
+        throwOnWrongHashes: false
+      });
       return result;
     },
     missingLayersTable: () => {
       const result = _Example.ok.complete();
       result.cakes._data[0].layersTable = "MISSING";
-      hip(result.cakes, true, false);
+      hip(result.cakes, {
+        updateExistingHashes: true,
+        throwOnWrongHashes: false
+      });
       return result;
     },
     missingCakeLayer: () => {
       const result = _Example.ok.complete();
       result.cakes._data[0].layers["layer0"] = "MISSING0";
       result.cakes._data[0].layers["layer1"] = "MISSING1";
-      hip(result.cakes, true, false);
+      hip(result.cakes, {
+        updateExistingHashes: true,
+        throwOnWrongHashes: false
+      });
       return result;
     }
   },
@@ -453,7 +479,7 @@ __publicField(_Example, "broken", {
       const buffet = result.buffets._data[0];
       buffet.items[0].table = "MISSING0";
       buffet.items[1].table = "MISSING1";
-      hip(result, true, false);
+      hip(result, { updateExistingHashes: true, throwOnWrongHashes: false });
       return result;
     },
     missingItems: () => {
@@ -461,7 +487,7 @@ __publicField(_Example, "broken", {
       const buffet = result.buffets._data[0];
       buffet.items[0].ref = "MISSING0";
       buffet.items[1].ref = "MISSING1";
-      hip(result, true, false);
+      hip(result, { updateExistingHashes: true, throwOnWrongHashes: false });
       return result;
     }
   }
@@ -475,15 +501,16 @@ const exampleTableCfg = (tableCfg = void 0) => {
     version: 1,
     columns: (tableCfg == null ? void 0 : tableCfg.columns) ?? {
       a: {
-        key: "a",
         type: "string"
       },
       b: {
-        key: "b",
         type: "number"
       }
     },
-    type: (tableCfg == null ? void 0 : tableCfg.type) ?? "ingredients"
+    type: (tableCfg == null ? void 0 : tableCfg.type) ?? "ingredients",
+    isHead: true,
+    isRoot: true,
+    isShared: false
   };
 };
 // @license
@@ -511,7 +538,13 @@ const rljsonIndexed = (rljson) => {
 };
 // @license
 const reservedFieldNames = ["_type", "_data"];
-const reservedTableKeys = ["_hash", "sliceIds", "tableCfgs"];
+const reservedTableKeys = [
+  "_hash",
+  "sliceIds",
+  "tableCfgs",
+  "reverseRefs",
+  "revisions"
+];
 const exampleRljson = () => Example.ok.singleRow();
 const iterateTables = (rljson, callback) => {
   for (const tableKey in rljson) {
@@ -587,6 +620,8 @@ class _BaseValidator {
       () => this._missingColumnConfigs(),
       () => this._dataDoesNotMatchColumnConfig(),
       () => this._tableTypesDoNotMatch(),
+      () => this._tableCfgHasRootHeadSharedError(),
+      () => this._rootOrHeadTableHasNoIdColumn(),
       // Check references
       () => this._refsNotFound(),
       // Check layers
@@ -893,6 +928,76 @@ class _BaseValidator {
     }
   }
   // ...........................................................................
+  _tableCfgHasRootHeadSharedError() {
+    const rljson = this.rljson;
+    const inconsistentTableCfgs = [];
+    for (const tableKey of this.tableKeys) {
+      const table = rljson[tableKey];
+      const cfgRef = table._tableCfg;
+      if (!cfgRef) {
+        continue;
+      }
+      const cfg = this.rljsonIndexed.tableCfgs._data[cfgRef];
+      const { isRoot, isHead, isShared } = cfg;
+      if (isShared && (isRoot || isHead)) {
+        inconsistentTableCfgs.push({
+          error: "Tables with isShared = true must have isRoot = false and isHead = false",
+          table: tableKey,
+          tableCfg: cfgRef
+        });
+      } else if (isRoot && !isHead) {
+        inconsistentTableCfgs.push({
+          error: "Tables with isRoot = true must also have isHead = true",
+          table: tableKey,
+          tableCfg: cfgRef
+        });
+      } else if (!isRoot && !isHead && !isShared) {
+        inconsistentTableCfgs.push({
+          error: "Tables must be either root, root+head or shared",
+          table: tableKey,
+          tableCfg: cfgRef
+        });
+      }
+    }
+    if (inconsistentTableCfgs.length > 0) {
+      this.errors.tableCfgHasRootHeadSharedError = {
+        error: "Table configs have inconsistent root/head/shared settings",
+        tables: inconsistentTableCfgs
+      };
+    }
+  }
+  // ...........................................................................
+  _rootOrHeadTableHasNoIdColumn() {
+    const rljson = this.rljson;
+    const rootOrHeadTablesWithoutIdColumns = [];
+    for (const tableKey of this.tableKeys) {
+      const table = rljson[tableKey];
+      const cfgRef = table._tableCfg;
+      if (!cfgRef) {
+        continue;
+      }
+      const cfg = this.rljsonIndexed.tableCfgs._data[cfgRef];
+      const isRootOrHeadTable = cfg.isRoot || cfg.isHead;
+      if (!isRootOrHeadTable) {
+        continue;
+      }
+      const columns = cfg.columns;
+      const idField = columns["id"];
+      if (!idField) {
+        rootOrHeadTablesWithoutIdColumns.push({
+          table: tableKey,
+          tableCfg: cfgRef
+        });
+      }
+    }
+    if (rootOrHeadTablesWithoutIdColumns.length > 0) {
+      this.errors.rootOrHeadTableHasNoIdColumn = {
+        error: "Root or head tables must have an id column",
+        tables: rootOrHeadTablesWithoutIdColumns
+      };
+    }
+  }
+  // ...........................................................................
   _dataHasWrongType() {
     const rljson = this.rljson;
     const tablesWithWrongType = [];

package/dist/src/example.ts

@@ -49,37 +49,32 @@ export class Example {
             _hash: '',
             key: 'table',
             type: 'ingredients',
+            isHead: false,
+            isRoot: false,
+            isShared: true,
             columns: {
               int: {
-                key: 'int',
                 type: 'number',
               },
               double: {
-                key: 'double',
                 type: 'number',
               },
               string: {
-                key: 'string',
                 type: 'string',
               },
               boolean: {
-                key: 'boolean',
                 type: 'boolean',
               },
               null: {
-                key: 'null',
                 type: 'null',
               },
               jsonArray: {
-                key: 'jsonArray',
                 type: 'jsonArray',
               },
               json: {
-                key: 'json',
                 type: 'json',
               },
               jsonValue: {
-                key: 'jsonValue',
                 type: 'jsonValue',
               },
             },
@@ -309,7 +304,10 @@ export class Example {
         const result = Example.ok.singleRow();
         const tableCfg = result.tableCfgs._data[0];
         tableCfg.columns['int'].type = 'numberBroken'; // Break one of the types
-        return hip(result, true, false);
+        return hip(result, {
+          updateExistingHashes: true,
+          throwOnWrongHashes: false,
+        });
       },
     },
 
@@ -320,7 +318,10 @@ export class Example {
         layer1.base = 'MISSING'; // Missing base
 
         // Recalculate hashes
-        return hip(result, true, false);
+        return hip(result, {
+          updateExistingHashes: true,
+          throwOnWrongHashes: false,
+        });
       },
 
       missingSliceIdSet: (): Rljson => {
@@ -330,7 +331,10 @@ export class Example {
         layer1.sliceIds = 'MISSING1';
 
         // Recalculate hashes
-        return hip(result, true, false);
+        return hip(result, {
+          updateExistingHashes: true,
+          throwOnWrongHashes: false,
+        });
       },
 
       missingAssignedIngredientTable: (): Rljson => {
@@ -342,7 +346,10 @@ export class Example {
       missingAssignedIngredient: (): Rljson => {
         const result = Example.ok.complete();
         result.ingredients._data.splice(1, 2); // Remove an ingredient that is assigned
-        return hip(result, true, false);
+        return hip(result, {
+          updateExistingHashes: true,
+          throwOnWrongHashes: false,
+        });
       },
     },
 
@@ -350,14 +357,20 @@ export class Example {
       missingSliceIdSet: (): Rljson => {
         const result = Example.ok.complete();
         result.cakes._data[0].sliceIds = 'MISSING'; // Missing ID set
-        hip(result.cakes, true, false);
+        hip(result.cakes, {
+          updateExistingHashes: true,
+          throwOnWrongHashes: false,
+        });
         return result;
       },
 
       missingLayersTable: (): Rljson => {
         const result = Example.ok.complete();
         result.cakes._data[0].layersTable = 'MISSING'; // Missing layers table
-        hip(result.cakes, true, false);
+        hip(result.cakes, {
+          updateExistingHashes: true,
+          throwOnWrongHashes: false,
+        });
         return result;
       },
 
@@ -365,7 +378,10 @@ export class Example {
         const result = Example.ok.complete();
         result.cakes._data[0].layers['layer0'] = 'MISSING0';
         result.cakes._data[0].layers['layer1'] = 'MISSING1';
-        hip(result.cakes, true, false);
+        hip(result.cakes, {
+          updateExistingHashes: true,
+          throwOnWrongHashes: false,
+        });
         return result;
       },
     },
@@ -376,7 +392,7 @@ export class Example {
         const buffet = result.buffets._data[0];
         buffet.items[0].table = 'MISSING0';
         buffet.items[1].table = 'MISSING1';
-        hip(result, true, false);
+        hip(result, { updateExistingHashes: true, throwOnWrongHashes: false });
         return result;
       },
 
@@ -385,7 +401,7 @@ export class Example {
         const buffet = result.buffets._data[0];
         buffet.items[0].ref = 'MISSING0';
         buffet.items[1].ref = 'MISSING1';
-        hip(result, true, false);
+        hip(result, { updateExistingHashes: true, throwOnWrongHashes: false });
         return result;
       },
     },

package/dist/typedefs.d.ts

@@ -1,4 +1,4 @@
-import { JsonKey } from '@rljson/json';
+import { Json, JsonKey } from '@rljson/json';
 /**
  * A ref is a hash that references to another element
  */
@@ -37,3 +37,9 @@ export declare const exampleTypedefs: () => {
     tableKey: TableKey;
     contentType: ContentType;
 };
+/**
+ * A json object with an optional id
+ */
+export type JsonWithId = Json & {
+    id?: string;
+};

package/dist/validate/base-validator.d.ts

@@ -16,6 +16,8 @@ export interface BaseErrors extends Errors {
     columnConfigNotFound?: Json;
     dataDoesNotMatchColumnConfig?: Json;
     tableTypesDoNotMatch?: Json;
+    rootOrHeadTableHasNoIdColumn?: Json;
+    tableCfgHasRootHeadSharedError?: Json;
     refsNotFound?: Json;
     layerBasesNotFound?: Json;
     layerSliceIdsTableNotFound?: Json;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/rljson",
-  "version": "0.0.33",
+  "version": "0.0.34",
   "packageManager": "pnpm@10.6.3",
   "description": "The RLJSON data format specification",
   "homepage": "https://github.com/rljson/rljson",
@@ -29,10 +29,10 @@
     "updateGoldens": "cross-env UPDATE_GOLDENS=true npm test"
   },
   "devDependencies": {
-    "@types/node": "^22.13.14",
-    "@typescript-eslint/eslint-plugin": "^8.28.0",
-    "@typescript-eslint/parser": "^8.28.0",
-    "@vitest/coverage-v8": "^3.0.9",
+    "@types/node": "^22.13.17",
+    "@typescript-eslint/eslint-plugin": "^8.29.0",
+    "@typescript-eslint/parser": "^8.29.0",
+    "@vitest/coverage-v8": "^3.1.1",
     "cross-env": "^7.0.3",
     "eslint": "^9.23.0",
     "eslint-plugin-jsdoc": "^50.6.9",
@@ -41,16 +41,16 @@
     "jsdoc": "^4.0.4",
     "read-pkg": "^9.0.1",
     "typescript": "~5.8.2",
-    "typescript-eslint": "^8.28.0",
-    "vite": "^6.2.3",
-    "vite-node": "^3.0.9",
+    "typescript-eslint": "^8.29.0",
+    "vite": "^6.2.4",
+    "vite-node": "^3.1.1",
     "vite-plugin-dts": "^4.5.3",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^3.0.9",
+    "vitest": "^3.1.1",
     "vitest-dom": "^0.1.1"
   },
   "dependencies": {
-    "@rljson/hash": "^0.0.12",
+    "@rljson/hash": "^0.0.13",
     "@rljson/json": "^0.0.18"
   },
   "pnpm": {