@abraca/dabra 1.8.0 → 1.8.2

package/dist/index.d.ts

@@ -826,6 +826,13 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
    * the offline store is disabled or when no snapshot has been saved yet.
    */
   readonly ready: Promise<void>;
+  /**
+   * True once `_initFromOfflineStore()` has applied a non-empty snapshot or
+   * at least one pending update to the Y.Doc. Lets the UI decide to render
+   * cached content immediately instead of waiting for a server round-trip.
+   * Only meaningful after `await ready`.
+   */
+  hasCachedContent: boolean;
   constructor(configuration: AbracadabraProviderConfiguration);
   /**
    * Extract the server hostname from the provider configuration.
@@ -1157,6 +1164,7 @@ type onServerErrorParameters = {
   source: string;
   code: string;
   message: string;
+  meta?: Record<string, unknown>;
 };
 type StatesArray = {
   clientId: number;
@@ -1446,7 +1454,14 @@ interface CompleteAbracadabraWSConfiguration {
    */
   WebSocketPolyfill: any;
   /**
-   * Disconnect when no message is received for the defined amount of milliseconds.
+   * Disconnect and reconnect when no message is received for the defined amount
+   * of milliseconds.
+   *
+   * Defaults to 30000 ms to match y-protocols/awareness `Awareness.outdatedTime`
+   * (also 30 s). Awareness heartbeats are what normally keep this timer
+   * resetting, so this value should be ≥ the largest `outdatedTime` of any
+   * awareness instance attached to this socket. If you pass a custom awareness
+   * with a non-default `outdatedTime`, pass the matching value here too.
    */
   messageReconnectTimeout: number;
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

package/src/AbracadabraBaseProvider.ts

@@ -375,9 +375,9 @@ export class AbracadabraBaseProvider extends EventEmitter {
     try {
       const parsed = JSON.parse(payload);
       if (parsed?.type === "error" && parsed.source && parsed.code) {
-        const { source, code, message } = parsed;
-        console.warn(`[Abracadabra] Server error: ${source} (${code}) — ${message}`);
-        this.emit("serverError", { source, code, message: message ?? "" });
+        const { source, code, message, meta } = parsed;
+        console.warn(`[Abracadabra] Server error: ${source} (${code}) — ${message}`, meta ?? "");
+        this.emit("serverError", { source, code, message: message ?? "", meta });
         return;
       }
     } catch {

package/src/AbracadabraProvider.ts

@@ -129,6 +129,14 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 	 */
 	public readonly ready: Promise<void>;
 
+	/**
+	 * True once `_initFromOfflineStore()` has applied a non-empty snapshot or
+	 * at least one pending update to the Y.Doc. Lets the UI decide to render
+	 * cached content immediately instead of waiting for a server round-trip.
+	 * Only meaningful after `await ready`.
+	 */
+	public hasCachedContent = false;
+
 	constructor(configuration: AbracadabraProviderConfiguration) {
 		// Derive URL and token from client when not explicitly set.
 		const resolved = { ...configuration } as AbracadabraBaseProviderConfiguration;
@@ -225,9 +233,11 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 
 		if (snapshot) {
 			Y.applyUpdate(this.document, snapshot, this.offlineStore);
+			this.hasCachedContent = true;
 		}
 		for (const update of pending) {
 			Y.applyUpdate(this.document, update, this.offlineStore);
+			this.hasCachedContent = true;
 		}
 	}
 

package/src/AbracadabraWS.ts

@@ -55,7 +55,14 @@ export interface CompleteAbracadabraWSConfiguration {
   WebSocketPolyfill: any;
 
   /**
-   * Disconnect when no message is received for the defined amount of milliseconds.
+   * Disconnect and reconnect when no message is received for the defined amount
+   * of milliseconds.
+   *
+   * Defaults to 30000 ms to match y-protocols/awareness `Awareness.outdatedTime`
+   * (also 30 s). Awareness heartbeats are what normally keep this timer
+   * resetting, so this value should be ≥ the largest `outdatedTime` of any
+   * awareness instance attached to this socket. If you pass a custom awareness
+   * with a non-default `outdatedTime`, pass the matching value here too.
    */
   messageReconnectTimeout: number;
   /**
@@ -121,7 +128,8 @@ export class AbracadabraWS extends EventEmitter {
     // @ts-ignore
     document: undefined,
     WebSocketPolyfill: undefined,
-    // TODO: this should depend on awareness.outdatedTime
+    // Matches y-protocols/awareness Awareness.outdatedTime default (30 s).
+    // See the `messageReconnectTimeout` JSDoc on CompleteAbracadabraWSConfiguration.
     messageReconnectTimeout: 30000,
     // 1 second
     delay: 1000,

package/src/types.ts

@@ -128,6 +128,7 @@ export type onServerErrorParameters = {
   source: string;
   code: string;
   message: string;
+  meta?: Record<string, unknown>;
 };
 
 export type StatesArray = { clientId: number; [key: string | number]: any }[];