feat(json-crdt): 🎸 store Log metadata in file

Author: streamich

src/json-crdt/log/Log.ts

@@ -34,7 +34,7 @@ import type {JsonNode} from '../nodes/types';
  *
  * @todo Make this implement UILifecycle (start, stop) interface.
  */
-export class Log<N extends JsonNode = JsonNode<any>> implements Printable {
+export class Log<N extends JsonNode = JsonNode<any>, Metadata extends Record<string, unknown> = Record<string, unknown>> implements Printable {
   /**
    * Creates a `PatchLog` instance from a newly JSON CRDT model. Checks if
    * the model API buffer has any initial operations applied, if yes, it
@@ -60,6 +60,13 @@ export class Log<N extends JsonNode = JsonNode<any>> implements Printable {
     return new Log<N>(beginning, model);
   }
 
+  /**
+   * Custom metadata associated with the log, it will be stored in the log's
+   * header when serialized with {@link LogEncoder} and can be used to store
+   * additional information about the log.
+   */
+  public metadata: Metadata;
+
   /**
    * The collection of patches which are applied to the `start()` model to reach
    * the `end` model. The patches in the log, stored in an AVL tree for
@@ -94,6 +101,8 @@ export class Log<N extends JsonNode = JsonNode<any>> implements Printable {
      * @readonly
      */
     public readonly end: Model<N> = start(),
+
+    metadata?: Metadata
   ) {
     const onPatch = (patch: Patch) => {
       const id = patch.getId();
@@ -103,6 +112,7 @@ export class Log<N extends JsonNode = JsonNode<any>> implements Printable {
     const api = end.api;
     this.__onPatch = api.onPatch.listen(onPatch);
     this.__onFlush = api.onFlush.listen(onPatch);
+    this.metadata = metadata ?? {} as Metadata;
   }
 
   /**

src/json-crdt/log/codec/LogDecoder.ts

@@ -70,7 +70,7 @@ export class LogDecoder {
   }
 
   public deserialize(components: types.LogComponentsWithFrontier, params: DeserializeParams = {}): DecodeResult {
-    const [view, metadata, model, , ...frontier] = components;
+    const [view, header, model, , ...frontier] = components;
     const result: DecodeResult = {};
     if (params.view) result.view = view;
     if (params.history) result.history = this.deserializeHistory(components);
@@ -79,7 +79,7 @@ export class LogDecoder {
       if (result.history) {
         result.frontier = result.history;
       } else if (model) {
-        const modelFormat = metadata[1];
+        const modelFormat = header[1];
         const start = (): Model => {
           const isSidecar = modelFormat === FileModelEncoding.SidecarBinary;
           if (isSidecar) {
@@ -102,7 +102,7 @@ export class LogDecoder {
   }
 
   public deserializeHistory(components: types.LogComponentsWithFrontier): Log {
-    const [, , , history, ...frontier] = components;
+    const [, header, , history, ...frontier] = components;
     const [startSerialized] = history;
     const start = (): Model => {
       if (!history || !startSerialized) {
@@ -112,7 +112,7 @@ export class LogDecoder {
       }
       return this.deserializeModel(startSerialized);
     };
-    const log = new Log(start);
+    const log = new Log(start, void 0, header[0]);
     const end = log.end;
     if (history) {
       const [, patches] = history;

src/json-crdt/log/codec/LogEncoder.ts

@@ -24,12 +24,12 @@ export class LogEncoder {
 
   public serialize(log: Log, params: SerializeParams = {}): types.LogComponents {
     if (params.noView && params.model === 'sidecar') throw new Error('SIDECAR_MODEL_WITHOUT_VIEW');
-    const metadata: types.LogHeader = [{}, FileModelEncoding.Auto];
+    const header: types.LogHeader = [log.metadata ?? {}, FileModelEncoding.Auto];
     let model: Uint8Array | unknown | null = null;
     const modelFormat = params.model ?? 'sidecar';
     switch (modelFormat) {
       case 'sidecar': {
-        metadata[1] = FileModelEncoding.SidecarBinary;
+        header[1] = FileModelEncoding.SidecarBinary;
         const encoder = this.options.sidecarEncoder;
         if (!encoder) throw new Error('NO_SIDECAR_ENCODER');
         const [, uint8] = encoder.encode(log.end);
@@ -102,7 +102,7 @@ export class LogEncoder {
       default:
         throw new Error(`Invalid history format: ${patchFormat}`);
     }
-    return [params.noView ? null : log.end.view(), metadata, model, history];
+    return [params.noView ? null : log.end.view(), header, model, history];
   }
 
   public encode(log: Log, params: EncodingParams): Uint8Array {

src/json-crdt/log/codec/__tests__/LogDecoder.spec.ts

@@ -36,6 +36,20 @@ describe('can decode from blob', () => {
     expect(history!.start().view()).toEqual(undefined);
     expect(history!.end.view()).toEqual({foo: 'bar'});
   });
+
+  test('can store custom metadata keys', () => {
+    const {log, encoder, decoder} = setup({foo: 'bar'});
+    const metadata = {
+      baz: 'qux',
+      time: 123,
+      active: true,
+    };
+    log.metadata = {...metadata};
+    const blob = encoder.encode(log, {format: 'seq.cbor'});
+    const decoded1 = decoder.decode(blob, {format: 'seq.cbor', frontier: true, history: true});
+    expect(decoded1.frontier?.metadata).toEqual(metadata);
+    expect(decoded1.history?.metadata).toEqual(metadata);
+  });
 });
 
 const assertEncoding = (log: Log, params: EncodingParams) => {

src/json-crdt/log/codec/types.ts

@@ -1,13 +1,13 @@
 import type {FileModelEncoding} from './constants';
 
-export type LogHeader<LogMetadata extends Record<string, unknown> = Record<string, unknown>> = [
-  map: LogMetadata,
+export type LogHeader<metadata extends Record<string, unknown> = Record<string, unknown>> = [
+  metadata: metadata,
   modelFormat: FileModelEncoding,
 ];
 
-export type LogComponents<LogMetadata extends Record<string, unknown> = Record<string, unknown>> = [
+export type LogComponents<Metadata extends Record<string, unknown> = Record<string, unknown>> = [
   view: unknown | null,
-  header: LogHeader<LogMetadata>,
+  header: LogHeader<Metadata>,
   model: Uint8Array | unknown | null,
   history: LogHistory,
 ];