JSON CRDT refactor and automated docs

src/json-crdt-patch/types.ts

@@ -1,11 +1,12 @@
+import type {Printable} from '../util/print/types';
 import type {ITimestampStruct} from './clock';
 import type {JsonCrdtPatchMnemonic} from './codec/verbose';
 
 /**
  * Something in the document that can be identified by ID. All operations have
  * IDs and operations result into JSON nodes and chunks, which also have IDs.
  */
-export interface Identifiable {
+export interface Identifiable extends Printable {
   /**
    * Unique ID within a document.
    */
@@ -17,11 +18,6 @@ export interface Identifiable {
    * the number of entries.
    */
   span?(): number;
-
-  /**
-   * Used for debugging.
-   */
-  toString(tab?: string): string;
 }
 
 /**
@@ -46,13 +42,6 @@ export interface IJsonCrdtPatchOperation extends Identifiable {
    * User friendly name of the operation.
    */
   name(): JsonCrdtPatchMnemonic;
-
-  /**
-   * Returns a textual human-readable representation of the operation.
-   *
-   * @param tab String to use for indentation.
-   */
-  toString(tab?: string): string;
 }
 
 /**

src/json-crdt/codec/indexed/binary/Decoder.ts

@@ -6,7 +6,7 @@ import {CrdtReader} from '../../../../json-crdt-patch/util/binary/CrdtDecoder';
 import {IndexedFields, FieldName, IndexedNodeFields} from './types';
 import {ITimestampStruct, IVectorClock, Timestamp, VectorClock} from '../../../../json-crdt-patch/clock';
 import {JsonNode} from '../../../types';
-import {Model, UNDEFINED} from '../../../model';
+import {Model, UNDEFINED} from '../../../model/Model';
 import {MsgPackDecoderFast} from '../../../../json-pack/msgpack';
 import {ObjectLww} from '../../../types/lww-object/ObjectLww';
 import {StringChunk, StringRga} from '../../../types/rga-string/StringRga';

src/json-crdt/codec/structural/binary/Decoder.ts

@@ -4,7 +4,7 @@ import {ClockDecoder} from '../../../../json-crdt-patch/codec/clock/ClockDecoder
 import {Const} from '../../../types/const/Const';
 import {CrdtReader} from '../../../../json-crdt-patch/util/binary/CrdtDecoder';
 import {ITimestampStruct, Timestamp} from '../../../../json-crdt-patch/clock';
-import {Model, UNDEFINED} from '../../../model';
+import {Model, UNDEFINED} from '../../../model/Model';
 import {MsgPackDecoderFast} from '../../../../json-pack/msgpack';
 import {ObjectLww} from '../../../types/lww-object/ObjectLww';
 import {RootLww} from '../../../types/lww-root/RootLww';

src/json-crdt/index.ts

@@ -1,3 +1,3 @@
-export * from './types/types';
+export * from './types';
 export * from './extensions/types';
 export * from './model';

src/json-crdt/model/Model.ts

@@ -1,6 +1,4 @@
 import * as operations from '../../json-crdt-patch/operations';
-import {ArrayRga} from '../types/rga-array/ArrayRga';
-import {BinaryRga} from '../types/rga-binary/BinaryRga';
 import {Const} from '../types/const/Const';
 import {encoder, decoder} from '../codec/structural/binary/shared';
 import {
@@ -13,13 +11,9 @@ import {
 } from '../../json-crdt-patch/clock';
 import {JsonCrdtPatchOperation, Patch} from '../../json-crdt-patch/Patch';
 import {ModelApi} from './api/ModelApi';
-import {ObjectLww} from '../types/lww-object/ObjectLww';
 import {ORIGIN, SESSION, SYSTEM_SESSION_TIME} from '../../json-crdt-patch/constants';
 import {randomSessionId} from './util';
-import {RootLww} from '../types/lww-root/RootLww';
-import {StringRga} from '../types/rga-string/StringRga';
-import {ValueLww} from '../types/lww-value/ValueLww';
-import {ArrayLww} from '../types/lww-array/ArrayLww';
+import {RootLww, ValueLww, ArrayLww, ObjectLww, StringRga, BinaryRga, ArrayRga} from '../types';
 import {printTree} from '../../util/print/printTree';
 import {Extensions} from '../extensions/Extensions';
 import {AvlMap} from '../../util/trees/avl/AvlMap';
@@ -30,8 +24,7 @@ export const UNDEFINED = new Const(ORIGIN, undefined);
 
 /**
  * In instance of Model class represents the underlying data structure,
- * i.e. model, of the JSON CRDT document. The `.toJson()` can be called to
- * compute the "view" of the model.
+ * i.e. model, of the JSON CRDT document.
  */
 export class Model<RootJsonNode extends JsonNode = JsonNode> implements Printable {
   /**
@@ -92,12 +85,16 @@ export class Model<RootJsonNode extends JsonNode = JsonNode> implements Printabl
   /**
    * Index of all known node objects (objects, array, strings, values)
    * in this document.
+   *
+   * @ignore
    */
   public index = new AvlMap<ITimestampStruct, JsonNode>(compare);
 
   /**
    * Extensions to the JSON CRDT protocol. Extensions are used to implement
    * custom data types on top of the JSON CRDT protocol.
+   *
+   * @ignore
    */
   public ext: Extensions = new Extensions();
 
@@ -106,29 +103,45 @@ export class Model<RootJsonNode extends JsonNode = JsonNode> implements Printabl
     if (!clock.time) clock.time = 1;
   }
 
+  /** @ignore */
   private _api?: ModelApi<RootJsonNode>;
 
   /**
-   * API for applying changes to the current document.
+   * API for applying local changes to the current document.
    */
   public get api(): ModelApi<RootJsonNode> {
     if (!this._api) this._api = new ModelApi<RootJsonNode>(this);
     return this._api;
   }
 
   /**
-   * @private
    * Experimental node retrieval API using proxy objects.
    */
   public get find() {
     return this.api.r.proxy();
   }
 
-  /** Tracks number of times the `applyPatch` was called. */
+  /**
+   * Tracks number of times the `applyPatch` was called.
+   *
+   * @ignore
+   */
   public tick: number = 0;
 
+  /**
+   * Callback called after every `applyPatch` call.
+   *
+   * When using the `.api` API, this property is set automatically by
+   * the {@link ModelApi} class. In that case use the `mode.api.evens.on('change')`
+   * to subscribe to changes.
+   */
   public onchange: undefined | (() => void) = undefined;
 
+  /**
+   * Applies a batch of patches to the document.
+   *
+   * @param patches A batch, i.e. an array of patches.
+   */
   public applyBatch(patches: Patch[]) {
     const length = patches.length;
     for (let i = 0; i < length; i++) this.applyPatch(patches[i]);
@@ -154,6 +167,7 @@ export class Model<RootJsonNode extends JsonNode = JsonNode> implements Printabl
    * the `tick` property and call `onchange` after calling this method.
    *
    * @param op Any JSON CRDT Patch operation
+   * @ignore
    */
   public applyOperation(op: JsonCrdtPatchOperation): void {
     this.clock.observe(op.id, op.span());
@@ -261,6 +275,8 @@ export class Model<RootJsonNode extends JsonNode = JsonNode> implements Printabl
   /**
    * Recursively deletes a tree of nodes. Used when root node is overwritten or
    * when object contents of container node (object or array) is removed.
+   *
+   * @ignore
    */
   protected deleteNodeTree(value: ITimestampStruct) {
     const isSystemNode = value.sid === SESSION.SYSTEM;
@@ -272,7 +288,11 @@ export class Model<RootJsonNode extends JsonNode = JsonNode> implements Printabl
   }
 
   /**
-   * Creates a copy of this model with a new session ID.
+   * Creates a copy of this model with a new session ID. If the session ID is
+   * not provided, a random session ID is generated.
+   *
+   * @param sessionId Session ID to use for the new model.
+   * @returns A copy of this model with a new session ID.
    */
   public fork(sessionId: number = randomSessionId()): Model {
     const copy = Model.fromBinary(this.toBinary());
@@ -283,21 +303,33 @@ export class Model<RootJsonNode extends JsonNode = JsonNode> implements Printabl
 
   /**
    * Creates a copy of this model with the same session ID.
+   *
+   * @returns A copy of this model with the same session ID.
    */
   public clone(): Model {
     return this.fork(this.clock.sid);
   }
 
   /**
-   * @returns Returns the view of the model.
+   * Returns the view of the model.
+   *
+   * @returns JSON/CBOR of the model.
    */
   public view(): Readonly<JsonNodeView<RootJsonNode>> {
     return this.root.view();
   }
 
   /**
-   * @returns Returns human-readable text for debugging.
+   * Serialize this model using "binary" structural encoding.
+   *
+   * @returns This model encoded in octets.
    */
+  public toBinary(): Uint8Array {
+    return encoder.encode(this);
+  }
+
+  // ---------------------------------------------------------------- Printable
+
   public toString(tab: string = ''): string {
     const nl = () => '';
     const hasExtensions = this.ext.size() > 0;
@@ -314,12 +346,4 @@ export class Model<RootJsonNode extends JsonNode = JsonNode> implements Printabl
       ])
     );
   }
-
-  /**
-   * Serialize this model using "binary" structural encoding.
-   * @returns This model encoded in octets.
-   */
-  public toBinary(): Uint8Array {
-    return encoder.encode(this);
-  }
 }