From b42b8b5935b96eb5a36d646f3b3fc4d2b2ada038 Mon Sep 17 00:00:00 2001 From: tylim Date: Mon, 31 Jul 2023 18:37:24 +0800 Subject: [PATCH] improve collection and collectionGroup JSDoc --- codeForDoc/src/quick_start/query.ts | 7 ++++- package.json | 2 +- src/types/firelord.ts | 12 +++------ src/types/refs/collection.ts | 42 ++++++++++++++++------------- src/types/refs/collectionGroup.ts | 13 +++++---- 5 files changed, 41 insertions(+), 35 deletions(-) diff --git a/codeForDoc/src/quick_start/query.ts b/codeForDoc/src/quick_start/query.ts index 55d7dc93..791f76bb 100644 --- a/codeForDoc/src/quick_start/query.ts +++ b/codeForDoc/src/quick_start/query.ts @@ -4,7 +4,7 @@ import { getDocs, query, where, orderBy, limit } from 'firelordjs' // filter documents getDocs( query( - example.collection(), + example.collection(), // or example.collectionGroup() where('f.h', '>', 1010), orderBy('f.h'), limit(10) @@ -25,3 +25,8 @@ getDocs( // similar to docSnapshot of getDoc }) }) + +// get all collection documents +getDocs( + example.collection() // or example.collectionGroup() +) diff --git a/package.json b/package.json index d7b755ce..1215093b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "firelordjs", - "version": "2.6.4", + "version": "2.6.5", "description": "🔥 High Precision Typescript Wrapper for Firestore Web, Providing Unparalleled Type Safe and Dev Experience", "main": "dist/index.js", "types": "dist/index.d.ts", diff --git a/src/types/firelord.ts b/src/types/firelord.ts index 4a81c96c..201fe74d 100644 --- a/src/types/firelord.ts +++ b/src/types/firelord.ts @@ -16,19 +16,15 @@ type Doc_ = { } type Collection_ = { - /** - * Gets a `CollectionReference` instance that refers to the collection at - * the specified absolute path. - * - * @param documentIds - all the docID(s) needed to build this collection path. - * @returns The `CollectionReference` instance. - */ collection: Collection } type CollectionGroup_ = { /** - * @returns — The created Query. + * related documentations: + * - {@link https://firelordjs.com/quick_start/#query query} + * - {@link https://firelordjs.com/quick_start/#onsnapshot onSnapshot} + * @returns — The created {@link Query}. */ collectionGroup: () => Query } diff --git a/src/types/refs/collection.ts b/src/types/refs/collection.ts index 858dd19b..5d1096be 100644 --- a/src/types/refs/collection.ts +++ b/src/types/refs/collection.ts @@ -6,8 +6,8 @@ import { DocumentReference } from './doc' import { Query } from './query' /** - * A `CollectionReference` object can be used for adding documents, getting - * document references, and querying for documents (using {@link query}). + * A {@link CollectionReference} object can be used for adding documents, getting + * {@link DocumentReference}, and querying for documents (using {@link Query}). */ export interface CollectionReference extends Query { /** The type of this Firestore reference. */ @@ -20,32 +20,38 @@ export interface CollectionReference extends Query { */ get path(): T['collectionPath'] /** - * A reference to the containing `DocumentReference` if this is a - * subcollection. If this isn't a subcollection, the reference is null. + * A reference to the containing parent {@link DocumentReference} if this is a + * sub-collection. If this isn't a sub-collection, the reference is null. */ get parent(): T['parent'] extends MetaType ? DocumentReference : null } -export type CollectionCreator = +export type CollectionCreator = ( + fStore: Firestore, + ...collectionIDs: GetOddOrEvenSegments +) => Collection + +export type Collection = { /** - * Gets a `CollectionReference` instance that refers to the collection at + * Gets a {@link CollectionReference} instance that refers to the collection at * the specified absolute path. * - * @param documentIds - all the docID(s) needed to build this collection path. - * @returns The `CollectionReference` instance. + * related documentations: + * - {@link https://firelordjs.com/guides/metatype child meta type} + * - {@link https://firelordjs.com/quick_start#operations operation} + * @param documentIds + * All the docID(s) needed to build this document path, eg + * - for top-collection: example.collection() + * - for sub-collection: example.collection(GrandParentDocId, ParentsDocId) + * + * @returns The {@link CollectionReference} instance. */ - ( - fStore: Firestore, - ...collectionIDs: GetOddOrEvenSegments - ) => Collection - -export type Collection = < - D extends GetOddOrEvenSegments ->( - ...documentIDs: D extends never ? D : IsValidDocIDLoop -) => CollectionReference + >( + ...documentIDs: D extends never ? D : IsValidDocIDLoop + ): CollectionReference +} export type GetCollectionIds = GetOddOrEvenSegments< T['collectionPath'], diff --git a/src/types/refs/collectionGroup.ts b/src/types/refs/collectionGroup.ts index 793a1867..d9ba3065 100644 --- a/src/types/refs/collectionGroup.ts +++ b/src/types/refs/collectionGroup.ts @@ -3,10 +3,10 @@ import { Firestore } from '../alias' import { Query } from './query' /** - * A `CollectionGroup` refers to all documents that are contained in a - * collection or subcollection with a specific collection ID. + * A {@link CollectionGroup} refers to all documents that are contained in a + * collection or sub-collection with a specific collection ID. */ -export interface CollectionGroupReference extends Query { +export interface CollectionGroup extends Query { /** The type of this Firestore reference. */ readonly type: 'query' } @@ -14,7 +14,6 @@ export interface CollectionGroupReference extends Query { export type CollectionGroupCreator = ( fStore: Firestore, collectionID: T['collectionID'] -) => /** - * @returns — The created Query. - */ -() => CollectionGroupReference +) => { + (): CollectionGroup +}