@lpdjs/firestore-repo-service 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,420 @@
+import { DocumentReference, Firestore, DocumentSnapshot, WhereFilterOp, Query, QuerySnapshot, CollectionReference, WriteBatch, Transaction } from 'firebase-admin/firestore';
+
+/**
+ * Extract the documentRef signature from refCb (without the db parameter)
+ * @internal
+ */
+type ExtractDocumentRefSignature<T> = T extends (db: Firestore, ...args: infer P) => DocumentReference ? (...args: P) => DocumentReference : never;
+/**
+ * Extract the update signature from refCb
+ * @internal
+ */
+type ExtractUpdateSignature<T, TType> = T extends (db: Firestore, ...args: infer P) => DocumentReference ? (...args: [...P, Partial<TType>]) => Promise<TType> : never;
+/**
+ * Type for a where condition with strict value typing based on the field
+ * @template T - Data model type
+ */
+type WhereClause<T = any> = {
+    [K in keyof T]: {
+        field: K;
+        operator: WhereFilterOp;
+        value: T[K] | T[K][];
+    };
+}[keyof T];
+/**
+ * Query options for filtering, sorting and paginating results
+ * @template T - Data model type
+ */
+interface QueryOptions<T = any> {
+    where?: WhereClause<T>[];
+    orWhere?: WhereClause<T>[][];
+    orderBy?: {
+        field: keyof T;
+        direction?: "asc" | "desc";
+    }[];
+    limit?: number;
+    offset?: number;
+    startAt?: DocumentSnapshot | any[];
+    startAfter?: DocumentSnapshot | any[];
+    endAt?: DocumentSnapshot | any[];
+    endBefore?: DocumentSnapshot | any[];
+}
+/**
+ * Result type for get operations with optional document snapshot
+ * @internal
+ */
+type GetResult<T, ReturnDoc extends boolean> = ReturnDoc extends true ? {
+    data: T;
+    doc: DocumentSnapshot;
+} | null : T | null;
+/**
+ * Relation configuration for a field with strict typing
+ * @template TRepoKey - Target repository name (key from mapping)
+ * @template TForeignKey - Target foreign key name
+ * @template TType - Relation type: "one" for one-to-one, "many" for one-to-many
+ * @template TTargetModel - Type of the target model (inferred from mapping)
+ */
+interface RelationConfig<TRepoKey extends string = string, TForeignKey extends string = string, TType extends "one" | "many" = "one" | "many", TTargetModel = any> {
+    repo: TRepoKey;
+    key: TForeignKey;
+    type: TType;
+    targetType?: TTargetModel;
+}
+/**
+ * Relational key mapping between repositories with strict typing
+ * Maps a field from the current model to a target repository and foreign key
+ * @template T - Current model type
+ * @template TMapping - All repositories mapping for validation
+ * @example { userId: { repo: "users", key: "docId", type: "one" } }
+ *
+ * IMPORTANT: Keys must exist in T (the current model)
+ * This prevents creating relations on non-existent fields
+ */
+type RelationalKeys<T = any, TMapping = any> = {
+    [K in keyof T]?: TMapping extends Record<string, any> ? {
+        [R in keyof TMapping]: TMapping[R] extends RepositoryConfig<any, infer FKeys, any, any, any, any> ? {
+            repo: R;
+            key: FKeys[number];
+            type: "one" | "many";
+        } : never;
+    }[keyof TMapping] : RelationConfig;
+};
+/**
+ * Configuration interface for repositories with strict literal type inference
+ * @template T - The data model type
+ * @template TForeignKeys - Foreign keys used for unique document retrieval
+ * @template TQueryKeys - Query keys used for multiple document searches
+ * @template TIsGroup - Whether this is a collection group query
+ * @template TRefCb - Callback function signature for creating document references
+ * @template TRelationalKeys - Relational keys mapping to other repositories
+ */
+interface RepositoryConfig<T, TForeignKeys extends readonly (keyof T)[], TQueryKeys extends readonly (keyof T)[], TIsGroup extends boolean = boolean, TRefCb = any, TRelationalKeys = {}> {
+    path: string;
+    isGroup: TIsGroup;
+    foreignKeys: TForeignKeys;
+    queryKeys: TQueryKeys;
+    type: T;
+    refCb?: TRefCb;
+    relationalKeys?: TRelationalKeys;
+    documentRef: TRefCb extends undefined ? TIsGroup extends true ? (...pathSegments: string[]) => DocumentReference : (docId: string) => DocumentReference : ExtractDocumentRefSignature<TRefCb>;
+    update: TRefCb extends undefined ? TIsGroup extends true ? (...args: [...string[], Partial<T>]) => Promise<T> : (docId: string, data: Partial<T>) => Promise<T> : ExtractUpdateSignature<TRefCb, T>;
+}
+
+/**
+ * Pagination result with data and cursor information
+ * @template T - Data model type
+ */
+interface PaginationResult<T> {
+    /** Array of documents for the current page */
+    data: T[];
+    /** Cursor to the next page (undefined if no more pages) */
+    nextCursor?: DocumentSnapshot;
+    /** Cursor to the previous page (undefined if on first page) */
+    prevCursor?: DocumentSnapshot;
+    /** Whether there are more pages after this one */
+    hasNextPage: boolean;
+    /** Whether there are pages before this one */
+    hasPrevPage: boolean;
+    /** Total number of items in current page */
+    pageSize: number;
+}
+/**
+ * Pagination options for cursor-based pagination
+ * @template T - Data model type
+ */
+interface PaginationOptions<T> extends Omit<QueryOptions<T>, "limit"> {
+    /** Number of items per page */
+    pageSize: number;
+    /** Cursor to start after (for next page) */
+    cursor?: DocumentSnapshot;
+    /** Direction of pagination */
+    direction?: "next" | "prev";
+}
+/**
+ * Helper to apply query options to a Firestore query
+ */
+declare function applyQueryOptions<T>(q: Query, options: QueryOptions<T>): Query;
+/**
+ * Executes a paginated query and returns results with pagination info
+ * Uses the advanced query builder that handles OR conditions and automatic splitting
+ * @template T - Data model type
+ * @param baseQuery - Base Firestore query
+ * @param options - Pagination options
+ * @returns Pagination result with data and cursor information
+ */
+declare function executePaginatedQuery<T>(baseQuery: Query, options: PaginationOptions<T>): Promise<PaginationResult<T>>;
+/**
+ * Creates an async generator for iterating through all pages
+ * @template T - Data model type
+ * @param baseQuery - Base Firestore query
+ * @param options - Pagination options (without cursor)
+ * @yields Pagination results for each page
+ * @example
+ * ```typescript
+ * const pageIterator = createPaginationIterator(query, { pageSize: 10 });
+ * for await (const page of pageIterator) {
+ *   console.log(`Page with ${page.pageSize} items`);
+ *   page.data.forEach(item => console.log(item));
+ *   if (!page.hasNextPage) break;
+ * }
+ * ```
+ */
+declare function createPaginationIterator<T>(baseQuery: Query, options: Omit<PaginationOptions<T>, "cursor" | "direction">): AsyncGenerator<PaginationResult<T>, void, unknown>;
+
+/**
+ * Build and execute query with automatic splitting for in/array-contains-any
+ * Handles both simple AND conditions and complex OR conditions
+ */
+declare function buildAndExecuteQuery<T>(baseQuery: Query, options: QueryOptions<T>): Promise<QuerySnapshot>;
+
+/**
+ * Helper type to extract populated data structure from a single relation
+ * @internal
+ */
+type ExtractPopulatedFromRelation<TRelation> = TRelation extends RelationConfig<infer TRepo, any, infer TType, infer TTargetModel> ? {
+    [P in TRepo]: TType extends "one" ? TTargetModel | null : TTargetModel[];
+} : Record<string, never>;
+/**
+ * Helper type to merge multiple populated objects into one
+ * @internal
+ */
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Generates get.by* methods from foreign keys
+ * @internal
+ */
+type GenerateGetMethods<TConfig extends RepositoryConfig<any, any, any, any, any, any>> = {
+    [K in TConfig["foreignKeys"][number] as K extends string ? `by${Capitalize<K>}` : never]: <ReturnDoc extends boolean = false>(value: TConfig["type"][K], returnDoc?: ReturnDoc) => Promise<GetResult<TConfig["type"], ReturnDoc>>;
+};
+/**
+ * Generates query.by* methods from query keys
+ * @internal
+ */
+type GenerateQueryMethods<TConfig extends RepositoryConfig<any, any, any, any, any, any>> = {
+    [K in TConfig["queryKeys"][number] as K extends string ? `by${Capitalize<K>}` : never]: (value: TConfig["type"][K], options?: QueryOptions<TConfig["type"]>) => Promise<TConfig["type"][]>;
+};
+/**
+ * Configured repository with organized methods
+ */
+type ConfiguredRepository<T extends RepositoryConfig<any, any, any, any, any, any>> = {
+    ref: CollectionReference | Query;
+    get: GenerateGetMethods<T> & {
+        byList: <K extends keyof T["type"], ReturnDoc extends boolean = false>(key: K, values: T["type"][K][], operator?: "in" | "array-contains-any", returnDoc?: ReturnDoc) => Promise<ReturnDoc extends true ? Array<{
+            data: T["type"];
+            doc: DocumentSnapshot;
+        }> : T["type"][]>;
+    };
+    query: GenerateQueryMethods<T> & {
+        by: (options: QueryOptions<T["type"]>) => Promise<T["type"][]>;
+        getAll: (options?: QueryOptions<T["type"]>) => Promise<T["type"][]>;
+        onSnapshot: (options: QueryOptions<T["type"]>, onNext: (data: T["type"][]) => void, onError?: (error: Error) => void) => () => void;
+        paginate: (options: PaginationOptions<T["type"]>) => ReturnType<typeof executePaginatedQuery<T["type"]>>;
+        paginateAll: (options: Omit<PaginationOptions<T["type"]>, "cursor" | "direction">) => ReturnType<typeof createPaginationIterator<T["type"]>>;
+    };
+    aggregate: {
+        count: (options?: QueryOptions<T["type"]>) => Promise<number>;
+        sum: <K extends keyof T["type"]>(field: K, options?: QueryOptions<T["type"]>) => Promise<number>;
+        average: <K extends keyof T["type"]>(field: K, options?: QueryOptions<T["type"]>) => Promise<number | null>;
+    };
+    documentRef: T["documentRef"];
+    create: (data: Partial<T["type"]>) => Promise<T["type"] & {
+        docId: string;
+    }>;
+    set: (...args: [
+        ...Parameters<T["documentRef"]>,
+        Partial<T["type"]>,
+        {
+            merge?: boolean;
+        }?
+    ]) => Promise<T["type"]>;
+    update: T["update"];
+    delete: (...args: Parameters<T["documentRef"]>) => Promise<void>;
+    batch: {
+        create: () => {
+            batch: WriteBatch;
+            set: (...args: [
+                ...Parameters<T["documentRef"]>,
+                Partial<T["type"]>,
+                {
+                    merge?: boolean;
+                }?
+            ]) => void;
+            update: (...args: [...Parameters<T["documentRef"]>, Partial<T["type"]>]) => void;
+            delete: (...args: Parameters<T["documentRef"]>) => void;
+            commit: () => Promise<void>;
+        };
+    };
+    transaction: {
+        run: <R>(updateFunction: (transaction: {
+            get: (...args: Parameters<T["documentRef"]>) => Promise<T["type"] | null>;
+            set: (...args: [
+                ...Parameters<T["documentRef"]>,
+                Partial<T["type"]>,
+                {
+                    merge?: boolean;
+                }?
+            ]) => void;
+            update: (...args: [...Parameters<T["documentRef"]>, Partial<T["type"]>]) => void;
+            delete: (...args: Parameters<T["documentRef"]>) => void;
+            raw: Transaction;
+        }) => Promise<R>) => Promise<R>;
+    };
+    bulk: {
+        set: (items: Array<{
+            docRef: DocumentReference;
+            data: Partial<T["type"]>;
+            merge?: boolean;
+        }>) => Promise<void>;
+        update: (items: Array<{
+            docRef: DocumentReference;
+            data: Partial<T["type"]>;
+        }>) => Promise<void>;
+        delete: (docRefs: DocumentReference[]) => Promise<void>;
+    };
+    populate: <K extends keyof NonNullable<T["relationalKeys"]>>(document: T["type"], relationKey: K | K[]) => Promise<T["type"] & {
+        populated: UnionToIntersection<K extends keyof NonNullable<T["relationalKeys"]> ? ExtractPopulatedFromRelation<NonNullable<T["relationalKeys"]>[K]> : Record<string, never>>;
+    }>;
+};
+
+/**
+ * Helper to create a typed repository configuration with literal type preservation
+ * Uses currying pattern to allow type parameter inference
+ * @template T - The data model type
+ * @returns Builder function that accepts repository configuration with withRelations method
+ * @example
+ * ```typescript
+ * const mapping = {
+ *   users: createRepositoryConfig<UserModel>()({
+ *     path: "users",
+ *     foreignKeys: ["docId", "email"] as const,
+ *     queryKeys: ["isActive"] as const,
+ *     refCb: (db, docId: string) => db.collection("users").doc(docId),
+ *   }),
+ *   posts: createRepositoryConfig<PostModel>()({
+ *     path: "posts",
+ *     foreignKeys: ["docId", "userId"] as const,
+ *     queryKeys: ["status"] as const,
+ *     refCb: (db, docId: string) => db.collection("posts").doc(docId),
+ *   }).withRelations<typeof mapping>()({
+ *     userId: { repo: "users", key: "docId", type: "one" as const }
+ *   })
+ * };
+ * ```
+ */
+declare function createRepositoryConfig<T>(): <const TForeignKeys extends readonly (keyof T)[], const TQueryKeys extends readonly (keyof T)[], const TIsGroup extends boolean, TRefCb = undefined>(config: {
+    path: string;
+    isGroup: TIsGroup;
+    foreignKeys: TForeignKeys;
+    queryKeys: TQueryKeys;
+    refCb: TRefCb;
+}) => RepositoryConfig<T, TForeignKeys, TQueryKeys, TIsGroup, TRefCb, {}>;
+/**
+ * Helper type to resolve a single relation configuration
+ * Extracts the target model type from the mapping
+ */
+type ResolveRelation<TMapping, TRelationConfig> = TRelationConfig extends {
+    repo: infer R;
+    key: infer FK;
+    type: infer RT;
+} ? R extends keyof TMapping ? TMapping[R] extends {
+    type: infer TTarget;
+} ? RelationConfig<R & string, FK & string, RT & ("one" | "many"), TTarget> : never : never : never;
+/**
+ * Helper to add relations to a repository mapping with full type validation
+ * Validates that repo names and foreign keys exist in the mapping
+ * @template TMapping - The complete repository mapping for validation
+ * @template TRelations - Relations configuration with strict typing
+ * @param mapping - The base repository mapping
+ * @param relations - Relations configuration for each repository
+ * @returns Updated mapping with relations and full type safety
+ * @example
+ * ```typescript
+ * const mapping = {
+ *   users: createRepositoryConfig<UserModel>()({ ... }),
+ *   posts: createRepositoryConfig<PostModel>()({ ... }),
+ * };
+ *
+ * const mappingWithRelations = buildRepositoryRelations(mapping, {
+ *   posts: {
+ *     userId: { repo: "users", key: "docId", type: "one" as const }
+ *   }
+ * });
+ *
+ * const repos = createRepositoryMapping(db, mappingWithRelations);
+ * ```
+ */
+declare function buildRepositoryRelations<TMapping extends Record<string, any>, const TRelations extends {
+    [K in keyof TMapping]?: TMapping[K] extends RepositoryConfig<infer T, any, any, any, any, any> ? {
+        [RK in keyof T]?: {
+            [R in keyof TMapping]: TMapping[R] extends RepositoryConfig<infer TTargetModel, infer TForeignKeys, any, any, any, any> ? {
+                repo: R;
+                key: TForeignKeys[number];
+                type: "one" | "many";
+            } : never;
+        }[keyof TMapping];
+    } : never;
+}>(mapping: TMapping, relations: TRelations): {
+    [K in keyof TMapping]: K extends keyof TRelations ? TMapping[K] extends RepositoryConfig<infer T, infer TForeignKeys, infer TQueryKeys, infer TIsGroup, infer TRefCb, any> ? RepositoryConfig<T, TForeignKeys, TQueryKeys, TIsGroup, TRefCb, {
+        [RK in keyof TRelations[K]]: ResolveRelation<TMapping, TRelations[K][RK]>;
+    }> : TMapping[K] : TMapping[K];
+};
+/**
+ * Repository mapping class that manages Firestore repositories with type safety
+ * @template T - Record of repository configurations
+ */
+declare class RepositoryMapping<T extends Record<string, any>> {
+    private db;
+    private repositoryCache;
+    private mapping;
+    private allRepositories;
+    /**
+     * Creates a new RepositoryMapping instance
+     * @param db - Firestore instance from firebase-admin
+     * @param mapping - Repository configuration mapping
+     */
+    constructor(db: Firestore, mapping: T);
+    /**
+     * Initialize all repositories in two passes to handle circular dependencies
+     * @private
+     */
+    private initializeRepositories;
+    /**
+     * Gets a repository (already initialized)
+     * @template K - Repository key
+     * @param key - Repository identifier
+     * @returns Configured repository instance
+     */
+    getRepository<K extends keyof T>(key: K): ConfiguredRepository<T[K]>;
+}
+/**
+ * Helper function to create a RepositoryMapping instance with full typing
+ * @template T - Record of repository configurations
+ * @param db - Firestore instance from firebase-admin
+ * @param mapping - Repository configurations
+ * @returns RepositoryMapping instance with repository access via getters
+ * @example
+ * ```typescript
+ * import * as admin from 'firebase-admin';
+ *
+ * admin.initializeApp();
+ * const db = admin.firestore();
+ *
+ * const repos = createRepositoryMapping(db, {
+ *   users: createRepositoryConfig<UserModel>()({
+ *     path: "users",
+ *     isGroup: false,
+ *     foreignKeys: ["docId", "email"] as const,
+ *     queryKeys: ["isActive"] as const,
+ *     refCb: (db, docId: string) => db.collection("users").doc(docId),
+ *   }),
+ * });
+ *
+ * // Access repositories directly
+ * const user = await repos.users.get.byDocId("123");
+ * ```
+ */
+declare function createRepositoryMapping<T extends Record<string, any>>(db: Firestore, mapping: T): RepositoryMapping<T> & {
+    [K in keyof T]: ConfiguredRepository<T[K]>;
+};
+
+export { type ConfiguredRepository, type ExtractDocumentRefSignature, type ExtractUpdateSignature, type GenerateGetMethods, type GenerateQueryMethods, type GetResult, type PaginationOptions, type PaginationResult, type QueryOptions, type RelationConfig, type RelationalKeys, type RepositoryConfig, RepositoryMapping, type WhereClause, applyQueryOptions as applyPaginationQueryOptions, buildAndExecuteQuery, buildRepositoryRelations, createPaginationIterator, createRepositoryConfig, createRepositoryMapping, executePaginatedQuery };