From aa5ab871a5157dd70d55768843aeeab521258a49 Mon Sep 17 00:00:00 2001
From: Ali Mihandoost <ali.mihandoost@gmail.com>
Date: Wed, 3 Jul 2024 22:29:13 +0330
Subject: [PATCH] feat: Add saveImmediate method to CollectionReference and
 DocumentReference

The code changes add a new method called `saveImmediate` to both the `CollectionReference` and `DocumentReference` classes. This method allows the Alwatr Store to save the collection or document immediately, bypassing any debounce delay. The purpose of this change is to provide a way to save the data without any delay when immediate saving is required.
---
 .../reference/src/collection-reference.ts     | 33 +++++++++++++++----
 packages/reference/src/document-reference.ts  | 33 +++++++++++++++----
 2 files changed, 54 insertions(+), 12 deletions(-)

diff --git a/packages/reference/src/collection-reference.ts b/packages/reference/src/collection-reference.ts
index 30cf80f5..eccb83a1 100644
--- a/packages/reference/src/collection-reference.ts
+++ b/packages/reference/src/collection-reference.ts
@@ -419,16 +419,27 @@ export class CollectionReference<TItem extends JsonifiableObject = JsonifiableOb
    * Requests the Alwatr Store to save the collection.
    * Saving may take some time in Alwatr Store due to the use of throttling.
    *
-   * @param withDebounce Indicates whether to use the Alwatr Store's debounce delay.
+   * @example
+   * ```typescript
+   * collectionRef.save();
+   * ```
+   */
+  save(): void {
+    this.logger__.logMethod?.('save');
+    this.updated__(null, false);
+  }
+
+  /**
+   * Requests the Alwatr Store to save the collection immediately.
    *
    * @example
    * ```typescript
-   * collectionRef.save('item1');
+   * collectionRef.saveImmediate();
    * ```
    */
-  save(withDebounce = false): void {
-    this.logger__.logMethodArgs?.('save', withDebounce);
-    this.updated__(null, !withDebounce);
+  saveImmediate(): void {
+    this.logger__.logMethod?.('saveImmediate');
+    this.updated__(null, true);
   }
 
   /**
@@ -500,6 +511,16 @@ export class CollectionReference<TItem extends JsonifiableObject = JsonifiableOb
     }
   }
 
+  /**
+   * Retrieves the full context of the collection.
+   *
+   * @returns The full context of the collection.
+   *
+   * @example
+   * ```typescript
+   * const context = collectionRef.getFullContext_();
+   * ```
+   */
   getFullContext_(): Readonly<CollectionContext<TItem>> {
     this.logger__.logMethod?.('getFullContext_');
     return this.context__;
@@ -514,7 +535,7 @@ export class CollectionReference<TItem extends JsonifiableObject = JsonifiableOb
    * @param id - The ID of the item to update.
    */
   private async updated__(id: string | number | null, immediate = false): Promise<void> {
-    this.logger__.logMethodArgs?.('updated__', {delayed: this.updateDelayed_});
+    this.logger__.logMethodArgs?.('updated__', {id, immediate, delayed: this.updateDelayed_});
 
     this.hasUnprocessedChanges_ = true;
     if (id !== null) this.updateMeta_(id); // meta must updated per item
diff --git a/packages/reference/src/document-reference.ts b/packages/reference/src/document-reference.ts
index 20f42f81..44c09d21 100644
--- a/packages/reference/src/document-reference.ts
+++ b/packages/reference/src/document-reference.ts
@@ -268,18 +268,39 @@ export class DocumentReference<TDoc extends JsonifiableObject = JsonifiableObjec
    * Requests the Alwatr Store to save the document.
    * Saving may take some time in Alwatr Store due to the use of throttling.
    *
-   * @param withDebounce Indicates whether to use the Alwatr Store's debounce delay.
-   *
    * @example
    * ```typescript
    * documentRef.save();
    * ```
    */
-  save(withDebounce = false): void {
-    this.logger__.logMethodArgs?.('save', withDebounce);
-    this.updated__(!withDebounce);
+  save(): void {
+    this.logger__.logMethod?.('save');
+    this.updated__(false);
+  }
+
+  /**
+   * Requests the Alwatr Store to save the document immediately.
+   *
+   * @example
+   * ```typescript
+   * documentRef.saveImmediate();
+   * ```
+   */
+  saveImmediate(): void {
+    this.logger__.logMethod?.('saveImmediate');
+    this.updated__(true);
   }
 
+  /**
+   * Retrieves the full context of the document.
+   *
+   * @returns The full context of the document.
+   *
+   * @example
+   * ```typescript
+   * const context = documentRef.getFullContext_();
+   * ```
+   */
   getFullContext_(): Readonly<DocumentContext<TDoc>> {
     this.logger__.logMethod?.('getFullContext_');
     return this.context__;
@@ -292,7 +313,7 @@ export class DocumentReference<TDoc extends JsonifiableObject = JsonifiableObjec
    * This method is throttled to prevent multiple updates in a short time.
    */
   private async updated__(immediate = false): Promise<void> {
-    this.logger__.logMethodArgs?.('updated__', {delayed: this.updateDelayed_});
+    this.logger__.logMethodArgs?.('updated__', {immediate, delayed: this.updateDelayed_});
 
     this.hasUnprocessedChanges_ = true;