Implement Listening on Snapshot Events

[elersong]

Description

Fireorm lacks support for listening to snapshot events. A proof-of-concept was created to demonstrate the feasibility of this feature, which allows real-time updates by listening to Firestore snapshot events. This feature needs to be refined and integrated into Fireorm with proper abstractions and unit tests.

Steps to Reproduce

1. Attempt to implement real-time updates by listening to Firestore snapshot events in Fireorm.
2. Notice the lack of built-in support for this functionality.

Expected Behavior

Ability to listen to Firestore snapshot events and handle real-time updates within Fireorm, using a consistent API that fits with the rest of the project.

Actual Behavior

Currently, Fireorm does not support listening to snapshot events, requiring manual implementation.

Acceptance Criteria

• Implement listening on snapshot events with proper type abstractions.
• Replace any usage of any with proper TypeScript types.
• Create unit tests to ensure the functionality works as expected.
• Return a custom object with parsed entities and relevant information from the snapshot, instead of the raw QuerySnapshot.

Additional Context

• November 22, 2020: Initial proof-of-concept for listening to snapshot events.
• November 23, 2020: Suggestions for improvements, including adding unit tests and proper TypeScript types.
• November 25, 2020: Discussion about abstracting QuerySnapshot and providing a custom object to users.
• November 30, 2020: Updates to use generics for QuerySnapshot.
• December 7, 2020: Further updates and preparation for a pull request to the main repository.

Proposed API Changes

1. Implement Snapshot Listener:

   • Add a method to listen to Firestore snapshot events and handle real-time updates.

   // Example implementation of listening to snapshot events
   async listenToSnapshots(callback: (data: CustomSnapshot<T>) => void): Promise<() => void> {
     const unsubscribe = this.firestoreCollection.onSnapshot(snapshot => {
       const data = this.extractDataFromSnapshot(snapshot);
       callback(data);
     });
     return unsubscribe;
   }

2. Custom Snapshot Object:

   • Return a custom object with parsed entities and relevant information from the snapshot, instead of the raw QuerySnapshot.

   // Define a custom snapshot type
   type CustomSnapshot<T> = {
     docs: T[];
     // Add other relevant information if needed
   };
   
   // Example of extracting data from a snapshot
   private extractDataFromSnapshot(snapshot: QuerySnapshot): CustomSnapshot<T> {
     const docs = snapshot.docs.map(doc => this.extractTFromDocSnap(doc));
     return { docs };
   }

3. Unit Tests:

   • Create unit tests to validate the functionality of the snapshot listener.

   // Example unit test
   test('should listen to snapshot events and handle updates', async () => {
     const callback = jest.fn();
     const unsubscribe = await repo.listenToSnapshots(callback);
     
     // Simulate a snapshot event
     const snapshot = { /* mock data */ };
     callback(snapshot);
     
     expect(callback).toHaveBeenCalledWith(snapshot);
     
     unsubscribe();
   });

Example Implementation

@Collection()
class User {
  id: string;
  display_name: string;
  username: string;
}

// Repository instance
const repo = getRepository(User);

// Listen to snapshot events
const unsubscribe = await repo.listenToSnapshots(data => {
  console.log('Received snapshot:', data);
});

// Later, unsubscribe from snapshot events
unsubscribe();

Original Issue

[elersong]

I'm not certain live updates listening really fits within the scope of an object-relational mapper. This will need some more thought.