[persisters] YjsPersister

Author: jamesgpearce

src/persisters/persister-yjs.ts

@@ -7,12 +7,16 @@ import {
   Values,
 } from '../types/store.d';
 import {IdObj, objEnsure, objHas, objMap, objNew} from '../common/obj';
-import {Persister, PersisterListener} from '../types/persisters.d';
 import {T, TINYBASE, V} from '../common/strings';
 import {Doc as YDoc, YEvent, Map as YMap} from 'yjs';
+import {
+  YjsPersister,
+  createYjsPersister as createYjsPersisterDecl,
+} from '../types/persisters/persister-yjs';
 import {arrayForEach, arrayIsEmpty, arrayShift} from '../common/array';
 import {ifNotUndefined, isUndefined, size} from '../common/other';
 import {Id} from '../types/common.d';
+import {PersisterListener} from '../types/persisters.d';
 import {createCustomPersister} from '../persisters';
 import {mapForEach} from '../common/map';
 
@@ -174,12 +178,12 @@ const yMapMatch = (
   return changed;
 };
 
-export const createYjsPersister = (
+export const createYjsPersister = ((
   store: Store,
   yDoc: YDoc,
   yMapName = TINYBASE,
   onIgnoredError?: (error: any) => void,
-): Persister => {
+): YjsPersister => {
   const yContent: YMap<any> = yDoc.getMap(yMapName);
 
   const getPersisted = async (): Promise<[Tables, Values] | undefined> =>
@@ -219,5 +223,5 @@ export const createYjsPersister = (
     delPersisterListener,
     onIgnoredError,
     ['getYDoc', yDoc],
-  );
-};
+  ) as YjsPersister;
+}) as typeof createYjsPersisterDecl;

src/types/docs/persisters/persister-yjs.js

@@ -11,6 +11,38 @@
  * @since v4.0.0
  */
 /// persister-yjs
+/**
+ * The YjsPersister interface is a minor extension to the Persister interface.
+ *
+ * It simply provides an extra getYDoc method for accessing the Yjs document the
+ * Store is being persisted to.
+ * @since v4.3.14
+ */
+/// YjsPersister
+{
+  /**
+   * The getYDoc method returns the Yjs document the Store is being persisted
+   * to.
+   * @returns The Yjs document.
+   * @example
+   * This example creates a Persister object against a newly-created Store and
+   * then gets the Yjs document back out again.
+   *
+   * ```js
+   * const doc = new Y.Doc();
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * const persister = createYjsPersister(store, doc);
+   *
+   * console.log(persister.getYDoc() == doc);
+   * // -> true
+   *
+   * persister.destroy();
+   * ```
+   * @category Getter
+   * @since v4.3.14
+   */
+  /// YjsPersister.getYDoc
+}
 /**
  * The createYjsPersister function creates a Persister object that can persist
  * the Store to a Yjs document.
@@ -24,9 +56,9 @@
  * @param onIgnoredError An optional handler for the errors that the Persister
  * would otherwise ignore when trying to save or load data. This is suitable for
  * debugging persistence issues in a development environment, since v4.0.4.
- * @returns A reference to the new Persister object.
+ * @returns A reference to the new YjsPersister object.
  * @example
- * This example creates a Persister object and persists the Store to a Yjs
+ * This example creates a YjsPersister object and persists the Store to a Yjs
  * document.
  *
  * ```js
@@ -44,8 +76,8 @@
  * ```
  * @example
  * This more complex example uses Yjs updates to keep two Store objects (each
- * with their own Persister objects and Yjs documents) in sync with each other.
- * We use the `await` keyword extensively for the purpose of ensuring
+ * with their own YjsPersister objects and Yjs documents) in sync with each
+ * other. We use the `await` keyword extensively for the purpose of ensuring
  * sequentiality in this example.
  *
  * Typically, real-world synchronization would happen between two systems via a

src/types/persisters/persister-yjs.d.ts

@@ -4,10 +4,16 @@ import {Persister} from '../persisters.d';
 import {Store} from '../store.d';
 import {Doc as YDoc} from 'yjs';
 
+/// YjsPersister
+export interface YjsPersister extends Persister {
+  /// YjsPersister.getYDoc
+  getYDoc: () => YDoc;
+}
+
 /// createYjsPersister
 export function createYjsPersister(
   store: Store,
   yDoc: YDoc,
   yMapName?: string,
   onIgnoredError?: (error: any) => void,
-): Persister;
+): YjsPersister;

src/types/with-schemas/persisters/persister-yjs.d.ts

@@ -4,10 +4,17 @@ import {OptionalSchemas, Store} from '../store.d';
 import {Persister} from '../persisters.d';
 import {Doc as YDoc} from 'yjs';
 
+/// YjsPersister
+export interface YjsPersister<Schemas extends OptionalSchemas>
+  extends Persister<Schemas> {
+  /// YjsPersister.getYDoc
+  getYDoc: () => YDoc;
+}
+
 /// createYjsPersister
 export function createYjsPersister<Schemas extends OptionalSchemas>(
   store: Store<Schemas>,
   yDoc: YDoc,
   yMapName?: string,
   onIgnoredError?: (error: any) => void,
-): Persister<Schemas>;
+): YjsPersister<Schemas>;