Expose Timestamps from DocumentSnapshot

[elersong]

Description

Firestore's DocumentSnapshot exposes timestamps such as createTime, readTime, and updateTime. It would be beneficial to expose these timestamps in Fireorm entities, allowing users to access metadata about document operations.

Steps to Reproduce

1. Retrieve a document using Fireorm.
2. Attempt to access timestamps like createTime, readTime, and updateTime.

Expected Behavior

Ability to access createTime, readTime, and updateTime directly from Fireorm entities.

Actual Behavior

Currently, these timestamps are not exposed in Fireorm entities.

Acceptance Criteria

• Implement a mechanism to expose createTime, readTime, and updateTime in Fireorm entities.
• Ensure the implementation is clean and does not require adding arbitrary fields to entities unless needed.

Additional Context

• May 3, 2020: Initial issue raised to expose timestamps from DocumentSnapshot.
• May 10, 2020: Discussion on the best approach to implement this feature, considering the use of decorators or Symbols for a clean implementation.

Proposed API Changes

1. Use of Decorators:

   • Introduce decorators to map entity fields to autogenerated or readonly fields in Firestore.
   • Example:

     @Collection()
     class MyEntity {
       id: string;
       
       @CreatedOnField()
       createTime: FirebaseFirestore.Timestamp;
       
       @ReadOnField()
       readTime: FirebaseFirestore.Timestamp;
       
       @UpdatedOnField()
       updateTime: FirebaseFirestore.Timestamp;
     }

2. Use of Symbols:

   • Expose Symbols that developers can use to override entity fields for metadata fields.
   • Example:

     import { Symbols } from 'fireorm';
     
     @Collection()
     class MyEntity {
       id: string;
       
       [Symbols.createTime]: FirebaseFirestore.Timestamp;
       [Symbols.readTime]: FirebaseFirestore.Timestamp;
       [Symbols.updateTime]: FirebaseFirestore.Timestamp;
     }

3. Testing and Validation:

   • Ensure thorough testing to validate that the timestamps are correctly mapped and accessible.
   • Verify that the implementation does not interfere with existing functionalities and remains backward compatible.

Original Issue