react-query-firebase 2.3.2 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. package/package.json +1 -1
  2. package/react-native/firestore/index.d.ts +5 -0
  3. package/react-native/firestore/index.js +5 -0
  4. package/react-native/firestore/index.ts +5 -0
  5. package/react-native/firestore/useAddDocMutation.d.ts +38 -9
  6. package/react-native/firestore/useAddDocMutation.js +25 -11
  7. package/react-native/firestore/useAddDocMutation.ts +43 -13
  8. package/react-native/firestore/useBatchWrite.d.ts +31 -7
  9. package/react-native/firestore/useBatchWrite.js +22 -4
  10. package/react-native/firestore/useBatchWrite.ts +31 -7
  11. package/react-native/firestore/useCollectionReference.d.ts +30 -9
  12. package/react-native/firestore/useCollectionReference.js +15 -7
  13. package/react-native/firestore/useCollectionReference.ts +34 -25
  14. package/react-native/firestore/useCompositeFilter.d.ts +1 -46
  15. package/react-native/firestore/useCompositeFilter.js +2 -45
  16. package/react-native/firestore/useCompositeFilter.ts +2 -74
  17. package/react-native/firestore/useCountQuery.d.ts +1 -1
  18. package/react-native/firestore/useCountQuery.ts +1 -1
  19. package/react-native/firestore/useDeleteDocMutation.d.ts +39 -10
  20. package/react-native/firestore/useDeleteDocMutation.js +22 -5
  21. package/react-native/firestore/useDeleteDocMutation.ts +38 -15
  22. package/react-native/firestore/useDocReference.d.ts +22 -14
  23. package/react-native/firestore/useDocReference.js +20 -26
  24. package/react-native/firestore/useDocReference.ts +34 -47
  25. package/react-native/firestore/useDocReferences.d.ts +23 -18
  26. package/react-native/firestore/useDocReferences.js +18 -19
  27. package/react-native/firestore/useDocReferences.ts +26 -34
  28. package/react-native/firestore/useFirestore.d.ts +4 -3
  29. package/react-native/firestore/useFirestore.js +4 -3
  30. package/react-native/firestore/useFirestore.ts +4 -3
  31. package/react-native/firestore/useGetDocData.d.ts +33 -14
  32. package/react-native/firestore/useGetDocData.js +21 -6
  33. package/react-native/firestore/useGetDocData.ts +34 -22
  34. package/react-native/firestore/useInfiniteQuery.d.ts +2 -2
  35. package/react-native/firestore/useInfiniteQuery.ts +3 -3
  36. package/react-native/firestore/useQuery.d.ts +1 -1
  37. package/react-native/firestore/useQuery.ts +1 -1
  38. package/react-native/firestore/useQueryConstraints.d.ts +2 -22
  39. package/react-native/firestore/useQueryConstraints.js +1 -39
  40. package/react-native/firestore/useQueryConstraints.ts +3 -43
  41. package/react-native/firestore/useRunTransaction.d.ts +33 -9
  42. package/react-native/firestore/useRunTransaction.js +20 -4
  43. package/react-native/firestore/useRunTransaction.ts +35 -16
  44. package/react-native/firestore/useSetDocMutation.d.ts +43 -11
  45. package/react-native/firestore/useSetDocMutation.js +28 -11
  46. package/react-native/firestore/useSetDocMutation.ts +49 -28
  47. package/react-native/firestore/useUpdateDocMutation.d.ts +40 -18
  48. package/react-native/firestore/useUpdateDocMutation.js +18 -13
  49. package/react-native/firestore/useUpdateDocMutation.ts +40 -31
  50. package/react-native/firestore/utils/buildCompositeFilter.d.ts +47 -0
  51. package/react-native/firestore/utils/buildCompositeFilter.js +45 -0
  52. package/react-native/firestore/utils/buildCompositeFilter.ts +75 -0
  53. package/react-native/firestore/utils/buildQueryConstraint.d.ts +23 -0
  54. package/react-native/firestore/utils/buildQueryConstraint.js +41 -0
  55. package/react-native/firestore/utils/buildQueryConstraint.ts +54 -0
  56. package/react-native/firestore/utils/getDocData.d.ts +11 -11
  57. package/react-native/firestore/utils/getDocData.js +5 -8
  58. package/react-native/firestore/utils/getDocData.ts +12 -16
  59. package/react-native/firestore/utils/getDocRef.d.ts +12 -9
  60. package/react-native/firestore/utils/getDocRef.js +7 -8
  61. package/react-native/firestore/utils/getDocRef.ts +12 -13
  62. package/react-native/firestore/utils/getDocSnap.d.ts +11 -13
  63. package/react-native/firestore/utils/getDocSnap.js +5 -10
  64. package/react-native/firestore/utils/getDocSnap.ts +12 -17
  65. package/types/AppModel.d.ts +4 -1
  66. package/types/AppModel.ts +4 -1
  67. package/web/firestore/index.d.ts +5 -0
  68. package/web/firestore/index.js +5 -0
  69. package/web/firestore/index.ts +5 -0
  70. package/web/firestore/useAddDocMutation.d.ts +41 -13
  71. package/web/firestore/useAddDocMutation.js +27 -14
  72. package/web/firestore/useAddDocMutation.ts +49 -37
  73. package/web/firestore/useBatchWrite.d.ts +34 -7
  74. package/web/firestore/useBatchWrite.js +22 -4
  75. package/web/firestore/useBatchWrite.ts +34 -7
  76. package/web/firestore/useCollectionReference.d.ts +32 -11
  77. package/web/firestore/useCollectionReference.js +15 -7
  78. package/web/firestore/useCollectionReference.ts +34 -13
  79. package/web/firestore/useCompositeFilter.d.ts +2 -47
  80. package/web/firestore/useCompositeFilter.js +2 -42
  81. package/web/firestore/useCompositeFilter.ts +2 -72
  82. package/web/firestore/useCountQuery.d.ts +4 -4
  83. package/web/firestore/useCountQuery.ts +5 -5
  84. package/web/firestore/useDeleteDocMutation.d.ts +41 -11
  85. package/web/firestore/useDeleteDocMutation.js +24 -7
  86. package/web/firestore/useDeleteDocMutation.ts +45 -23
  87. package/web/firestore/useDocReference.d.ts +23 -15
  88. package/web/firestore/useDocReference.js +16 -31
  89. package/web/firestore/useDocReference.ts +28 -46
  90. package/web/firestore/useDocReferences.d.ts +23 -18
  91. package/web/firestore/useDocReferences.js +18 -21
  92. package/web/firestore/useDocReferences.ts +26 -30
  93. package/web/firestore/useFirestore.d.ts +4 -3
  94. package/web/firestore/useFirestore.js +4 -3
  95. package/web/firestore/useFirestore.ts +4 -3
  96. package/web/firestore/useGetDocData.d.ts +32 -13
  97. package/web/firestore/useGetDocData.js +21 -6
  98. package/web/firestore/useGetDocData.ts +34 -23
  99. package/web/firestore/useGetRealtimeDocData.js +2 -2
  100. package/web/firestore/useGetRealtimeDocData.ts +2 -2
  101. package/web/firestore/useInfiniteQuery.d.ts +2 -2
  102. package/web/firestore/useInfiniteQuery.js +1 -1
  103. package/web/firestore/useInfiniteQuery.ts +4 -4
  104. package/web/firestore/useQuery.d.ts +1 -1
  105. package/web/firestore/useQuery.js +1 -1
  106. package/web/firestore/useQuery.ts +2 -2
  107. package/web/firestore/useQueryConstraints.d.ts +0 -21
  108. package/web/firestore/useQueryConstraints.js +1 -39
  109. package/web/firestore/useQueryConstraints.ts +2 -51
  110. package/web/firestore/useRunTransaction.d.ts +33 -8
  111. package/web/firestore/useRunTransaction.js +20 -4
  112. package/web/firestore/useRunTransaction.ts +35 -10
  113. package/web/firestore/useSetDocMutation.d.ts +45 -12
  114. package/web/firestore/useSetDocMutation.js +28 -11
  115. package/web/firestore/useSetDocMutation.ts +51 -26
  116. package/web/firestore/useUpdateDocMutation.d.ts +42 -20
  117. package/web/firestore/useUpdateDocMutation.js +20 -15
  118. package/web/firestore/useUpdateDocMutation.ts +45 -41
  119. package/web/firestore/utils/buildCompositeFilter.d.ts +47 -0
  120. package/web/firestore/utils/buildCompositeFilter.js +42 -0
  121. package/web/firestore/utils/buildCompositeFilter.ts +73 -0
  122. package/web/firestore/utils/buildQueryConstraint.d.ts +23 -0
  123. package/web/firestore/utils/buildQueryConstraint.js +41 -0
  124. package/web/firestore/utils/buildQueryConstraint.ts +55 -0
  125. package/web/firestore/utils/getDocData.d.ts +13 -11
  126. package/web/firestore/utils/getDocData.js +6 -9
  127. package/web/firestore/utils/getDocData.ts +14 -20
  128. package/web/firestore/utils/getDocRef.d.ts +14 -11
  129. package/web/firestore/utils/getDocRef.js +7 -8
  130. package/web/firestore/utils/getDocRef.ts +16 -19
  131. package/web/firestore/utils/getDocSnap.d.ts +11 -13
  132. package/web/firestore/utils/getDocSnap.js +5 -10
  133. package/web/firestore/utils/getDocSnap.ts +14 -21
@@ -1,62 +1,74 @@
1
1
  import { useMutation, UseMutationOptions } from "@tanstack/react-query";
2
- import {
3
- DocumentData,
4
- addDoc,
5
- WithFieldValue,
6
- CollectionReference,
7
- getDoc,
8
- FirestoreDataConverter
9
- } from "firebase/firestore";
2
+ import { addDoc, WithFieldValue, CollectionReference, getDoc } from "firebase/firestore";
10
3
 
11
4
  import { FirebaseError } from "firebase/app";
12
5
  import { useMemo } from "react";
6
+ import { AppModel } from "../../types";
13
7
 
8
+ /**
9
+ * @inline
10
+ */
14
11
  export type UseAddDocMutationValues<AppModelType> = {
12
+ /**
13
+ * Data to write
14
+ */
15
15
  data: WithFieldValue<AppModelType>;
16
16
  };
17
17
 
18
- export type UseAddDocMutationOptions<
19
- AppModelType extends DocumentData = DocumentData,
20
- DbModelType extends DocumentData = DocumentData,
21
- TContext = unknown
22
- > = {
23
- reference: CollectionReference<AppModelType, DbModelType>;
24
- converter?: FirestoreDataConverter<AppModelType, DbModelType>;
18
+ /**
19
+ * @inline
20
+ */
21
+ export type UseAddDocMutationOptions<AppModelType extends AppModel = AppModel, TContext = unknown> = {
22
+ /**
23
+ * Reference to a collection where document must be added
24
+ */
25
+ collectionReference: CollectionReference<AppModelType, AppModelType>;
26
+ /**
27
+ * Options for useMutation hook excluding mutationFn. MutationKey will be equal to reference.path by default.
28
+ */
25
29
  options?: Omit<
26
30
  UseMutationOptions<AppModelType, FirebaseError, UseAddDocMutationValues<AppModelType>, TContext>,
27
- "mutationFn" | "mutationKey"
31
+ "mutationFn"
28
32
  >;
29
33
  };
30
34
 
31
35
  /**
32
- * Provides a mutation hook to add a document to a Firestore collection utilizing React Query's `useMutation`.
33
- * It handles addition and optional conversion of the document data in Firestore.
36
+ * Executes a mutation and returns added document
37
+ *
38
+ * @group Hook
39
+ *
40
+ * @param {UseAddDocMutationOptions<AppModelType>} options - Configuration options for the mutation.
41
+ *
42
+ * @returns {UseMutationResult<AppModelType, Error, UseAddDocMutationValues<AppModelType>, TContext>} A mutation result
34
43
  *
35
- * @param {Object} options - Options for the mutation hook
36
- * @param {FirebaseFirestore.CollectionReference<AppModelType>} options.reference - Firestore collection reference where the document should be added.
37
- * @param {FirebaseFirestore.FirestoreDataConverter<DbModelType>} [options.converter] - Optional data converter for reading and writing Firestore documents.
38
- * @param {UseMutationOptions<AppModelType, Error, { data: DbModelType }, TContext>} [options.options={}] - Optional configuration for the mutation.
44
+ * @example
45
+ * ```jsx
46
+ * export const MyComponent = () => {
47
+ * const {mutate} = useAddDocMutation({
48
+ * options: {
49
+ * },
50
+ * reference: collection(),
51
+ * });
39
52
  *
40
- * @returns {UseMutationResult<AppModelType, Error, { data: DbModelType }, TContext>} The mutation hook result containing status, error, and data of the mutation process.
53
+ * // ....
54
+ * mutate({data: {test: 'value'}});
55
+ * // ....
56
+ * };
57
+ * ```
41
58
  */
42
- export const useAddDocMutation = <
43
- AppModelType extends DocumentData = DocumentData,
44
- DbModelType extends DocumentData = DocumentData,
45
- TContext = unknown
46
- >({
47
- reference,
48
- converter,
59
+ export const useAddDocMutation = <AppModelType extends AppModel = AppModel, TContext = unknown>({
60
+ collectionReference,
49
61
  options = {}
50
- }: UseAddDocMutationOptions<AppModelType, DbModelType, TContext>) => {
51
- const mutationKey = useMemo(() => [reference.path], [reference.path]);
62
+ }: UseAddDocMutationOptions<AppModelType, TContext>) => {
63
+ const mutationKey = useMemo(() => [collectionReference.path], [collectionReference.path]);
52
64
 
53
65
  return useMutation({
66
+ mutationKey,
54
67
  ...options,
55
68
  mutationFn: async ({ data }) => {
56
- const docRef = await addDoc<AppModelType, DbModelType>(reference, data);
57
- const docSnap = await getDoc(converter ? docRef.withConverter(converter) : docRef);
58
- return docSnap.data() as AppModelType;
59
- },
60
- mutationKey
69
+ const docRef = await addDoc<AppModelType, AppModelType>(collectionReference, data);
70
+ const docSnap = await getDoc(docRef);
71
+ return { ...docSnap.data(), uid: docSnap.id } as AppModelType;
72
+ }
61
73
  });
62
74
  };
@@ -1,15 +1,42 @@
1
1
  import { UseMutationOptions } from "@tanstack/react-query";
2
2
  import { WriteBatch } from "firebase/firestore";
3
3
  import { FirebaseError } from "firebase/app";
4
+ /**
5
+ * @inline
6
+ */
4
7
  export type UseBatchWriteVariables = (batch: WriteBatch) => Promise<void> | void;
5
- export type UseBatchWriteOptions<TContext = unknown> = {
6
- options?: Omit<UseMutationOptions<void, FirebaseError, UseBatchWriteVariables, TContext>, "mutationFn">;
8
+ /**
9
+ * @inline
10
+ */
11
+ export type UseBatchWriteOptions = {
12
+ /**
13
+ * Options for useMutation hook excluding mutationFn. MutationKey will be equal to reference.path by default.
14
+ */
15
+ options?: Omit<UseMutationOptions<void, FirebaseError, UseBatchWriteVariables>, "mutationFn">;
7
16
  };
8
17
  /**
9
18
  * Custom hook to perform batch write operations using Firestore.
10
- * Utilizes a mutation to carry out the batch write transaction.
11
- * @template TContext - The type of context that can be passed into the hook, defaults to unknown.
12
- * @param {Object} options - The configuration options for the mutation operation.
13
- * @returns {Object} Returns an object composed of elements returned by useMutation, including properties such as status, and functions to trigger and control the mutation process.
19
+ *
20
+ * @group Hook
21
+ *
22
+ * @param {UseBatchWriteOptions} options - Configuration options for the query.
23
+ *
24
+ * @returns {UseMutationResult<void, Error, UseAddDocMutationValues<AppModelType>>} A mutation result
25
+ *
26
+ * @example
27
+ * ```jsx
28
+ * export const MyComponent = () => {
29
+ * const {mutate} = useBatchWrite({
30
+ * options: {
31
+ * },
32
+ * });
33
+ *
34
+ * // ....
35
+ * mutate(() => {
36
+ * ref.update({...})
37
+ * });
38
+ * // ....
39
+ * };
40
+ * ```
14
41
  */
15
- export declare const useBatchWrite: <TContext = unknown>({ options }?: UseBatchWriteOptions<TContext>) => import("@tanstack/react-query").UseMutationResult<void, FirebaseError, UseBatchWriteVariables, TContext>;
42
+ export declare const useBatchWrite: ({ options }?: UseBatchWriteOptions) => import("@tanstack/react-query").UseMutationResult<void, FirebaseError, UseBatchWriteVariables, unknown>;
@@ -3,10 +3,28 @@ import { writeBatch } from "firebase/firestore";
3
3
  import { useFirestore } from "./useFirestore";
4
4
  /**
5
5
  * Custom hook to perform batch write operations using Firestore.
6
- * Utilizes a mutation to carry out the batch write transaction.
7
- * @template TContext - The type of context that can be passed into the hook, defaults to unknown.
8
- * @param {Object} options - The configuration options for the mutation operation.
9
- * @returns {Object} Returns an object composed of elements returned by useMutation, including properties such as status, and functions to trigger and control the mutation process.
6
+ *
7
+ * @group Hook
8
+ *
9
+ * @param {UseBatchWriteOptions} options - Configuration options for the query.
10
+ *
11
+ * @returns {UseMutationResult<void, Error, UseAddDocMutationValues<AppModelType>>} A mutation result
12
+ *
13
+ * @example
14
+ * ```jsx
15
+ * export const MyComponent = () => {
16
+ * const {mutate} = useBatchWrite({
17
+ * options: {
18
+ * },
19
+ * });
20
+ *
21
+ * // ....
22
+ * mutate(() => {
23
+ * ref.update({...})
24
+ * });
25
+ * // ....
26
+ * };
27
+ * ```
10
28
  */
11
29
  export const useBatchWrite = ({ options = {} } = {}) => {
12
30
  const db = useFirestore();
@@ -4,20 +4,47 @@ import { writeBatch, WriteBatch } from "firebase/firestore";
4
4
  import { FirebaseError } from "firebase/app";
5
5
  import { useFirestore } from "./useFirestore";
6
6
 
7
+ /**
8
+ * @inline
9
+ */
7
10
  export type UseBatchWriteVariables = (batch: WriteBatch) => Promise<void> | void;
8
11
 
9
- export type UseBatchWriteOptions<TContext = unknown> = {
10
- options?: Omit<UseMutationOptions<void, FirebaseError, UseBatchWriteVariables, TContext>, "mutationFn">;
12
+ /**
13
+ * @inline
14
+ */
15
+ export type UseBatchWriteOptions = {
16
+ /**
17
+ * Options for useMutation hook excluding mutationFn. MutationKey will be equal to reference.path by default.
18
+ */
19
+ options?: Omit<UseMutationOptions<void, FirebaseError, UseBatchWriteVariables>, "mutationFn">;
11
20
  };
12
21
 
13
22
  /**
14
23
  * Custom hook to perform batch write operations using Firestore.
15
- * Utilizes a mutation to carry out the batch write transaction.
16
- * @template TContext - The type of context that can be passed into the hook, defaults to unknown.
17
- * @param {Object} options - The configuration options for the mutation operation.
18
- * @returns {Object} Returns an object composed of elements returned by useMutation, including properties such as status, and functions to trigger and control the mutation process.
24
+ *
25
+ * @group Hook
26
+ *
27
+ * @param {UseBatchWriteOptions} options - Configuration options for the query.
28
+ *
29
+ * @returns {UseMutationResult<void, Error, UseAddDocMutationValues<AppModelType>>} A mutation result
30
+ *
31
+ * @example
32
+ * ```jsx
33
+ * export const MyComponent = () => {
34
+ * const {mutate} = useBatchWrite({
35
+ * options: {
36
+ * },
37
+ * });
38
+ *
39
+ * // ....
40
+ * mutate(() => {
41
+ * ref.update({...})
42
+ * });
43
+ * // ....
44
+ * };
45
+ * ```
19
46
  */
20
- export const useBatchWrite = <TContext = unknown>({ options = {} }: UseBatchWriteOptions<TContext> = {}) => {
47
+ export const useBatchWrite = ({ options = {} }: UseBatchWriteOptions = {}) => {
21
48
  const db = useFirestore();
22
49
 
23
50
  return useMutation({
@@ -1,18 +1,39 @@
1
- import { CollectionReference, DocumentData, DocumentReference } from "firebase/firestore";
2
- export type UseCollectionReferenceOptions<AppModelType, DbModelType extends DocumentData = DocumentData> = {
3
- reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
1
+ import { CollectionReference, DocumentReference } from "firebase/firestore";
2
+ import { AppModel } from "../../types";
3
+ /**
4
+ * @inline
5
+ */
6
+ export type UseCollectionReferenceOptions<AppModelType extends AppModel = AppModel> = {
7
+ /**
8
+ * CollectionReference or DocumentReference that is used as a root to lookup a sub-collection
9
+ */
10
+ reference?: CollectionReference<AppModelType, AppModelType> | DocumentReference<AppModelType, AppModelType>;
11
+ /**
12
+ * A slash-separated path to a collection.
13
+ */
4
14
  path: string;
15
+ /**
16
+ * Additional path segments that will be applied relative
17
+ */
5
18
  pathSegments?: string[];
6
19
  };
7
20
  /**
8
- * Creates a reference to a Firestore collection based on the provided path, reference, and path segments.
21
+ * Gets a `CollectionReference` instance that refers to a subcollection of
22
+ * `reference` at the specified relative path.
23
+ *
24
+ * @group Hook
25
+ *
26
+ * @param {UseCollectionReferenceOptions<AppModelType>} options - Options
9
27
  *
10
- * This hook utilizes useMemo for optimization, ensuring the collection reference is recalculated only when its dependencies change.
28
+ * @returns {CollectionReference<AppModelType, AppModelType>} A reference to a Firestore collection
11
29
  *
12
- * @param {UseCollectionReferenceOptions<AppModelType, DbModelType>} options - The options including path, reference, and pathSegments to construct the Firestore collection reference.
13
- * @param {string} options.path - The base path for the collection.
14
- * @param {FirestoreReference} options.reference - An optional Firestore reference object that should be of type "collection".
15
- * @param {string[]} options.pathSegments - Additional path segments to append to the base path.
16
- * @returns {CollectionReference} A Firestore collection reference constructed using the specified path, reference, and path segments.
30
+ * @example
31
+ * ```jsx
32
+ * export const MyComponent = () => {
33
+ * const ref = useCollectionReference({
34
+ * path: 'todos'
35
+ * });
36
+ * };
37
+ * ```
17
38
  */
18
- export declare const useCollectionReference: <AppModelType, DbModelType extends DocumentData = DocumentData>({ path, reference, pathSegments }: UseCollectionReferenceOptions<AppModelType, DbModelType>) => CollectionReference<DocumentData, DocumentData>;
39
+ export declare const useCollectionReference: <AppModelType extends AppModel = AppModel>({ path, reference, pathSegments }: UseCollectionReferenceOptions<AppModelType>) => CollectionReference<AppModelType, AppModelType>;
@@ -2,15 +2,23 @@ import { collection } from "firebase/firestore";
2
2
  import { useMemo } from "react";
3
3
  import { useFirestore } from "./useFirestore";
4
4
  /**
5
- * Creates a reference to a Firestore collection based on the provided path, reference, and path segments.
5
+ * Gets a `CollectionReference` instance that refers to a subcollection of
6
+ * `reference` at the specified relative path.
6
7
  *
7
- * This hook utilizes useMemo for optimization, ensuring the collection reference is recalculated only when its dependencies change.
8
+ * @group Hook
8
9
  *
9
- * @param {UseCollectionReferenceOptions<AppModelType, DbModelType>} options - The options including path, reference, and pathSegments to construct the Firestore collection reference.
10
- * @param {string} options.path - The base path for the collection.
11
- * @param {FirestoreReference} options.reference - An optional Firestore reference object that should be of type "collection".
12
- * @param {string[]} options.pathSegments - Additional path segments to append to the base path.
13
- * @returns {CollectionReference} A Firestore collection reference constructed using the specified path, reference, and path segments.
10
+ * @param {UseCollectionReferenceOptions<AppModelType>} options - Options
11
+ *
12
+ * @returns {CollectionReference<AppModelType, AppModelType>} A reference to a Firestore collection
13
+ *
14
+ * @example
15
+ * ```jsx
16
+ * export const MyComponent = () => {
17
+ * const ref = useCollectionReference({
18
+ * path: 'todos'
19
+ * });
20
+ * };
21
+ * ```
14
22
  */
15
23
  export const useCollectionReference = ({ path, reference, pathSegments }) => {
16
24
  const db = useFirestore();
@@ -1,30 +1,51 @@
1
- import { collection, CollectionReference, DocumentData, DocumentReference } from "firebase/firestore";
1
+ import { collection, CollectionReference, DocumentReference } from "firebase/firestore";
2
2
 
3
3
  import { useMemo } from "react";
4
4
  import { useFirestore } from "./useFirestore";
5
+ import { AppModel } from "../../types";
5
6
 
6
- export type UseCollectionReferenceOptions<AppModelType, DbModelType extends DocumentData = DocumentData> = {
7
- reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
7
+ /**
8
+ * @inline
9
+ */
10
+ export type UseCollectionReferenceOptions<AppModelType extends AppModel = AppModel> = {
11
+ /**
12
+ * CollectionReference or DocumentReference that is used as a root to lookup a sub-collection
13
+ */
14
+ reference?: CollectionReference<AppModelType, AppModelType> | DocumentReference<AppModelType, AppModelType>;
15
+ /**
16
+ * A slash-separated path to a collection.
17
+ */
8
18
  path: string;
19
+ /**
20
+ * Additional path segments that will be applied relative
21
+ */
9
22
  pathSegments?: string[];
10
23
  };
11
24
 
12
25
  /**
13
- * Creates a reference to a Firestore collection based on the provided path, reference, and path segments.
26
+ * Gets a `CollectionReference` instance that refers to a subcollection of
27
+ * `reference` at the specified relative path.
28
+ *
29
+ * @group Hook
30
+ *
31
+ * @param {UseCollectionReferenceOptions<AppModelType>} options - Options
14
32
  *
15
- * This hook utilizes useMemo for optimization, ensuring the collection reference is recalculated only when its dependencies change.
33
+ * @returns {CollectionReference<AppModelType, AppModelType>} A reference to a Firestore collection
16
34
  *
17
- * @param {UseCollectionReferenceOptions<AppModelType, DbModelType>} options - The options including path, reference, and pathSegments to construct the Firestore collection reference.
18
- * @param {string} options.path - The base path for the collection.
19
- * @param {FirestoreReference} options.reference - An optional Firestore reference object that should be of type "collection".
20
- * @param {string[]} options.pathSegments - Additional path segments to append to the base path.
21
- * @returns {CollectionReference} A Firestore collection reference constructed using the specified path, reference, and path segments.
35
+ * @example
36
+ * ```jsx
37
+ * export const MyComponent = () => {
38
+ * const ref = useCollectionReference({
39
+ * path: 'todos'
40
+ * });
41
+ * };
42
+ * ```
22
43
  */
23
- export const useCollectionReference = <AppModelType, DbModelType extends DocumentData = DocumentData>({
44
+ export const useCollectionReference = <AppModelType extends AppModel = AppModel>({
24
45
  path,
25
46
  reference,
26
47
  pathSegments
27
- }: UseCollectionReferenceOptions<AppModelType, DbModelType>) => {
48
+ }: UseCollectionReferenceOptions<AppModelType>) => {
28
49
  const db = useFirestore();
29
50
 
30
51
  return useMemo(() => {
@@ -33,5 +54,5 @@ export const useCollectionReference = <AppModelType, DbModelType extends Documen
33
54
  : reference.type === "collection"
34
55
  ? collection(reference, path, ...(pathSegments || []))
35
56
  : collection(reference, path, ...(pathSegments || []));
36
- }, [path, reference, pathSegments, db]);
57
+ }, [path, reference, pathSegments, db]) as CollectionReference<AppModelType, AppModelType>;
37
58
  };
@@ -1,56 +1,11 @@
1
- import { QueryFilterConstraint as FBQueryFilterConstraint, QueryCompositeFilterConstraint as FBQueryCompositeFilterConstraint, WhereFilterOp } from "firebase/firestore";
2
1
  import { AppModel } from "../../types";
3
- export type QueryFilterConstraint = FBQueryFilterConstraint | FBQueryCompositeFilterConstraint;
4
- export type QueryElement<AppModelType extends AppModel = AppModel> = {
5
- operator?: "OR" | "AND";
6
- children?: QueryElement[];
7
- field?: keyof (AppModelType & {
8
- documentId?: string[];
9
- });
10
- value?: AppModelType[keyof AppModelType];
11
- op?: WhereFilterOp;
12
- };
13
- export type CompositeFilter<AppModelType extends AppModel = AppModel> = {
14
- operator: "OR" | "AND";
15
- children: QueryElement<AppModelType & {
16
- documentId?: string[];
17
- }>[];
18
- };
2
+ import { CompositeFilter } from "./utils/buildCompositeFilter";
19
3
  /**
20
4
  * @inline
21
5
  */
22
6
  export type UseCompositeFilter<AppModelType extends AppModel = AppModel> = {
23
7
  query?: CompositeFilter<AppModelType>;
24
8
  };
25
- /**
26
- * Constructs a composite or where query filter based on the provided query structure.
27
- * It recursively builds query constraints using logical "or" or "and" operators.
28
- *
29
- * @group Utility
30
- *
31
- * @param {QueryElement<AppModelType>} query
32
- *
33
- * @returns {QueryFilterConstraint | null}
34
- *
35
- * @example
36
- * ```jsx
37
- * export const MyComponent = () => {
38
- * const filter = buildCompositeFilter({
39
- * operator: "AND",
40
- * children: [
41
- * {
42
- * field: "field",
43
- * value: "value",
44
- * op: "=="
45
- * },
46
- * ...(query ? [query] : [])
47
- * ]
48
- * });
49
- * console.log(filter);
50
- * };
51
- * ```
52
- */
53
- export declare const buildCompositeFilter: <AppModelType extends AppModel = AppModel>(query: QueryElement<AppModelType>) => QueryFilterConstraint | null;
54
9
  /**
55
10
  * A custom hook that constructs a composite or where query filter based on the provided query structure.
56
11
  * It recursively builds query constraints using logical "or" or "and" operators.
@@ -79,4 +34,4 @@ export declare const buildCompositeFilter: <AppModelType extends AppModel = AppM
79
34
  * };
80
35
  * ```
81
36
  */
82
- export declare const useCompositeFilter: <AppModelType extends AppModel = AppModel>({ query }: UseCompositeFilter<AppModelType>) => FBQueryCompositeFilterConstraint | undefined;
37
+ export declare const useCompositeFilter: <AppModelType extends AppModel = AppModel>({ query }: UseCompositeFilter<AppModelType>) => import("@firebase/firestore").QueryCompositeFilterConstraint | undefined;
@@ -1,46 +1,6 @@
1
- import { documentId, and, or, where } from "firebase/firestore";
1
+ import { and, or } from "firebase/firestore";
2
2
  import { useMemo } from "react";
3
- /**
4
- * Constructs a composite or where query filter based on the provided query structure.
5
- * It recursively builds query constraints using logical "or" or "and" operators.
6
- *
7
- * @group Utility
8
- *
9
- * @param {QueryElement<AppModelType>} query
10
- *
11
- * @returns {QueryFilterConstraint | null}
12
- *
13
- * @example
14
- * ```jsx
15
- * export const MyComponent = () => {
16
- * const filter = buildCompositeFilter({
17
- * operator: "AND",
18
- * children: [
19
- * {
20
- * field: "field",
21
- * value: "value",
22
- * op: "=="
23
- * },
24
- * ...(query ? [query] : [])
25
- * ]
26
- * });
27
- * console.log(filter);
28
- * };
29
- * ```
30
- */
31
- export const buildCompositeFilter = (query) => {
32
- if (query.children) {
33
- const queryConstraints = query.children.map(buildCompositeFilter).filter((constraint) => !!constraint);
34
- if (queryConstraints.length <= 0) {
35
- return null;
36
- }
37
- return query.operator === "OR" ? or(...queryConstraints) : and(...queryConstraints);
38
- }
39
- if (query.field && query.op) {
40
- return where(query.field === "documentId" ? documentId() : query.field, query.op, query.value);
41
- }
42
- return null;
43
- };
3
+ import { buildCompositeFilter } from "./utils/buildCompositeFilter";
44
4
  /**
45
5
  * A custom hook that constructs a composite or where query filter based on the provided query structure.
46
6
  * It recursively builds query constraints using logical "or" or "and" operators.
@@ -1,29 +1,7 @@
1
- import {
2
- QueryFilterConstraint as FBQueryFilterConstraint,
3
- QueryCompositeFilterConstraint as FBQueryCompositeFilterConstraint,
4
- WhereFilterOp,
5
- documentId,
6
- and,
7
- or,
8
- where
9
- } from "firebase/firestore";
1
+ import { and, or } from "firebase/firestore";
10
2
  import { useMemo } from "react";
11
3
  import { AppModel } from "../../types";
12
-
13
- export type QueryFilterConstraint = FBQueryFilterConstraint | FBQueryCompositeFilterConstraint;
14
-
15
- export type QueryElement<AppModelType extends AppModel = AppModel> = {
16
- operator?: "OR" | "AND";
17
- children?: QueryElement[];
18
- field?: keyof (AppModelType & { documentId?: string[] });
19
- value?: AppModelType[keyof AppModelType];
20
- op?: WhereFilterOp;
21
- };
22
-
23
- export type CompositeFilter<AppModelType extends AppModel = AppModel> = {
24
- operator: "OR" | "AND";
25
- children: QueryElement<AppModelType & { documentId?: string[] }>[];
26
- };
4
+ import { CompositeFilter, buildCompositeFilter, QueryFilterConstraint } from "./utils/buildCompositeFilter";
27
5
 
28
6
  /**
29
7
  * @inline
@@ -32,54 +10,6 @@ export type UseCompositeFilter<AppModelType extends AppModel = AppModel> = {
32
10
  query?: CompositeFilter<AppModelType>;
33
11
  };
34
12
 
35
- /**
36
- * Constructs a composite or where query filter based on the provided query structure.
37
- * It recursively builds query constraints using logical "or" or "and" operators.
38
- *
39
- * @group Utility
40
- *
41
- * @param {QueryElement<AppModelType>} query
42
- *
43
- * @returns {QueryFilterConstraint | null}
44
- *
45
- * @example
46
- * ```jsx
47
- * export const MyComponent = () => {
48
- * const filter = buildCompositeFilter({
49
- * operator: "AND",
50
- * children: [
51
- * {
52
- * field: "field",
53
- * value: "value",
54
- * op: "=="
55
- * },
56
- * ...(query ? [query] : [])
57
- * ]
58
- * });
59
- * console.log(filter);
60
- * };
61
- * ```
62
- */
63
- export const buildCompositeFilter = <AppModelType extends AppModel = AppModel>(
64
- query: QueryElement<AppModelType>
65
- ): QueryFilterConstraint | null => {
66
- if (query.children) {
67
- const queryConstraints = query.children.map(buildCompositeFilter).filter((constraint) => !!constraint);
68
-
69
- if (queryConstraints.length <= 0) {
70
- return null;
71
- }
72
-
73
- return (query as CompositeFilter).operator === "OR" ? or(...queryConstraints) : and(...queryConstraints);
74
- }
75
-
76
- if (query.field && query.op) {
77
- return where(query.field === "documentId" ? documentId() : (query.field as string), query.op, query.value);
78
- }
79
-
80
- return null;
81
- };
82
-
83
13
  /**
84
14
  * A custom hook that constructs a composite or where query filter based on the provided query structure.
85
15
  * It recursively builds query constraints using logical "or" or "and" operators.
@@ -1,11 +1,11 @@
1
1
  import { CollectionReference, QueryConstraint, QueryNonFilterConstraint } from "firebase/firestore";
2
2
  import { UseQueryResult, UseQueryOptions as UseReactQueryOptions } from "@tanstack/react-query";
3
- import { QueryFilterConstraint } from "./useCompositeFilter";
3
+ import { QueryFilterConstraint } from "./utils/buildCompositeFilter";
4
4
  import { AppModel } from "../../types";
5
5
  /**
6
6
  * @inline
7
7
  */
8
- type UseCountQueryOptions<AppModelType extends AppModel = AppModel, DbModelType extends AppModel = AppModel> = {
8
+ type UseCountQueryOptions<AppModelType extends AppModel = AppModel> = {
9
9
  /**
10
10
  * Reqct-query options that must include queryKey and shall not define queryFn
11
11
  */
@@ -13,7 +13,7 @@ type UseCountQueryOptions<AppModelType extends AppModel = AppModel, DbModelType
13
13
  /**
14
14
  * Reference to a Firestore collection
15
15
  */
16
- collectionReference: CollectionReference<AppModelType, DbModelType>;
16
+ collectionReference: CollectionReference<AppModelType, AppModelType>;
17
17
  /**
18
18
  * Non composite filter constraints such as limit, order, where
19
19
  */
@@ -45,5 +45,5 @@ type UseCountQueryOptions<AppModelType extends AppModel = AppModel, DbModelType
45
45
  * };
46
46
  * ```
47
47
  */
48
- export declare const useCountQuery: <AppModelType extends AppModel = AppModel, DbModelType extends AppModel = AppModel>({ options, collectionReference, queryConstraints, compositeFilter }: UseCountQueryOptions<AppModelType, DbModelType>) => UseQueryResult<number>;
48
+ export declare const useCountQuery: <AppModelType extends AppModel = AppModel>({ options, collectionReference, queryConstraints, compositeFilter }: UseCountQueryOptions<AppModelType>) => UseQueryResult<number>;
49
49
  export {};