Support for Referenced Properties

Description

Fireorm currently does not support creating entities with referenced properties directly. Users need a way to reference other collections when creating new documents, such as referencing a Produtor from within a ProdutorDadosAdicionais entity.

Steps to Reproduce

Create a Produtor class and a ProdutorDadosAdicionais class, with ProdutorDadosAdicionais having a property referencing Produtor.
Attempt to create a new ProdutorDadosAdicionais document with a reference to an existing Produtor document.

Expected Behavior

Ability to create documents with referenced properties that correctly store document references in Firestore.

Actual Behavior

Currently, there is no straightforward way to set referenced properties, leading to workarounds or potential bugs with deserialization/serialization of Firestore entities.

Acceptance Criteria

Implement support for creating documents with referenced properties, allowing users to set references directly.
Ensure compatibility with TypeScript for proper type checking and autocomplete.
Avoid forcing the use of subcollections where document references are more appropriate.
Develop a method to validate reference paths.
Consider adding a getRef/getPath function to entities for easy access to document paths.

Additional Context

November 12, 2019: Initial inquiry about setting referenced properties.
November 14, 2019: Discussion on potential solutions and workarounds, such as using produtorId and produtorNome properties.
February 18, 2021: Request to re-open the issue to further explore a cleaner API for document references.
February 22, 2021: Discussion about a proposed API using Reference<T> type and @DocumentReference() decorator.
February 28, 2021: Initial work on supporting references, with ongoing discussion about the API design.

Original

Additional Context

November 12, 2019: Initial inquiry about setting referenced properties.
November 14, 2019: Discussion on potential solutions and workarounds, such as using produtorId and produtorNome properties.
February 18, 2021: Request to re-open the issue to further explore a cleaner API for document references.
February 22, 2021: Discussion about a proposed API using Reference
type and @DocumentReference() decorator.
- Suggested API:
```
@Collection()
class Band {
id: string;
@DocumentReference()
artist: Reference<Artist>;
}
```
- Allowing the artist property to be assigned either a string (reference path) or an object, with Fireorm handling the creation and reference setting.
- Handling cases where the referenced document does not exist, with options such as throwing an error, creating the reference within a transaction, or using a helper function like setReference.
- February 28, 2021: Initial work on supporting references, with ongoing discussion about the API design.
- Challenges identified:
  - Ensuring type safety and autocompletion in TypeScript.
  - Validating reference paths.
  - Allowing easy access to document paths within entities.
- March 1-2, 2021: Further API refinement and discussion on possible implementations.
- Example API for creating a document with a reference:
```
// Creating a reference with a string
getRepository(Band).create({
id: 'fireorm rocks!',
artist: '/artists/wovalle'
});
```

// Creating a reference with an object const artist = new Artist(); artist.id = 'new-artist'; artist.name = 'New Artist';

getRepository(Band).create({ id: 'fireorm rocks!', artist: setReference(artist), });

### Proposed API Changes

1. Reference Type and Decorator:

 - Introduce a generic Reference<T> type to handle document references.
 - Use @DocumentReference() decorator to mark properties as references.
```typescript
@Collection()
class Band {
  id: string;
  @DocumentReference()
  artist: Reference<Artist>;
}

Handling Reference Creation:
- Allow properties to be set either as a reference path (string) or as an object.
- Validate reference paths to ensure they are well-formed.
- Provide mechanisms to handle cases where the referenced document does not exist, such as:
- Throwing an error.
- Automatically creating the referenced document within a transaction.
- Using a helper function (setReference) to manage reference creation.
```
// Example with reference path as string
getRepository(Band).create({
id: 'fireorm rocks!',
artist: '/artists/wovalle'
});
```

// Example with reference object const artist = new Artist(); artist.id = 'new-artist'; artist.name = 'New Artist';

getRepository(Band).create({ id: 'fireorm rocks!', artist: setReference(artist), });


3. Adding Path Information to Entities:

 - Introduce a getPath method to entities for easy access to their document paths.
 - Ensure that the path is stored and accessible within the entity's instance.

4. Reference Validation:

 - Implement validation logic for reference paths based on Firebase's guidelines, ensuring paths are non-empty strings without double slashes.

5. TypeScript Compatibility:

 - Ensure the proposed changes are compatible with TypeScript's type checking and autocomplete features.
 - Use a generic approach to allow properties to be of type T or string while maintaining type safety.

elersong / fireorm24