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

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 ZodSimpleDocumentData<Output extends DocumentData = DocumentData, Input extends DocumentData = Output> = z.ZodType<Output, Input>;
type ZodUnionDocumentData<T extends ReadonlyArray<ZodSimpleDocumentData>> = z.ZodUnion<T>;
type ZodTypeDocumentData<Output extends DocumentData = DocumentData, Input extends DocumentData = Output> = ZodSimpleDocumentData<Output, Input> | ZodUnionDocumentData<[ZodSimpleDocumentData<Output, 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 extends {
    _id: false;
} ? EmptyObject : {
    readonly _id: string;
}) & (Options extends {
    _createTime: true;
} ? {
    readonly _createTime: Timestamp;
} : EmptyObject) & (Options extends {
    _updateTime: true;
} ? {
    readonly _updateTime: Timestamp;
} : EmptyObject) & (Options extends {
    _readTime: true;
} ? {
    readonly _readTime: Timestamp;
} : EmptyObject);
type DocumentOutput<Z extends ZodTypeDocumentData, OutputOptions extends MetaOutputOptions = MetaOutputOptions> = (OutputOptions extends {
    readonly: 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 extends {
    readonlyDocuments: true;
} ? ReadonlyDocumentOutput<CollectionSchemaZod<TCollectionSchema>, Options> : DocumentOutput<CollectionSchemaZod<TCollectionSchema>, Options>;

type WhereTuple = [FieldPath | string, WhereFilterOp, any];
type OrderByTuple = [FieldPath | string, OrderByDirection] | [FieldPath | string];
interface QuerySpecification<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData> {
    name: string;
    where?: WhereTuple[] | Filter;
    orderBy?: OrderByTuple[];
    limit?: number;
    limitToLast?: number;
    offset?: number;
    startAt?: DocumentSnapshot<AppModelType, DbModelType> | unknown[];
    startAfter?: DocumentSnapshot<AppModelType, DbModelType> | unknown[];
    endAt?: DocumentSnapshot<AppModelType, DbModelType> | unknown[];
    endBefore?: DocumentSnapshot<AppModelType, DbModelType> | unknown[];
}
declare const applyQuerySpecification: <AppModelType, DbModelType extends DocumentData = DocumentData>(query: Query<AppModelType, DbModelType>, { where, orderBy, limit, limitToLast, offset, startAt, startAfter, endAt, endBefore, }: QuerySpecification<AppModelType, DbModelType>) => 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>>;
type SchemaQuerySpecification<TCollectionSchema extends CollectionSchema, TOptions extends MetaOutputOptions = MetaOutputOptions> = QuerySpecification<SchemaDocumentOutput<TCollectionSchema, TOptions>, SchemaDocumentInput<TCollectionSchema>>;
interface SchemaFirestoreQueryFactory<TCollectionSchema extends CollectionSchema> {
    readonly collectionName: string;
    prepare<TOptions extends MetaOutputOptions>(query: SchemaQuerySpecification<TCollectionSchema, TOptions>, options?: TOptions): SchemaQuery<TCollectionSchema, TOptions>;
    query<TOptions extends MetaOutputOptions>(query: SchemaQuerySpecification<TCollectionSchema, TOptions>, options?: TOptions): Promise<SchemaQuerySnapshot<TCollectionSchema, TOptions>>;
    count(query: SchemaQuerySpecification<TCollectionSchema>): Promise<number>;
    findMany<TOptions extends MetaOutputOptions>(query: SchemaQuerySpecification<TCollectionSchema, TOptions>, options?: TOptions): Promise<Array<SchemaDocumentOutput<TCollectionSchema, TOptions>>>;
    findUnique<TOptions extends MetaOutputOptions>(query: SchemaQuerySpecification<TCollectionSchema, TOptions>, options?: TOptions): Promise<SchemaDocumentOutput<TCollectionSchema, TOptions> | null>;
    findUniqueOrThrow<TOptions extends MetaOutputOptions>(query: SchemaQuerySpecification<TCollectionSchema, TOptions>, options?: TOptions): Promise<SchemaDocumentOutput<TCollectionSchema, TOptions>>;
    findFirst<TOptions extends MetaOutputOptions>(query: SchemaQuerySpecification<TCollectionSchema, TOptions>, options?: TOptions): Promise<SchemaDocumentOutput<TCollectionSchema, TOptions> | null>;
    findFirstOrThrow<TOptions extends MetaOutputOptions>(query: SchemaQuerySpecification<TCollectionSchema, TOptions>, options?: TOptions): Promise<SchemaDocumentOutput<TCollectionSchema, TOptions>>;
}

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'> {
}

type SchemaFallbackValue<TCollectionSchema extends CollectionSchema, TDocumentId extends string = string> = TCollectionSchema extends {
    includeDocumentIdForZod: true;
} ? Except<Extract<SchemaDocumentInput<TCollectionSchema>, {
    _id: TDocumentId;
}>, '_id'> : SchemaDocumentInput<TCollectionSchema>;
type SchemaFallbackOutputDocument<TCollectionSchema extends CollectionSchema, TDocumentId extends string = string> = TCollectionSchema extends {
    includeDocumentIdForZod: true;
} ? Except<Extract<SchemaDocumentOutput<TCollectionSchema>, {
    _id: TDocumentId;
}>, '_id'> : SchemaDocumentOutput<TCollectionSchema>;
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>>;
    findByIdWithFallback<TDocumentId extends string>(this: void, id: TDocumentId, fallback: SchemaFallbackValue<TCollectionSchema, TDocumentId>): Promise<SchemaFallbackOutputDocument<TCollectionSchema, TDocumentId>>;
    add(this: void, data: WithFieldValue<SchemaDocumentInput<TCollectionSchema>>): Promise<SchemaWriteDocumentReference<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>, schema: 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>>;
    findWithFallback(this: void, fallback: SchemaFallbackValue<TCollectionSchema>): Promise<SchemaFallbackOutputDocument<TCollectionSchema>>;
    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>, schema: TCollectionSchema, singleDocumentKey: string) => SingleDocumentCollectionFactory<TCollectionSchema>;

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