@dereekb/firebase 11.1.7 → 12.0.0

package/src/lib/common/firestore/query/constraint.template.d.ts

@@ -4,69 +4,139 @@ import { type RootFirestoreModelIdentity } from '../collection/collection';
 import { type DocumentReference, type FieldPathOrStringPath, type FieldPathOrStringPathOf } from '../types';
 import { type FirestoreQueryConstraint, type OrderByDirection } from './constraint';
 /**
- * Use with a CollectionGroup query to return all child documents that are under a given parent.
+ * Creates constraints to query all child documents under a specific parent document reference.
  *
- * @param parentRef U
- * @returns
+ * This function is designed to be used with a CollectionGroup query to filter results to only
+ * include documents that are descendants of the specified parent. It's useful for hierarchical data
+ * structures where you need to retrieve all documents of a certain type that belong to a specific parent.
+ *
+ * @template P - The parent document data type
+ * @param parentRef - The parent document reference
+ * @returns Array of query constraints to filter by parent document
+ *
+ * @example
+ * // Get all 'comments' documents under a specific 'post'
+ * const postRef = doc(firestore, 'posts', postId);
+ * const query = collectionGroup(firestore, 'comments')
+ *   .where(...allChildDocumentsUnderParent(postRef));
  */
 export declare function allChildDocumentsUnderParent<P>(parentRef: DocumentReference<P>): FirestoreQueryConstraint[];
 /**
- * Use with a CollectionGroup query to return all child documents that have a given path.
+ * Creates constraints to query all child documents under a specific parent path.
+ *
+ * Similar to allChildDocumentsUnderParent but takes a string path instead of a document reference.
+ * This is useful when you have the path to a parent document but don't need to create a reference.
+ * Uses a range query on document IDs to efficiently filter for descendants.
  *
- * @param parentPath
- * @returns
+ * @param parentPath - The full path to the parent document (e.g., 'users/123')
+ * @returns Array of query constraints to filter by parent path
+ *
+ * @example
+ * // Get all 'comments' under a specific post without creating a reference
+ * const query = collectionGroup(firestore, 'comments')
+ *   .where(...allChildDocumentsUnderParentPath('posts/abc123'));
  */
 export declare function allChildDocumentsUnderParentPath(parentPath: string): FirestoreQueryConstraint[];
 /**
- * Use with a CollectionGroup query to return all child documents that are under a given path based on values in a field.
+ * Creates constraints to query documents that have a field value starting with a specific prefix.
+ *
+ * Unlike allChildDocumentsUnderParent, this function filters on a field value rather than
+ * the document path. This is useful when you're storing hierarchical references in a field
+ * rather than relying on the document path itself.
  *
- * For example, if each value has a field that references another object with a parent, you can filter on that parent's value range, or parents of that value in order to return
- * all jobs for that range.
+ * For example, if documents have a 'parentPath' field that contains a string path, you can
+ * filter to find all documents where that field starts with a specific value.
  *
- * Example:
- * - objects with path "rc/aaa/rcs/bbb" and "rc/aaa/rcs/ccc" will be returned when querying for "rc/aaa".
+ * @template T - The document data type
+ * @param orderByFieldPath - The field path to filter on
+ * @param parentValue - The string value prefix to match
+ * @param sortDirection - Optional direction to sort results (default: 'asc')
+ * @returns Array of query constraints to filter by field value prefix
  *
- * @param parentValue
- * @returns
+ * @example
+ * // Find all documents where the 'parentPath' field starts with 'organizations/org123/'
+ * const query = collectionGroup(firestore, 'tasks')
+ *   .where(...allChildDocumentsUnderRelativePath('parentPath', 'organizations/org123/'));
  */
 export declare function allChildDocumentsUnderRelativePath<T>(orderByFieldPath: StringKeyPropertyKeys<T>, parentValue: string, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 export declare function allChildDocumentsUnderRelativePath(orderByFieldPath: FieldPathOrStringPath, parentValue: string, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 /**
- * Searches a specified field for string values that start with a model key's collection type.
+ * Creates constraints to find documents where a field contains a reference to a specific model type.
  *
- * @param orderByFieldPath
- * @param parentValue
- * @param sortDirection
+ * This utility searches for string values that start with a specific model collection type prefix.
+ * It's useful when you're storing references to other models as strings in the format
+ * 'collectionType/id'.
+ *
+ * @template T - The document data type
+ * @param orderByFieldPath - The field containing model references
+ * @param value - The root model identity containing the collection type to search for
+ * @param sortDirection - Optional direction to sort results (default: 'asc')
+ * @returns Array of query constraints to filter by model type
+ *
+ * @example
+ * // Find all documents where the 'reference' field contains a reference to a 'users' model
+ * const query = collection(firestore, 'documents')
+ *   .where(...whereStringHasRootIdentityModelKey('reference', { collectionType: 'users' }));
  */
 export declare function whereStringHasRootIdentityModelKey<T = object>(orderByFieldPath: FieldPathOrStringPathOf<T> | FieldPathOrStringPath, value: RootFirestoreModelIdentity, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 /**
- * Searches a specified field for string values that have a specific prefix.
+ * Creates constraints to find documents where a string field starts with a specific prefix.
  *
- * @param orderByFieldPath
- * @param parentValue
- * @param sortDirection
+ * This utility creates a range query that efficiently finds all documents where a string
+ * field starts with the specified prefix. This is more efficient than using a LIKE query
+ * since it can utilize Firestore's indexes.
+ *
+ * @template T - The document data type
+ * @param orderByFieldPath - The string field to search
+ * @param parentValue - The prefix to match at the start of the field
+ * @param sortDirection - Optional direction to sort results (default: 'asc')
+ * @returns Array of query constraints to filter by string prefix
+ *
+ * @example
+ * // Find all documents where the 'email' field starts with 'admin@'
+ * const query = collection(firestore, 'users')
+ *   .where(...whereStringValueHasPrefix('email', 'admin@'));
  */
 export declare function whereStringValueHasPrefix<T>(orderByFieldPath: StringKeyPropertyKeys<T>, parentValue: string, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 export declare function whereStringValueHasPrefix(orderByFieldPath: FieldPathOrStringPath, parentValue: string, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 /**
- * Searches dates that follow between the dates derived from the input. Excludes the end date.
+ * Creates constraints to filter documents by a date field within a specific date range.
  *
- * Sorts in ascending order by default.
+ * This function creates constraints to find documents where a date field falls within
+ * a specified range. It automatically orders the results by the date field and applies
+ * appropriate filters for the start and end dates.
  *
- * @param field
- * @param range
- * @param sortDirection
+ * @template T - The document data type
+ * @param field - The date field to filter on (stored as ISO string in Firestore)
+ * @param dateRange - The date range to filter by (start and/or end date)
+ * @param sortDirection - Optional direction to sort results (default: 'asc')
+ * @returns Array of query constraints to filter by date range
+ *
+ * @example
+ * // Find documents created in the last 7 days
+ * const lastWeek = { startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000) };
+ * const query = collection(firestore, 'documents')
+ *   .where(...filterWithDateRange('createdAt', lastWeek));
  */
 export declare function filterWithDateRange<T>(field: StringKeyPropertyKeys<T>, dateRange: Partial<DateRange>, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 export declare function filterWithDateRange(field: FieldPathOrStringPath, dateRange: Partial<DateRange>, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 /**
- * Searches dates that follow between the dates derived from the input. Excludes the end date.
+ * Creates constraints to filter documents by a date field within a range specified by flexible input.
  *
- * Sorts in ascending order by default.
+ * This function accepts various forms of date range inputs (start/end dates, relative ranges,
+ * predefined periods) and converts them to appropriate query constraints. It's more flexible
+ * than filterWithDateRange because it accepts different input formats.
  *
- * @param field
- * @param range
- * @param sortDirection
+ * @template T - The document data type
+ * @param field - The date field to filter on (stored as ISO string in Firestore)
+ * @param rangeInput - Flexible specification of a date range
+ * @param sortDirection - Optional direction to sort results (default: 'asc')
+ * @returns Array of query constraints to filter by date range
+ *
+ * @example
+ * // Find documents from January 2023
+ * const query = collection(firestore, 'documents')
+ *   .where(...whereDateIsInRange('createdAt', { month: 0, year: 2023 }));
  */
 export declare function whereDateIsInRange<T>(field: StringKeyPropertyKeys<T>, rangeInput: DateRangeInput, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 export declare function whereDateIsInRange(field: FieldPathOrStringPath, rangeInput: DateRangeInput, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
@@ -82,22 +152,45 @@ export declare function whereDateIsInRange(field: FieldPathOrStringPath, rangeIn
 export declare function whereDateIsBetween<T>(field: StringKeyPropertyKeys<T>, range: DateRange, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 export declare function whereDateIsBetween(field: FieldPathOrStringPath, range: DateRange, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 /**
- * Searches dates that are on or after the input date. If no date is input, uses now.
+ * Creates a constraint to filter documents where a date field is greater than or equal to a specified date.
  *
- * @param field
- * @param date
- * @param sortDirection
+ * This function creates a simple comparison constraint that finds documents where a date field
+ * is on or after a specific date. If no date is provided, it defaults to the current date and time.
+ *
+ * @template T - The document data type
+ * @param field - The date field to filter on (stored as ISO string in Firestore)
+ * @param date - The minimum date to include (default: current date/time)
+ * @returns A query constraint to filter for dates on or after the specified date
+ *
+ * @example
+ * // Find documents created today or in the future
+ * const query = collection(firestore, 'documents')
+ *   .where(whereDateIsOnOrAfter('createdAt'));
+ *
+ * // Find documents created on or after a specific date
+ * const startOfYear = new Date(2023, 0, 1);
+ * const query = collection(firestore, 'documents')
+ *   .where(whereDateIsOnOrAfter('createdAt', startOfYear));
  */
 export declare function whereDateIsOnOrAfter<T>(field: StringKeyPropertyKeys<T>, date?: Date): FirestoreQueryConstraint;
 export declare function whereDateIsOnOrAfter(field: FieldPathOrStringPath, date?: Date): FirestoreQueryConstraint;
 /**
- * Searches dates that are on or after the input date. If no date is input, uses now.
+ * Creates constraints to filter documents by dates on or after a specified date, with sorting.
  *
- * Sorts in ascending order by default.
+ * This function combines a date comparison constraint with a sort order, returning an array of
+ * constraints that can be applied to a query. It finds documents where a date field is on or
+ * after a specific date, and sorts the results by that same date field.
  *
- * @param field
- * @param date
- * @param sortDirection
+ * @template T - The document data type
+ * @param field - The date field to filter and sort on (stored as ISO string in Firestore)
+ * @param date - The minimum date to include (default: current date/time)
+ * @param sortDirection - Direction to sort results (default: 'asc')
+ * @returns Array of query constraints for filtering and sorting
+ *
+ * @example
+ * // Find documents created today or in the future, sorted newest first
+ * const query = collection(firestore, 'documents')
+ *   .where(...whereDateIsOnOrAfterWithSort('createdAt', new Date(), 'desc'));
  */
 export declare function whereDateIsOnOrAfterWithSort<T>(field: StringKeyPropertyKeys<T>, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];
 export declare function whereDateIsOnOrAfterWithSort(field: FieldPathOrStringPath, date?: Date, sortDirection?: OrderByDirection): FirestoreQueryConstraint[];

package/src/lib/common/firestore/query/iterator.d.ts

@@ -5,76 +5,262 @@ import { type Observable } from 'rxjs';
 import { type FirestoreQueryDriverRef } from '../driver/query';
 import { type FirestoreQueryConstraint } from './constraint';
 import { type QueryLikeReferenceRef } from '../reference';
+/**
+ * Filter configuration for Firestore query pagination.
+ *
+ * This interface defines how to filter and limit paginated Firestore queries.
+ * It allows specifying both a query limit and additional query constraints.
+ */
 export interface FirestoreItemPageIteratorFilter extends ItemPageLimit {
     /**
-     * Overrides the default limit, if applicable.
+     * Overrides the default limit of items per page, if specified.
+     *
+     * This allows dynamically changing the number of items retrieved in each query
+     * without changing the base configuration.
      */
     readonly limit?: Maybe<number>;
     /**
-     * Constraints to query on.
+     * Query constraints to apply to the paginated query.
+     *
+     * These can include filtering conditions (where), sorting (orderBy), etc.
+     * Note that some constraints like 'limit' will be handled automatically
+     * and should not be included here.
      */
     readonly constraints?: Maybe<ArrayOrValue<FirestoreQueryConstraint>>;
 }
+/**
+ * Base configuration for Firestore query pagination.
+ *
+ * This interface defines the core settings needed for paginated Firestore queries,
+ * including the query reference, driver, and pagination settings.
+ *
+ * @template T - The document data type in the query results
+ */
 export interface FirestoreItemPageIterationBaseConfig<T> extends QueryLikeReferenceRef<T>, FirestoreQueryDriverRef, ItemPageLimit {
     /**
-     * (Optional) number of items per page to load in each query.
+     * Number of items to retrieve per page in each query.
      *
-     * Defaults to 50
+     * This controls the size of each "page" of results. Larger values mean
+     * fewer total queries but more data transferred per query.
+     *
+     * @default 50
      */
     readonly itemsPerPage?: number;
 }
+/**
+ * Complete configuration for Firestore query pagination.
+ *
+ * Combines the base Firestore configuration with the generic pagination configuration,
+ * providing all settings needed for paginated Firestore queries.
+ *
+ * @template T - The document data type in the query results
+ */
 export interface FirestoreItemPageIterationConfig<T> extends FirestoreItemPageIterationBaseConfig<T>, ItemPageIterationConfig<FirestoreItemPageIteratorFilter> {
 }
+/**
+ * Results from a paginated Firestore query.
+ *
+ * This interface encapsulates the results of a single "page" query in a paginated
+ * Firestore query sequence. It includes both the raw query snapshot and convenient
+ * accessors for the document data, along with methods to reload or stream the results.
+ *
+ * @template T - The document data type in the query results
+ */
 export interface FirestoreItemPageQueryResult<T> {
     /**
-     * Time the result was read at.
+     * Timestamp when the result was retrieved.
+     *
+     * Useful for tracking when data was last fetched or for implementing
+     * time-based caching strategies.
      */
     readonly time: Date;
     /**
-     * The relevant docs for this page result. This value will omit the cursor.
+     * Document snapshots for this page of results.
+     *
+     * This array contains the document snapshots returned by the query,
+     * excluding any cursor document used for pagination.
      */
     readonly docs: QueryDocumentSnapshotArray<T>;
     /**
-     * The raw snapshot returned from the query.
+     * The complete query snapshot returned by Firestore.
+     *
+     * This provides access to all metadata and methods of the raw query
+     * snapshot, including size, query information, and document changes.
      */
     readonly snapshot: QuerySnapshot<T>;
     /**
-     * Reloads these results as a snapshot.
+     * Reloads the current page of results.
+     *
+     * This method re-executes the exact same query that produced these results,
+     * fetching the latest data from Firestore. Useful for refreshing data
+     * without changing pagination position.
+     *
+     * @returns A promise that resolves with the fresh query snapshot
      */
     reload(): Promise<QuerySnapshot<T>>;
     /**
-     * Streams these results.
+     * Creates an Observable that streams updates to this query.
+     *
+     * This method establishes a real-time listener for the current page query,
+     * emitting new snapshots whenever the underlying data changes.
+     *
+     * @param options - Optional configuration for the snapshot listener
+     * @returns An Observable of query snapshots that updates in real-time
      */
     stream(options?: FirestoreItemPageQueryResultStreamOptions): Observable<QuerySnapshot<T>>;
 }
+/**
+ * Options for streaming real-time updates to a Firestore query page.
+ *
+ * This interface allows configuring how the real-time listener behaves
+ * when streaming updates to a page of Firestore query results.
+ */
 export interface FirestoreItemPageQueryResultStreamOptions {
+    /**
+     * Optional Firestore snapshot listener options.
+     *
+     * These options control aspects of the snapshot listener like whether to include metadata
+     * changes or wait for a server snapshot.
+     */
     readonly options?: Maybe<SnapshotListenOptions>;
 }
 export type FirestoreItemPageIteratorDelegate<T> = ItemPageIteratorDelegate<FirestoreItemPageQueryResult<T>, FirestoreItemPageIteratorFilter, FirestoreItemPageIterationConfig<T>>;
 export type InternalFirestoreItemPageIterationInstance<T> = ItemPageIterationInstance<FirestoreItemPageQueryResult<T>, FirestoreItemPageIteratorFilter, FirestoreItemPageIterationConfig<T>>;
+/**
+ * Filters out constraints that should not be directly specified in pagination queries.
+ *
+ * This utility function removes constraints that would conflict with the pagination
+ * mechanics, such as 'limit' constraints which are automatically added by the paginator.
+ *
+ * @param constraints - Array of query constraints to filter
+ * @returns Filtered array with disallowed constraints removed
+ */
 export declare function filterDisallowedFirestoreItemPageIteratorInputContraints(constraints: FirestoreQueryConstraint[]): FirestoreQueryConstraint[];
+/**
+ * Default number of items to retrieve per page in paginated Firestore queries.
+ *
+ * This value is used when no itemsPerPage is explicitly specified in the configuration.
+ */
 export declare const DEFAULT_FIRESTORE_ITEM_PAGE_ITERATOR_ITEMS_PER_PAGE = 50;
 export declare function makeFirestoreItemPageIteratorDelegate<T>(): FirestoreItemPageIteratorDelegate<T>;
+/**
+ * Instance for paginated iteration over Firestore documents.
+ *
+ * This interface represents a configured paginator for Firestore documents. It extends the
+ * generic mapped page iteration system to work specifically with Firestore documents,
+ * providing both the document arrays and access to the underlying snapshot iteration.
+ *
+ * @template T - The document data type in the query results
+ */
 export interface FirestoreItemPageIterationInstance<T> extends MappedPageItemIterationInstance<QueryDocumentSnapshotArray<T>, FirestoreItemPageQueryResult<T>, PageLoadingState<QueryDocumentSnapshotArray<T>>, PageLoadingState<FirestoreItemPageQueryResult<T>>, InternalFirestoreItemPageIterationInstance<T>> {
+    /**
+     * The underlying iteration instance that works with raw query snapshots.
+     *
+     * This provides access to the snapshot-level pagination when needed, which is useful
+     * for accessing metadata or other snapshot-specific features not available in the
+     * mapped document arrays.
+     */
     readonly snapshotIteration: InternalFirestoreItemPageIterationInstance<T>;
 }
 /**
- * FirestoreItemPageIteration factory.
+ * Factory for creating Firestore pagination instances.
+ *
+ * This interface provides a standardized way to create pagination instances
+ * for Firestore queries with consistent configuration.
+ *
+ * @template T - The document data type in the query results
  */
 export interface FirestoreItemPageIterationFactory<T> {
+    /**
+     * Function that creates pagination instances with consistent base configuration.
+     *
+     * This factory function allows creating multiple pagination instances that share
+     * the same base configuration but can have different filters applied.
+     */
     readonly firestoreIteration: FirestoreItemPageIterationFactoryFunction<T>;
 }
 /**
- * Function that creates a FirestoreItemPageIterationInstance from the input filter.
+ * Function that creates a Firestore pagination instance using the specified filter.
+ *
+ * This type represents a factory function that creates pagination instances with
+ * predefined base configuration. The only parameter needed is the filter that specifies
+ * what constraints to apply and how many items to load per page.
+ *
+ * @template T - The document data type in the query results
  */
 export type FirestoreItemPageIterationFactoryFunction<T> = (filter?: FirestoreItemPageIteratorFilter) => FirestoreItemPageIterationInstance<T>;
 /**
- * Creates a new factory function that can build FirestoreItemPageIterationInstance values from just the input filter.
+ * Creates a factory function for generating Firestore pagination instances with consistent base configuration.
+ *
+ * This higher-order function takes a base configuration and returns a specialized factory function
+ * that can create properly configured pagination instances. This is useful when you need to create
+ * multiple pagination instances for the same collection but with different filters.
+ *
+ * @template T - The document data type in the query results
+ * @param baseConfig - The base configuration shared by all created pagination instances
+ * @returns A factory function that creates pagination instances with the specified base configuration
  *
- * @param baseConfig
- * @returns FirestoreItemPageIterationInstance
+ * @example
+ * // Create a factory for paginating users collection
+ * const usersQuery = collection(firestore, 'users');
+ * const usersPaginator = firestoreItemPageIterationFactory({
+ *   queryLike: usersQuery,
+ *   itemsPerPage: 20,
+ *   firestoreQueryDriver: driver
+ * });
+ *
+ * // Create specific pagination instances with different filters
+ * const activePaginator = usersPaginator({
+ *   constraints: [where('status', '==', 'active')]
+ * });
+ * const adminPaginator = usersPaginator({
+ *   constraints: [where('role', '==', 'admin')]
+ * });
  */
 export declare function firestoreItemPageIterationFactory<T>(baseConfig: FirestoreItemPageIterationBaseConfig<T>): FirestoreItemPageIterationFactoryFunction<T>;
+/**
+ * Default delegate that implements Firestore pagination logic.
+ *
+ * This singleton instance handles the core logic of paginated Firestore queries,
+ * including cursor management and document fetching.
+ */
 export declare const FIRESTORE_ITEM_PAGE_ITERATOR_DELEGATE: FirestoreItemPageIteratorDelegate<unknown>;
+/**
+ * Default iterator that provides Firestore pagination functionality.
+ *
+ * This singleton instance is the core pagination iterator used by the library.
+ * It uses the default delegate to implement paginated Firestore queries.
+ */
 export declare const FIRESTORE_ITEM_PAGE_ITERATOR: ItemPageIterator<FirestoreItemPageQueryResult<unknown>, FirestoreItemPageIteratorFilter, FirestoreItemPageIterationConfig<unknown>>;
+/**
+ * Creates a Firestore pagination instance that handles loading documents in pages.
+ *
+ * This function creates a pagination instance that loads Firestore documents in pages,
+ * automatically handling cursor-based pagination. It returns a mapped iteration instance
+ * that directly provides document arrays while also exposing access to the underlying
+ * snapshot iteration.
+ *
+ * @template T - The document data type in the query results
+ * @param config - The configuration for the pagination
+ * @returns A Firestore pagination instance that loads documents in pages
+ *
+ * @example
+ * // Create a pagination instance for a users collection
+ * const usersPagination = firestoreItemPageIteration({
+ *   queryLike: collection(firestore, 'users'),
+ *   itemsPerPage: 10,
+ *   firestoreQueryDriver: driver,
+ *   filter: {
+ *     constraints: [where('status', '==', 'active'), orderBy('createdAt', 'desc')]
+ *   }
+ * });
+ *
+ * // Load the first page of results
+ * const firstPage = await usersPagination.loadNextPage().toPromise();
+ * console.log('First 10 users:', firstPage);
+ *
+ * // Load the next page when needed
+ * const secondPage = await usersPagination.loadNextPage().toPromise();
+ * console.log('Next 10 users:', secondPage);
+ */
 export declare function firestoreItemPageIteration<T>(config: FirestoreItemPageIterationConfig<T>): FirestoreItemPageIterationInstance<T>;