zod-firebase-admin/lib/index.d.cts

zod firebase-admin schema

import { DocumentData, CollectionReference, CollectionGroup, DocumentReference, Timestamp, DocumentSnapshot, Query, QuerySnapshot, QueryDocumentSnapshot, FirestoreDataConverter, Firestore as Firestore$1, FieldPath, WhereFilterOp, Filter, OrderByDirection, getFirestore, WithFieldValue, WriteResult, PartialWithFieldValue, SetOptions, UpdateData, Precondition } from 'firebase-admin/firestore';
import { ReadonlyDeep, EmptyObject, Except } from 'type-fest';
import { z, ZodError } from 'zod';

type CollectionPath = [string] | [string, string, string];
declare const firestoreCollectionPath: (path: CollectionPath | string) => string;

declare const firestoreCollection: <AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData>(collectionPath: CollectionPath | string, firestore?: Firestore) => CollectionReference<AppModelType, DbModelType>;

declare const firestoreCollectionGroup: <AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData>(collectionId: string, firestore?: Firestore) => CollectionGroup<AppModelType, DbModelType>;

declare const firestoreDocument: <AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData>(collectionPath: CollectionPath | string, documentId: string, firestore?: Firestore) => DocumentReference<AppModelType, DbModelType>;

declare const firestoreDocumentPath: (collectionPath: CollectionPath | string, documentId: string) => string;

type ZodTypeDocumentData<Output extends DocumentData = DocumentData, Input extends DocumentData = Output> = z.ZodType<Output, any, Input>;
type DocumentInput<Z extends ZodTypeDocumentData = ZodTypeDocumentData> = z.input<Z>;
interface MetaOutputOptions {
    readonly _id?: boolean;
    readonly _createTime?: true;
    readonly _updateTime?: true;
    readonly _readTime?: true;
    readonly readonly?: true;
}
type MetaOutput<Options extends MetaOutputOptions> = (Options['_id'] extends false ? EmptyObject : {
    readonly _id: string;
}) & (Options['_createTime'] extends true ? {
    readonly _createTime: Timestamp;
} : EmptyObject) & (Options['_updateTime'] extends true ? {
    readonly _updateTime: Timestamp;
} : EmptyObject) & (Options['_readTime'] extends true ? {
    readonly _readTime: Timestamp;
} : EmptyObject);
type DocumentOutput<Z extends ZodTypeDocumentData, OutputOptions extends MetaOutputOptions = MetaOutputOptions> = (OutputOptions['readonly'] extends true ? ReadonlyDeep<z.output<Z>> : z.output<Z>) & MetaOutput<OutputOptions>;
type ReadonlyDocumentOutput<Z extends ZodTypeDocumentData, OutputOptions extends MetaOutputOptions = MetaOutputOptions> = ReadonlyDeep<z.output<Z>> & MetaOutput<OutputOptions>;
type ZodDocumentReference<Z extends ZodTypeDocumentData, OutputOptions extends MetaOutputOptions = MetaOutputOptions, AppModelType extends DocumentOutput<Z, OutputOptions> = DocumentOutput<Z, OutputOptions>, DbModelType extends DocumentData = DocumentInput<Z>> = DocumentReference<AppModelType, DbModelType>;
type ZodDocumentSnapshot<Z extends ZodTypeDocumentData, OutputOptions extends MetaOutputOptions = MetaOutputOptions, AppModelType extends DocumentOutput<Z, OutputOptions> = DocumentOutput<Z, OutputOptions>, DbModelType extends DocumentData = DocumentInput<Z>> = DocumentSnapshot<AppModelType, DbModelType>;
type ZodCollectionReference<Z extends ZodTypeDocumentData, OutputOptions extends MetaOutputOptions = MetaOutputOptions, AppModelType extends DocumentOutput<Z, OutputOptions> = DocumentOutput<Z, OutputOptions>, DbModelType extends DocumentData = DocumentInput<Z>> = CollectionReference<AppModelType, DbModelType>;
type ZodCollectionGroup<Z extends ZodTypeDocumentData, OutputOptions extends MetaOutputOptions = MetaOutputOptions, AppModelType extends DocumentOutput<Z, OutputOptions> = DocumentOutput<Z, OutputOptions>, DbModelType extends DocumentData = DocumentInput<Z>> = CollectionGroup<AppModelType, DbModelType>;
type ZodQuery<Z extends ZodTypeDocumentData, OutputOptions extends MetaOutputOptions = MetaOutputOptions, AppModelType extends DocumentOutput<Z, OutputOptions> = DocumentOutput<Z, OutputOptions>, DbModelType extends DocumentData = DocumentInput<Z>> = Query<AppModelType, DbModelType>;
type ZodQuerySnapshot<Z extends ZodTypeDocumentData, OutputOptions extends MetaOutputOptions = MetaOutputOptions, AppModelType extends DocumentOutput<Z, OutputOptions> = DocumentOutput<Z, OutputOptions>, DbModelType extends DocumentData = DocumentInput<Z>> = QuerySnapshot<AppModelType, DbModelType>;

type ZodErrorHandler = <T extends DocumentData = DocumentData>(zodError: ZodError<T>, snapshot: QueryDocumentSnapshot) => Error;

interface FirestoreZodDataConverterOptions {
    readonly includeDocumentIdForZod?: boolean;
    readonly zodErrorHandler?: ZodErrorHandler;
    readonly snapshotDataConverter?: (snapshot: QueryDocumentSnapshot) => DocumentData;
}
declare const firestoreZodDataConverter: <Z extends ZodTypeDocumentData, OutputOptions extends MetaOutputOptions, AppModelType extends DocumentOutput<Z, OutputOptions> = DocumentOutput<Z, OutputOptions>, DbModelType extends DocumentData = DocumentInput<Z>>(zod: Z, outputOptions?: OutputOptions, options?: FirestoreZodDataConverterOptions) => FirestoreDataConverter<AppModelType, DbModelType>;

type FirestoreZodOptions = FirestoreZodDataConverterOptions & {
    readonly firestore?: Firestore$1;
};

type CollectionSchema<Z extends ZodTypeDocumentData = ZodTypeDocumentData, TSubCollectionsSchema extends Schema = EmptyObject> = {
    readonly zod: Z;
    readonly singleDocumentKey?: string;
    readonly includeDocumentIdForZod?: true;
    readonly readonlyDocuments?: true;
} & TSubCollectionsSchema;
type Schema = Record<string, CollectionSchema>;

type CollectionSchemaZod<TCollectionSchema> = TCollectionSchema extends CollectionSchema<infer Z extends ZodTypeDocumentData> ? Z : never;
type SchemaDocumentInput<TCollectionSchema extends CollectionSchema> = z.input<CollectionSchemaZod<TCollectionSchema>> | ReadonlyDeep<z.input<CollectionSchemaZod<TCollectionSchema>>>;
type SchemaDocumentOutput<TCollectionSchema extends CollectionSchema, Options extends MetaOutputOptions = MetaOutputOptions> = TCollectionSchema['readonlyDocuments'] extends true ? ReadonlyDocumentOutput<CollectionSchemaZod<TCollectionSchema>, Options> : DocumentOutput<CollectionSchemaZod<TCollectionSchema>, Options>;

type WhereTuple = [FieldPath | string, WhereFilterOp, any];
type OrderByTuple = [FieldPath | string, OrderByDirection] | [FieldPath | string];
interface QuerySpecification {
    name: string;
    where?: WhereTuple[] | Filter;
    orderBy?: OrderByTuple[];
    limit?: number;
}
declare const applyQuerySpecification: <AppModelType, DbModelType extends DocumentData = DocumentData>(query: Query<AppModelType, DbModelType>, { where, orderBy, limit }: QuerySpecification) => Query<AppModelType, DbModelType>;

interface QueryHelper<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData> {
    prepare(query: QuerySpecification): Query<AppModelType, DbModelType>;
    query(query: QuerySpecification): Promise<QuerySnapshot<AppModelType, DbModelType>>;
    count(query: QuerySpecification): Promise<number>;
    findMany(query: QuerySpecification): Promise<AppModelType[]>;
    findUnique(query: QuerySpecification): Promise<AppModelType | null>;
    findUniqueOrThrow(query: QuerySpecification): Promise<AppModelType>;
    findFirst(query: QuerySpecification): Promise<AppModelType | null>;
    findFirstOrThrow(query: QuerySpecification): Promise<AppModelType>;
}
declare const queryHelper: <AppModelType, DbModelType extends DocumentData>(queryFactory: (querySpecification: QuerySpecification) => Query<AppModelType, DbModelType>) => QueryHelper<AppModelType, DbModelType>;

type SchemaQuery<TCollectionSchema extends CollectionSchema, Options extends MetaOutputOptions = MetaOutputOptions> = Query<SchemaDocumentOutput<TCollectionSchema, Options>, SchemaDocumentInput<TCollectionSchema>>;
type SchemaQuerySnapshot<TCollectionSchema extends CollectionSchema, Options extends MetaOutputOptions = MetaOutputOptions> = QuerySnapshot<SchemaDocumentOutput<TCollectionSchema, Options>, SchemaDocumentInput<TCollectionSchema>>;
type SchemaDocumentSnapshot<TCollectionSchema extends CollectionSchema, Options extends MetaOutputOptions = MetaOutputOptions> = DocumentSnapshot<SchemaDocumentOutput<TCollectionSchema, Options>, SchemaDocumentInput<TCollectionSchema>>;
type SchemaQueryDocumentSnapshot<TCollectionSchema extends CollectionSchema, Options extends MetaOutputOptions = MetaOutputOptions> = QueryDocumentSnapshot<SchemaDocumentOutput<TCollectionSchema, Options>, SchemaDocumentInput<TCollectionSchema>>;
interface SchemaFirestoreQueryFactory<TCollectionSchema extends CollectionSchema> {
    prepare<Options extends MetaOutputOptions>(query: QuerySpecification, options?: Options): SchemaQuery<TCollectionSchema, Options>;
    query<Options extends MetaOutputOptions>(query: QuerySpecification, options?: Options): Promise<SchemaQuerySnapshot<TCollectionSchema, Options>>;
    count(query: QuerySpecification): Promise<number>;
    findMany<Options extends MetaOutputOptions>(query: QuerySpecification, options?: Options): Promise<Array<SchemaDocumentOutput<TCollectionSchema, Options>>>;
    findUnique<Options extends MetaOutputOptions>(query: QuerySpecification, options?: Options): Promise<SchemaDocumentOutput<TCollectionSchema, Options> | null>;
    findUniqueOrThrow<Options extends MetaOutputOptions>(query: QuerySpecification, options?: Options): Promise<SchemaDocumentOutput<TCollectionSchema, Options>>;
    findFirst<Options extends MetaOutputOptions>(query: QuerySpecification, options?: Options): Promise<SchemaDocumentOutput<TCollectionSchema, Options> | null>;
    findFirstOrThrow<Options extends MetaOutputOptions>(query: QuerySpecification, options?: Options): Promise<SchemaDocumentOutput<TCollectionSchema, Options>>;
}

type SchemaReadCollectionReference<TCollectionSchema extends CollectionSchema, Options extends MetaOutputOptions = MetaOutputOptions> = CollectionReference<SchemaDocumentOutput<TCollectionSchema, Options>, SchemaDocumentInput<TCollectionSchema>>;
type SchemaReadDocumentReference<TCollectionSchema extends CollectionSchema, Options extends MetaOutputOptions = MetaOutputOptions> = DocumentReference<SchemaDocumentOutput<TCollectionSchema, Options>, SchemaDocumentInput<TCollectionSchema>>;
type SchemaReadCollectionGroup<TCollectionSchema extends CollectionSchema, Options extends MetaOutputOptions = MetaOutputOptions> = Query<SchemaDocumentOutput<TCollectionSchema, Options>, SchemaDocumentInput<TCollectionSchema>>;
interface SchemaFirestoreReadFactory<TCollectionSchema extends CollectionSchema> {
    collection<Options extends MetaOutputOptions>(this: void, options?: Options): SchemaReadCollectionReference<TCollectionSchema, Options>;
    doc<Options extends MetaOutputOptions>(this: void, id: string, options?: Options): SchemaReadDocumentReference<TCollectionSchema, Options>;
    collectionGroup<Options extends MetaOutputOptions>(this: void, options?: Options): SchemaReadCollectionGroup<TCollectionSchema, Options>;
}

type SchemaWriteCollectionReference<TCollectionSchema extends CollectionSchema> = CollectionReference<SchemaDocumentInput<TCollectionSchema>, SchemaDocumentInput<TCollectionSchema>>;
type SchemaWriteDocumentReference<TCollectionSchema extends CollectionSchema> = DocumentReference<SchemaDocumentInput<TCollectionSchema>, SchemaDocumentInput<TCollectionSchema>>;
interface SchemaFirestoreWriteFactory<TCollectionSchema extends CollectionSchema> {
    collection(this: void): SchemaWriteCollectionReference<TCollectionSchema>;
    doc(this: void, id: string): SchemaWriteDocumentReference<TCollectionSchema>;
}

interface SchemaFirestoreFactory<TCollectionSchema extends CollectionSchema> extends SchemaFirestoreQueryFactory<TCollectionSchema> {
    readonly read: SchemaFirestoreReadFactory<TCollectionSchema>;
    readonly write: SchemaFirestoreWriteFactory<TCollectionSchema>;
}

interface FirestoreFactoryOptions {
    readonly getFirestore?: typeof getFirestore;
}
interface FirestoreZodFactoryOptions extends FirestoreFactoryOptions, Except<FirestoreZodDataConverterOptions, 'includeDocumentIdForZod'> {
}

interface MultiDocumentCollectionFactory<TCollectionSchema extends CollectionSchema> extends SchemaFirestoreFactory<TCollectionSchema> {
    findById<Options extends MetaOutputOptions>(this: void, id: string, options?: Options): Promise<SchemaDocumentOutput<TCollectionSchema, Options> | undefined>;
    findByIdOrThrow<Options extends MetaOutputOptions>(this: void, id: string, options?: Options): Promise<SchemaDocumentOutput<TCollectionSchema, Options>>;
    add(this: void, data: WithFieldValue<SchemaDocumentInput<TCollectionSchema>>): Promise<DocumentReference<SchemaDocumentInput<TCollectionSchema>>>;
    create(this: void, id: string, data: WithFieldValue<SchemaDocumentInput<TCollectionSchema>>): Promise<WriteResult>;
    set(this: void, id: string, data: WithFieldValue<SchemaDocumentInput<TCollectionSchema>>): Promise<WriteResult>;
    set(this: void, id: string, data: PartialWithFieldValue<SchemaDocumentInput<TCollectionSchema>>, options: SetOptions): Promise<WriteResult>;
    update(this: void, id: string, data: UpdateData<SchemaDocumentInput<TCollectionSchema>>, precondition?: Precondition): Promise<WriteResult>;
    delete(this: void, id: string, precondition?: Precondition): Promise<WriteResult>;
}
declare const multiDocumentCollectionFactory: <TCollectionSchema extends CollectionSchema>(firestoreFactory: SchemaFirestoreFactory<TCollectionSchema>) => MultiDocumentCollectionFactory<TCollectionSchema>;

interface SingleDocumentCollectionFactory<TCollectionSchema extends CollectionSchema> {
    readonly singleDocumentKey: string;
    readonly read: Except<SchemaFirestoreReadFactory<TCollectionSchema>, 'doc'> & {
        doc<Options extends MetaOutputOptions>(this: void, options?: Options): SchemaReadDocumentReference<TCollectionSchema, Options>;
    };
    readonly write: Except<SchemaFirestoreWriteFactory<TCollectionSchema>, 'doc'> & {
        doc(this: void): SchemaWriteDocumentReference<TCollectionSchema>;
    };
    find<Options extends MetaOutputOptions>(this: void, options?: Options): Promise<SchemaDocumentOutput<TCollectionSchema, Options> | undefined>;
    findOrThrow<Options extends MetaOutputOptions>(this: void, options?: Options): Promise<SchemaDocumentOutput<TCollectionSchema, Options>>;
    create(this: void, data: WithFieldValue<SchemaDocumentInput<TCollectionSchema>>): Promise<WriteResult>;
    set(this: void, data: WithFieldValue<SchemaDocumentInput<TCollectionSchema>>): Promise<WriteResult>;
    set(this: void, data: PartialWithFieldValue<SchemaDocumentInput<TCollectionSchema>>, options: SetOptions): Promise<WriteResult>;
    update(this: void, data: UpdateData<SchemaDocumentInput<TCollectionSchema>>, precondition?: Precondition): Promise<WriteResult>;
    delete(this: void, precondition?: Precondition): Promise<WriteResult>;
}
declare const singleDocumentCollectionFactory: <TCollectionSchema extends CollectionSchema>(firestoreFactory: SchemaFirestoreFactory<TCollectionSchema>, singleDocumentKey: string) => SingleDocumentCollectionFactory<TCollectionSchema>;

type SingleOrMultiDocumentCollectionFactory<TCollectionSchema extends CollectionSchema> = TCollectionSchema['singleDocumentKey'] extends string ? SingleDocumentCollectionFactory<TCollectionSchema> : MultiDocumentCollectionFactory<TCollectionSchema>;
type CollectionFactory<TCollectionName extends string, TCollectionSchema extends CollectionSchema> = SingleOrMultiDocumentCollectionFactory<TCollectionSchema> & TCollectionSchema & {
    readonly collectionName: TCollectionName;
    readonly collectionPath: string;
};

type SubCollectionsSchema<TSchema> = Omit<TSchema, 'zod' | 'singleDocumentKey' | 'includeDocumentIdForZod' | 'readonlyDocuments'> extends Schema ? Omit<TSchema, 'zod' | 'singleDocumentKey' | 'includeDocumentIdForZod' | 'readonlyDocuments'> : EmptyObject;
type Collections<TSchema extends Schema> = {
    [CollectionName in keyof TSchema]: CollectionName extends string ? TSchema[CollectionName] extends CollectionSchema ? TSchema[CollectionName] & Collection<CollectionName, TSchema[CollectionName]> : never : never;
};
type SubCollections<TSchema extends Schema> = {
    [CollectionName in keyof TSchema]: CollectionName extends string ? TSchema[CollectionName] extends CollectionSchema ? TSchema[CollectionName] & SubCollection<CollectionName, TSchema[CollectionName]> : never : never;
};
type SubCollectionsAccessor<TSchema extends Schema> = (documentId: string) => Collections<TSchema>;
type Collection<TCollectionName extends string, TCollectionSchema extends CollectionSchema> = SubCollectionsSchema<TCollectionSchema> extends Schema ? CollectionFactory<TCollectionName, TCollectionSchema> & SubCollections<SubCollectionsSchema<TCollectionSchema>> & SubCollectionsAccessor<SubCollectionsSchema<TCollectionSchema>> : CollectionFactory<TCollectionName, TCollectionSchema>;
type SubCollection<TCollectionName extends string, TCollectionSchema extends CollectionSchema> = SubCollectionsSchema<TCollectionSchema> extends Schema ? TCollectionSchema & {
    readonly collectionName: TCollectionName;
    readonly group: SchemaFirestoreQueryFactory<TCollectionSchema>;
} & SubCollections<SubCollectionsSchema<TCollectionSchema>> : TCollectionSchema & {
    readonly collectionName: TCollectionName;
    readonly group: SchemaFirestoreQueryFactory<TCollectionSchema>;
};

/**
 * Build collections from a schema
 * @param schema
 * @param options
 */
declare const collectionsBuilder: <TSchema extends Schema>(schema: TSchema, options?: FirestoreZodFactoryOptions) => Collections<TSchema>;

export { type Collection, type CollectionFactory, type CollectionPath, type CollectionSchema, type Collections, type DocumentInput, type DocumentOutput, type FirestoreFactoryOptions, type FirestoreZodDataConverterOptions, type FirestoreZodFactoryOptions, type FirestoreZodOptions, type MetaOutput, type MetaOutputOptions, type MultiDocumentCollectionFactory, type QueryHelper, type QuerySpecification, type ReadonlyDocumentOutput, type Schema, type SchemaDocumentInput, type SchemaDocumentOutput, type SchemaDocumentSnapshot, type SchemaFirestoreFactory, type SchemaFirestoreQueryFactory, type SchemaFirestoreReadFactory, type SchemaFirestoreWriteFactory, type SchemaQuery, type SchemaQueryDocumentSnapshot, type SchemaQuerySnapshot, type SchemaReadCollectionGroup, type SchemaReadCollectionReference, type SchemaReadDocumentReference, type SchemaWriteCollectionReference, type SchemaWriteDocumentReference, type SingleDocumentCollectionFactory, type SingleOrMultiDocumentCollectionFactory, type SubCollection, type SubCollections, type SubCollectionsAccessor, type SubCollectionsSchema, type ZodCollectionGroup, type ZodCollectionReference, type ZodDocumentReference, type ZodDocumentSnapshot, type ZodErrorHandler, type ZodQuery, type ZodQuerySnapshot, type ZodTypeDocumentData, applyQuerySpecification, collectionsBuilder, firestoreCollection, firestoreCollectionGroup, firestoreCollectionPath, firestoreDocument, firestoreDocumentPath, firestoreZodDataConverter, multiDocumentCollectionFactory, queryHelper, singleDocumentCollectionFactory };