@rljson/rljson 0.0.61 → 0.0.62

package/dist/content/cake.d.ts

@@ -43,7 +43,7 @@ export type CakesTable = RljsonTable<Cake, 'cakes'>;
 /**
  * Sample Table as BoilerPlate for Tests and Examples
  */
-/**
+/**pnpm build
  * Sample Table as BoilerPlate for Tests and Examples
  * @param cakeKey - the key of the cake table cfg
  */

package/dist/edit/edit-validator.d.ts

@@ -0,0 +1,24 @@
+import { Json } from '@rljson/json';
+import { Errors } from '../validate/validate.ts';
+import { Edit } from './edit.ts';
+export interface EditErrors extends Errors {
+    invalidObject?: Json;
+    parameterInvalid?: Json;
+    parameterRouteInvalid?: Json;
+    parameterCommandInvalid?: Json;
+    parameterValueInvalid?: Json;
+    parameterOriginInvalid?: Json;
+    parameterPreviousInvalid?: Json;
+    routeInvalid?: Json;
+    dataRouteMismatch?: Json;
+}
+export declare class EditValidator<T extends Json> {
+    private _edit;
+    errors: EditErrors;
+    get hasErrors(): boolean;
+    constructor(_edit: Edit<T>);
+    validate(): EditErrors;
+    private _checkMatchingRefs;
+    static create(edit: Edit<any>): EditValidator<any>;
+}
+export declare const validateEdit: (edit: Edit<any>) => EditErrors;

package/dist/edit/edit.d.ts

@@ -1,18 +1,24 @@
-import { Json, JsonH, JsonValueH } from '@rljson/json';
+import { Json } from '@rljson/json';
 import { Ref } from '../typedefs.ts';
-import { RouteRef } from './route.ts';
+import { TableCfg } from '../content/table-cfg.ts';
 import { RljsonTable } from '../rljson.ts';
+import { RouteRef } from '../route/route.ts';
 /**
  * An Edit Object describing edits on data basically
  */
 export type EditRef = Ref;
+export type EditCommand = 'add' | 'remove';
+/**
+ * An Edit describes a change to be applied to an Rljson object.
+ * @param T - The type of the value being edited, extending Json
+ */
 export type Edit<T extends Json> = {
-    value: T & JsonValueH;
+    command: EditCommand;
+    value: T;
     route: RouteRef;
     origin?: Ref;
-    previous?: EditProtocolTimeId[];
     acknowledged?: boolean;
-} & JsonH;
+};
 export type EditProtocolTimeId = string;
 export type EditProtocolRow<Str extends string> = {
     [key in Str as `${Uncapitalize<string & key>}Ref`]: string;
@@ -23,6 +29,12 @@ export type EditProtocolRow<Str extends string> = {
     previous?: EditProtocolTimeId[];
 };
 export type EditProtocol<Str extends string> = RljsonTable<EditProtocolRow<Str>, 'edits'>;
+/**
+ * Creates a TableCfg for an Edit Protocol table for the given table configuration
+ * @param tableCfg - The table configuration to create the Edit Protocol table for
+ * @returns The TableCfg for the Edit Protocol table
+ */
+export declare const createEditProtocolTableCfg: (tableCfg: TableCfg) => TableCfg;
 /**
  * Provides an example Edits table for test purposes
  */

package/dist/index.d.ts

@@ -5,11 +5,12 @@ export * from './content/layer.ts';
 export * from './content/revision.ts';
 export * from './content/slice-ids.ts';
 export * from './content/table-cfg.ts';
+export * from './edit/edit-validator.ts';
 export * from './edit/edit.ts';
-export * from './edit/route.ts';
 export * from './example.ts';
 export * from './example/bakery-example.ts';
 export * from './rljson.ts';
+export * from './route/route.ts';
 export * from './tools/remove-duplicates.ts';
 export * from './tools/time-id.ts';
 export * from './typedefs.ts';

package/dist/rljson.js

@@ -3,36 +3,166 @@ import { exampleJsonObject, jsonValueTypes, jsonValueMatchesType, jsonValueType
 import { nanoid } from "nanoid";
 // @license
 class Route {
-  constructor(segments) {
-    this.segments = segments;
+  constructor(_segments) {
+    this._segments = _segments;
   }
+  // .............................................................................
+  /**
+   * Creates a Route from a flat string representation.
+   * @param route - The flat string representation of the route (e.g. "/a/b/c")
+   * @returns A Route object
+   */
   static fromFlat(route) {
-    return new Route(route.split("/").filter(Boolean));
+    const segmentsFlat = route.split("/").filter((s) => s.length > 0);
+    const segments = [];
+    for (const segmentFlat of segmentsFlat) {
+      const [tableKey, refFlat] = segmentFlat.split("@");
+      const ref = !!refFlat ? refFlat.split(":").length == 2 ? { [tableKey + "EditsRef"]: refFlat } : { [tableKey + "Ref"]: refFlat } : {};
+      const segment = {
+        tableKey,
+        ...ref
+      };
+      segments.push(segment);
+    }
+    return new Route(segments);
   }
+  // .............................................................................
+  /**
+   * Returns the segment at the given index or the last segment if no index is provided.
+   * @param index - The index of the segment to return (optional)
+   * @returns The segment at the given index or the last segment
+   */
   segment(index) {
     if (index === void 0) {
-      return this.segments[this.segments.length - 1];
+      return this._segments[this._segments.length - 1];
     }
-    return this.segments[index];
+    return this._segments[index];
   }
+  // .............................................................................
+  /**
+   * Returns a new Route that is one level deeper than the current route.
+   * If steps is provided, it returns a new Route that is 'steps' levels deeper.
+   * @param steps - The number of levels to go deeper (optional)
+   * @returns A new Route that is one level deeper or 'steps' levels deeper
+   */
   deeper(steps) {
     if (steps === void 0) {
-      return new Route(this.segments.slice(1, this.segments.length));
+      return new Route(this._segments.slice(1, this._segments.length));
     } else {
       if (steps < 1) {
         throw new Error("Steps must be greater than 0");
       }
-      if (steps >= this.segments.length) {
+      if (steps >= this._segments.length) {
         throw new Error("Cannot go deeper than the root");
       }
-      return new Route(this.segments.slice(steps, this.segments.length));
+      return new Route(this._segments.slice(steps, this._segments.length));
     }
   }
+  // .............................................................................
+  /**
+   * Checks if the current route is the root route.
+   * @returns True if the current route is the root route, false otherwise
+   */
   get isRoot() {
-    return this.segments.length === 1;
+    return this._segments.length === 1;
   }
+  // .............................................................................
+  /**
+   * Returns the flat string representation of the route.
+   * @returns The flat string representation of the route (e.g. "/a/b/c")
+   */
   get flat() {
-    return "/" + this.segments.join("/");
+    let flat = "";
+    for (const segment of this._segments) {
+      const tableKey = segment.tableKey;
+      const ref = Object.keys(segment).filter((k) => k !== "tableKey")[0];
+      flat += `/${tableKey}${ref ? `@${segment[ref]}` : ""}`;
+    }
+    return flat;
+  }
+  // .............................................................................
+  /**
+   * Returns the segments of the route as an array of strings.
+   * @returns The segments of the route as an array of strings
+   */
+  get segments() {
+    return this._segments;
+  }
+  // .............................................................................
+  /**
+   * Returns the root segment of the route.
+   * @returns The root segment of the route
+   */
+  get root() {
+    return this.segment();
+  }
+  // .............................................................................
+  /**
+   * Returns the top level segment of the route.
+   * @returns The top level segment of the route
+   */
+  get top() {
+    return this.segment(0);
+  }
+  // .............................................................................
+  /**
+   * Returns the next segment of the route if it exists.
+   * @returns The next segment of the route or undefined if it doesn't exist
+   */
+  get next() {
+    return this._segments.length > 1 ? this._segments[1] : void 0;
+  }
+  // .............................................................................
+  /**
+   * Checks if the route is valid (i.e. has at least one segment and no empty segments).
+   * @returns True if the route is valid, false otherwise
+   */
+  get isValid() {
+    return this._segments.length > 0 && this._segments.every((s) => s.tableKey.length > 0);
+  }
+  // .............................................................................
+  /**
+   * Returns the reference of a segment if it exists.
+   * @param segment - The segment to get the reference from
+   * @returns The reference of the segment or undefined if it doesn't exist
+   */
+  static segmentRef(segment) {
+    if (this.segmentHasRef(segment)) {
+      const refKey = Object.keys(segment).find(
+        (k) => k.endsWith("Ref") && k !== "tableKey"
+      );
+      if (refKey) {
+        return segment[refKey];
+      }
+    }
+    return void 0;
+  }
+  // .............................................................................
+  /**
+   * Checks if a segment has any reference (either default or protocol).
+   * @param segment - The segment to check
+   * @returns True if the segment has any reference, false otherwise
+   */
+  static segmentHasRef(segment) {
+    return Object.keys(segment).some((k) => k.endsWith("Ref"));
+  }
+  // .............................................................................
+  /**
+   * Checks if a segment has a default reference (i.e. not a protocol reference).
+   * @param segment - The segment to check
+   * @returns True if the segment has a default reference, false otherwise
+   */
+  static segmentHasDefaultRef(segment) {
+    return this.segmentHasRef(segment) && !this.segmentHasProtocolRef(segment);
+  }
+  // .............................................................................
+  /**
+   * Checks if a segment has a protocol reference (i.e. an EditsRef).
+   * @param segment - The segment to check
+   * @returns True if the segment has a protocol reference, false otherwise
+   */
+  static segmentHasProtocolRef(segment) {
+    return this.segmentHasRef(segment) && Object.keys(segment).some((k) => k.endsWith("EditsRef"));
   }
 }
 // @license
@@ -204,9 +334,10 @@ const createCakeTableCfg = (cakeKey) => ({
   key: cakeKey,
   type: "cakes",
   columns: [
+    { key: "_hash", type: "string" },
     { key: "sliceIdsTable", type: "string" },
     { key: "sliceIdsRow", type: "string" },
-    { key: "layers", type: "jsonArray" },
+    { key: "layers", type: "json" },
     { key: "id", type: "string" }
   ],
   isHead: false,
@@ -221,12 +352,13 @@ const createLayerTableCfg = (layerKey) => ({
   key: layerKey,
   type: "layers",
   columns: [
+    { key: "_hash", type: "string" },
     { key: "base", type: "string" },
     { key: "sliceIdsTable", type: "string" },
     { key: "sliceIdsTableRow", type: "string" },
     { key: "componentsTable", type: "string" },
-    { key: "add", type: "jsonArray" },
-    { key: "remove", type: "jsonArray" }
+    { key: "add", type: "json" },
+    { key: "remove", type: "json" }
   ],
   isHead: false,
   isRoot: false,
@@ -918,6 +1050,107 @@ const exampleTableCfg = (tableCfg = void 0) => {
   };
 };
 // @license
+const objectDepth = (o) => Object(o) === o ? 1 + Math.max(-1, ...Object.values(o).map(objectDepth)) : 0;
+// @license
+class EditValidator {
+  constructor(_edit) {
+    this._edit = _edit;
+  }
+  errors = { hasErrors: false };
+  get hasErrors() {
+    return Object.keys(this.errors).length > 1;
+  }
+  validate() {
+    if (typeof this._edit.route !== "string" || this._edit.route.length === 0) {
+      this.errors.parameterRouteInvalid = {
+        error: "Edit route must be a non-empty string.",
+        parameter: this._edit.route
+      };
+    }
+    if (!this._edit.command.startsWith("add") && !this._edit.command.startsWith("remove")) {
+      this.errors.parameterCommandInvalid = {
+        error: "Edit command must be starting with either 'add' or 'remove'.",
+        parameter: this._edit.command
+      };
+    }
+    if (typeof this._edit.value === "undefined" || typeof this._edit.value !== "object" || this._edit.value === null) {
+      this.errors.parameterValueInvalid = {
+        error: "Edit value must be a non-null object.",
+        parameter: this._edit.value
+      };
+    }
+    if (typeof this._edit.origin !== "undefined" && typeof this._edit.origin !== "string") {
+      this.errors.parameterOriginInvalid = {
+        error: "Edit origin must be a string if defined.",
+        parameter: this._edit.origin
+      };
+    }
+    const route = Route.fromFlat(this._edit.route);
+    if (!route.isValid) {
+      this.errors.routeInvalid = {
+        error: "Edit route is not valid.",
+        route: this._edit.route
+      };
+    }
+    if (route.isValid) {
+      const routeDepth = route.segments.length;
+      const valueDepth = objectDepth(this._edit.value);
+      if (routeDepth !== valueDepth) {
+        this.errors.dataRouteMismatch = {
+          error: "Edit route depth does not match value depth. Route depth must match the depth of the value object.",
+          route: this._edit.route,
+          routeDepth,
+          valueDepth
+        };
+      }
+    }
+    if (typeof this._edit.value === "object" && this._edit.value !== null) {
+      this._checkMatchingRefs(route, this._edit.value);
+    }
+    this.errors.hasErrors = this.hasErrors;
+    return this.errors;
+  }
+  _checkMatchingRefs(route, value) {
+    const next = route.next;
+    const keys = Object.keys(value);
+    for (const key of keys) {
+      if (key.endsWith("Ref") && value[key] !== null && value[key] !== void 0 && typeof value[key] !== "string") {
+        const refObj = value[key];
+        if (!next || next.tableKey !== key.slice(0, -3)) {
+          this.errors.parameterInvalid = {
+            error: `Edit value has a reference key "${key}" that does not match the next route segment.`,
+            parameter: this._edit.value
+          };
+          break;
+        }
+        if (route.deeper().next)
+          this._checkMatchingRefs(route.deeper(), refObj);
+      }
+    }
+  }
+  static create(edit) {
+    return new EditValidator(edit);
+  }
+}
+const validateEdit = (edit) => {
+  return EditValidator.create(edit).validate();
+};
+// @license
+const createEditProtocolTableCfg = (tableCfg) => ({
+  key: `${tableCfg.key}Edits`,
+  type: "edits",
+  columns: [
+    { key: "_hash", type: "string" },
+    { key: "timeId", type: "string" },
+    { key: `${tableCfg.key}Ref`, type: "string" },
+    { key: "route", type: "string" },
+    { key: "origin", type: "string" },
+    { key: "previous", type: "jsonArray" }
+  ],
+  isHead: false,
+  isRoot: false,
+  isShared: false
+});
 const exampleEditsTable = () => bakeryExample().ingredientsEdits;
 // @license
 const reservedFieldNames = ["_data"];
@@ -977,6 +1210,12 @@ const removeDuplicates = (rljson) => {
 const timeId = () => {
   return nanoid(4) + ":" + Date.now();
 };
+const isTimeId = (id) => {
+  const parts = id.split(":");
+  if (parts.length !== 2) return false;
+  if (isNaN(Number(parts[1]))) return false;
+  return parts[0].length === 4;
+};
 // @license
 const contentTypes = [
   "buffets",
@@ -1875,6 +2114,7 @@ class Validate {
 }
 export {
   BaseValidator,
+  EditValidator,
   Example,
   Route,
   Validate,
@@ -1882,6 +2122,7 @@ export {
   bakeryExample,
   contentTypes,
   createCakeTableCfg,
+  createEditProtocolTableCfg,
   createLayerTableCfg,
   exampleBuffetsTable,
   exampleCakesTable,
@@ -1894,6 +2135,7 @@ export {
   exampleTableCfg,
   exampleTableCfgTable,
   exampleTypedefs,
+  isTimeId,
   isValidFieldName,
   iterateTables,
   iterateTablesSync,
@@ -1902,5 +2144,6 @@ export {
   reservedTableKeys,
   throwOnInvalidTableCfg,
   timeId,
+  validateEdit,
   validateRljsonAgainstTableCfg
 };

package/dist/route/route.d.ts

@@ -0,0 +1,93 @@
+import { TableKey } from '../typedefs.ts';
+export type RouteRef = string;
+export type RouteSegment<Str extends string> = {
+    [key in Str as `${Uncapitalize<string & key>}Ref`]: string;
+} & {
+    tableKey: TableKey;
+};
+export type RouteSegmentFlat<N extends string> = `${N}` | `${N}@${string}` | `${N}@${string}:${string}`;
+/**
+ * A class to handle routes in an Rljson object.
+ */
+export declare class Route {
+    private readonly _segments;
+    constructor(_segments: RouteSegment<any>[]);
+    /**
+     * Creates a Route from a flat string representation.
+     * @param route - The flat string representation of the route (e.g. "/a/b/c")
+     * @returns A Route object
+     */
+    static fromFlat(route: string): Route;
+    /**
+     * Returns the segment at the given index or the last segment if no index is provided.
+     * @param index - The index of the segment to return (optional)
+     * @returns The segment at the given index or the last segment
+     */
+    segment(index?: number): RouteSegment<any>;
+    /**
+     * Returns a new Route that is one level deeper than the current route.
+     * If steps is provided, it returns a new Route that is 'steps' levels deeper.
+     * @param steps - The number of levels to go deeper (optional)
+     * @returns A new Route that is one level deeper or 'steps' levels deeper
+     */
+    deeper(steps?: number): Route;
+    /**
+     * Checks if the current route is the root route.
+     * @returns True if the current route is the root route, false otherwise
+     */
+    get isRoot(): boolean;
+    /**
+     * Returns the flat string representation of the route.
+     * @returns The flat string representation of the route (e.g. "/a/b/c")
+     */
+    get flat(): string;
+    /**
+     * Returns the segments of the route as an array of strings.
+     * @returns The segments of the route as an array of strings
+     */
+    get segments(): RouteSegment<any>[];
+    /**
+     * Returns the root segment of the route.
+     * @returns The root segment of the route
+     */
+    get root(): RouteSegment<any>;
+    /**
+     * Returns the top level segment of the route.
+     * @returns The top level segment of the route
+     */
+    get top(): RouteSegment<any>;
+    /**
+     * Returns the next segment of the route if it exists.
+     * @returns The next segment of the route or undefined if it doesn't exist
+     */
+    get next(): RouteSegment<any> | undefined;
+    /**
+     * Checks if the route is valid (i.e. has at least one segment and no empty segments).
+     * @returns True if the route is valid, false otherwise
+     */
+    get isValid(): boolean;
+    /**
+     * Returns the reference of a segment if it exists.
+     * @param segment - The segment to get the reference from
+     * @returns The reference of the segment or undefined if it doesn't exist
+     */
+    static segmentRef(segment: RouteSegment<any>): string | undefined;
+    /**
+     * Checks if a segment has any reference (either default or protocol).
+     * @param segment - The segment to check
+     * @returns True if the segment has any reference, false otherwise
+     */
+    static segmentHasRef(segment: RouteSegment<any>): boolean;
+    /**
+     * Checks if a segment has a default reference (i.e. not a protocol reference).
+     * @param segment - The segment to check
+     * @returns True if the segment has a default reference, false otherwise
+     */
+    static segmentHasDefaultRef(segment: RouteSegment<any>): boolean;
+    /**
+     * Checks if a segment has a protocol reference (i.e. an EditsRef).
+     * @param segment - The segment to check
+     * @returns True if the segment has a protocol reference, false otherwise
+     */
+    static segmentHasProtocolRef(segment: RouteSegment<any>): boolean;
+}

package/dist/tools/object-depth.d.ts

@@ -0,0 +1 @@
+export declare const objectDepth: (o: object) => number;

package/dist/tools/time-id.d.ts

@@ -1 +1,17 @@
+/**
+ * Generates a new TimeId.
+ * A TimeId is a string in the format "xxxx:timestamp" where:
+ * - "xxxx" is a 4-character unique identifier
+ * - "timestamp" is the current time in milliseconds since epoch
+ * @returns A new TimeId string
+ */
 export declare const timeId: () => string;
+/**
+ * Checks if a given id is a valid TimeId.
+ * A valid TimeId has the format "xxxx:timestamp" where:
+ * - "xxxx" is a 4-character string
+ * - "timestamp" is a valid number representing milliseconds since epoch
+ * @param id - The id to check
+ * @returns True if the id is a valid TimeId, false otherwise
+ */
+export declare const isTimeId: (id: string) => boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/rljson",
-  "version": "0.0.61",
+  "version": "0.0.62",
   "description": "The RLJSON data format specification",
   "homepage": "https://github.com/rljson/rljson",
   "bugs": "https://github.com/rljson/rljson/issues",
@@ -20,20 +20,20 @@
   ],
   "type": "module",
   "devDependencies": {
-    "@types/node": "^24.6.1",
-    "@typescript-eslint/eslint-plugin": "^8.45.0",
-    "@typescript-eslint/parser": "^8.45.0",
+    "@types/node": "^24.7.2",
+    "@typescript-eslint/eslint-plugin": "^8.46.0",
+    "@typescript-eslint/parser": "^8.46.0",
     "@vitest/coverage-v8": "^3.2.4",
     "cross-env": "^10.1.0",
-    "eslint": "^9.36.0",
-    "eslint-plugin-jsdoc": "^60.7.0",
+    "eslint": "^9.37.0",
+    "eslint-plugin-jsdoc": "^61.1.1",
     "eslint-plugin-tsdoc": "^0.4.0",
     "globals": "^16.4.0",
-    "jsdoc": "^4.0.4",
+    "jsdoc": "^4.0.5",
     "read-pkg": "^9.0.1",
     "typescript": "~5.9.3",
-    "typescript-eslint": "^8.45.0",
-    "vite": "^7.1.7",
+    "typescript-eslint": "^8.46.0",
+    "vite": "^7.1.9",
     "vite-node": "^3.2.4",
     "vite-plugin-dts": "^4.5.4",
     "vite-tsconfig-paths": "^5.1.4",

package/dist/edit/route.d.ts

@@ -1,13 +0,0 @@
-export type RouteRef = string;
-/**
- * A class to handle routes in an Rljson object.
- */
-export declare class Route {
-    private segments;
-    constructor(segments: string[]);
-    static fromFlat(route: string): Route;
-    segment(index?: number): string;
-    deeper(steps?: number): Route;
-    get isRoot(): boolean;
-    get flat(): string;
-}