@intuitionrobotics/db-api-generator/app-backend/BaseDB_ApiGenerator.d.ts

db-api-generator

import { Clause_Where, DB_Object, FilterKeys, FirestoreQuery } from "@intuitionrobotics/firebase";
import { Module, PartialProperties, ValidatorTypeResolver } from "@intuitionrobotics/ts-common";
import { ServerApi_Create } from "./apis";
import { ExpressRequest, FirestoreBackupDetails, OnFirestoreBackupSchedulerAct, ServerApi } from "@intuitionrobotics/thunderstorm/backend";
import { FirestoreCollection, FirestoreTransaction } from "@intuitionrobotics/firebase/backend";
export declare const validateId: (length: number, mandatory?: boolean) => import("@intuitionrobotics/ts-common").Validator<string>;
export declare const validateEmail: import("@intuitionrobotics/ts-common").Validator<string>;
export declare const validateBucketUrl: (mandatory?: boolean) => import("@intuitionrobotics/ts-common").Validator<string>;
export declare const validateGeneralUrl: (mandatory?: boolean) => import("@intuitionrobotics/ts-common").Validator<string>;
export declare const validateUniqueId: import("@intuitionrobotics/ts-common").Validator<string>;
export declare const validateOptionalId: import("@intuitionrobotics/ts-common").Validator<string>;
export declare const validateStringWithDashes: import("@intuitionrobotics/ts-common").Validator<string>;
export declare const validateStringAndNumbersWithDashes: import("@intuitionrobotics/ts-common").Validator<string>;
export declare const validator_JavaObjectMemberName: import("@intuitionrobotics/ts-common").Validator<string>;
export declare const validateNameWithDashesAndDots: import("@intuitionrobotics/ts-common").Validator<string>;
export declare const validator_LowercaseStringWithDashes: import("@intuitionrobotics/ts-common").Validator<string>;
export declare const validator_LowerUpperStringWithSpaces: import("@intuitionrobotics/ts-common").Validator<string>;
export declare const validator_LowerUpperStringWithDashesAndUnderscore: import("@intuitionrobotics/ts-common").Validator<string>;
export declare const validator_InternationalPhoneNumber: import("@intuitionrobotics/ts-common").Validator<string>;
export type CustomUniquenessAssertion<Type extends DB_Object> = (transaction: FirestoreTransaction, dbInstance: Type) => Promise<void>;
export type Config<Type extends object> = {
    projectId?: string;
    lockKeys: (keyof Type)[];
    collectionName: string;
    itemName: string;
    externalFilterKeys: FilterKeys<Type>;
};
/**
 * An abstract base class used for implementing CRUD operations on a specific collection.
 *
 * By default, it exposes API endpoints for creating, deleting, updating, querying and querying for unique document.
 */
export declare abstract class BaseDB_ApiGenerator<DBType extends DB_Object, ConfigType extends Config<DBType> = Config<DBType>, UType extends PartialProperties<DBType, "_id"> = PartialProperties<DBType, "_id">> extends Module<ConfigType> implements OnFirestoreBackupSchedulerAct {
    readonly collection: FirestoreCollection<DBType>;
    protected validator: ValidatorTypeResolver<DBType>;
    protected constructor(collectionName: string, validator: ValidatorTypeResolver<DBType>, itemName: string, moduleName: string);
    setValidator(validator: ValidatorTypeResolver<DBType>): void;
    __onFirestoreBackupSchedulerAct(): FirestoreBackupDetails<DBType>[];
    protected resolveBackupQuery(): FirestoreQuery<DBType>;
    /**
     * Sets the external unique keys. External keys are the attributes of a document that must be unique inside the
     * collection. Default is `_id`.
     *
     * @remarks
     * You can only update the external unique keys before the module is initialized, preferably from its constructor.
     *
     * @param keys - The external unique keys.
     *
     * @returns
     * The external filter keys.
     */
    protected setExternalUniqueKeys(keys: FilterKeys<DBType>): FilterKeys<DBType>;
    /**
     * Sets the lock keys. Lock keys are the attributes of a document that must not be changed during a patch.
     * Thr property `_id` is always part of the lock keys.
     *
     * @remarks
     * You can only update the lock keys before the module is initialized, preferably from its constructor.
     *
     * @param keys - The lock keys.
     *
     * @returns
     * The lock keys.
     */
    protected setLockKeys(keys: (keyof DBType)[]): ("_id" | keyof DBType)[];
    getCollectionName(): string;
    getItemName(): string;
    /**
     * Executed during the initialization of the module.
     * The collection reference is set in this method.
     */
    init(): void;
    assertExternalQueryUnique(instance: DBType, transaction: FirestoreTransaction): Promise<DBType>;
    /**
     * Asserts the uniqueness of an instance in two steps:
     * - Executes `this.preUpsertProcessing`.
     * - Asserts uniqueness based on the internal filters.
     *
     * @param transaction - The transaction object.
     * @param instance - The document for which the uniqueness assertion will occur.
     */
    assertUniqueness(transaction: FirestoreTransaction, instance: DBType, request?: ExpressRequest): Promise<void>;
    /**
     * Runs the module's validator for the instance.
     *
     * @param instance - The object to be validated.
     *
     * @throws `ApiException` for bad implementation or invalid input.
     */
    validateImpl(instance: DBType): void;
    /**
     * Override this method to return a list of "where" queries that dictate uniqueness inside the collection.
     * Example return value: [{attribute1: item.attribute1, attribute2: item.attribute2}].
     *
     * @param item - The DB entry that will be used.
     */
    protected internalFilter(item: DBType): Clause_Where<DBType>[];
    /**
     * Override this method to customize the assertions that should be done before the insertion of the document to the DB.
     *
     * @param transaction - The transaction object.
     * @param dbInstance - The DB entry for which the uniqueness is being asserted.
     */
    protected preUpsertProcessing(transaction: FirestoreTransaction, dbInstance: DBType, request?: ExpressRequest): Promise<void>;
    /**
     * Override this method to provide actions or assertions to be executed before the deletion happens.
     *
     * Currently executed only before `deleteUnique()`.
     *
     * @param transaction - The transaction object
     * @param dbInstance - The DB entry that is going to be deleted.
     */
    protected assertDeletion(transaction: FirestoreTransaction, dbInstance: DBType, request?: ExpressRequest): Promise<void>;
    protected assertDeletion_Read(transaction: FirestoreTransaction, dbInstance: DBType, request?: ExpressRequest): Promise<() => void>;
    /**
     * A wrapper of the collections's `runInTransaction`.
     *
     * @param processor - The transaction's processor.
     *
     * @returns
     * A promise of the result of the `processor`.
     */
    runInTransaction<ReturnType>(processor: (transaction: FirestoreTransaction) => Promise<ReturnType>): Promise<ReturnType>;
    private deleteCollection;
    /**
     * Inserts the `instance` using the `transaction` object.
     *
     * @param transaction - The transaction object.
     * @param instance - The object to be inserted.
     * @param request - The request in order to possibly obtain more info.
     *
     * @returns
     * A promise of the document that was inserted.
     */
    createImpl_Read(transaction: FirestoreTransaction, instance: DBType, request?: ExpressRequest): Promise<() => DBType>;
    /**
     * Upserts the `instance` using a transaction, after validating it and asserting uniqueness.
     *
     * @param instance - The object to be upserted.
     * @param transaction - OPTIONAL transaction to perform the upsert operation on
     * @param request - The request in order to possibly obtain more info.
     *
     * @returns
     * A promise of the document that was upserted.
     */
    upsert(instance: UType, transaction?: FirestoreTransaction, request?: ExpressRequest): Promise<DBType>;
    upsert_Read(instance: UType, transaction: FirestoreTransaction, request?: ExpressRequest): Promise<() => DBType>;
    /**
     * Upserts a set of objects. Batching is used to circumvent firestore limitations on the number of objects.
     *
     * @param instances - The objects to be upserted.
     * @param request - The request in order to possibly obtain more info.
     *
     * @returns
     * A promise of an array of documents that were upserted.
     */
    upsertAll_Batched(instances: UType[], request?: ExpressRequest): Promise<DBType[]>;
    /**
     * Upserts the `dbInstances` using the `transaction` object.
     *
     * @param transaction - The transaction object.
     * @param instances - The instances to update.
     * @param request - The request in order to possibly obtain more info.
     *
     * @throws `BadImplementationException` when the instances are more than 500.
     *
     * @returns
     * A promise of the array of documents that were upserted.
     */
    upsertAll(instances: UType[], transaction?: FirestoreTransaction, request?: ExpressRequest): Promise<DBType[]>;
    protected upsertAllImpl_Read(instances: UType[], transaction: FirestoreTransaction, request?: ExpressRequest): Promise<(() => DBType)[]>;
    /**
     * Upserts the `dbInstance` using the `transaction` transaction object.
     *
     * @param transaction - The transaction object.
     * @param dbInstance - The object to be upserted.
     * @param request - The request in order to possibly obtain more info.
     *
     * @returns
     * A promise of the document that was upserted.
     */
    protected upsertImpl(transaction: FirestoreTransaction, dbInstance: DBType, request?: ExpressRequest): Promise<DBType>;
    protected upsertImpl_Read(transaction: FirestoreTransaction, dbInstance: DBType, request?: ExpressRequest): Promise<() => DBType>;
    /**
     * Deletes a unique document based on its `_id`. Uses a transaction, after deletion assertions occur.
     *
     * @param _id - The _id of the object to be deleted.
     * @param transaction
     * @param request - The request in order to possibly obtain more info.
     *
     * @throws `ApiException` when the document doesn't exist in the collection.
     *
     * @returns
     * A promise of the document that was deleted.
     */
    deleteUnique(_id: string, transaction?: FirestoreTransaction, request?: ExpressRequest): Promise<DBType>;
    deleteUnique_Read(_id: string, transaction: FirestoreTransaction, request?: ExpressRequest): Promise<() => Promise<DBType>>;
    /**
     * Uses the `transaction` to delete a unique document, querying with the `ourQuery`.
     *
     * @param transaction - The transaction object.
     * @param ourQuery - The query to be used for the deletion.
     * @param request - The request in order to possibly obtain more info.
     *
     * @returns
     * A promise of the document that was deleted.
     */
    private deleteImpl_Read;
    /**
     * Calls the `delete` method of the module's collection.
     *
     * @param query - The query to be executed for the deletion.
     * @param request - The request in order to possibly obtain more info.
     */
    delete(query: FirestoreQuery<DBType>, request?: ExpressRequest): Promise<DBType[]>;
    /**
     * Queries the database for a specific document in the module's collection.
     *
     * @param where - The where clause to be used for querying.
     * @param request - The request in order to possibly obtain more info.
     *
     * @throws `ApiException` if the document is not found.
     *
     * @returns
     * The DB document that was found.
     */
    queryUnique(where: Clause_Where<DBType>, request?: ExpressRequest): Promise<DBType>;
    /**
     * Executes the specified query on the module's collection.
     *
     * @param query - The query to be executed.
     * @param request - The request in order to possibly obtain more info.
     *
     * @returns
     * A promise of an array of documents.
     */
    query(query: FirestoreQuery<DBType>, request?: ExpressRequest): Promise<DBType[]>;
    /**
     * If propsToPatch is not set, we remove the lock keys from the caller's instance
     * before merging with the original dbInstance.
     * If propsToPatch is set, we also remove all of the instance's keys that
     * are not specified in propsToPatch.
     *
     * @param instance - The instance to be upserted.
     * @param propsToPatch - Properties to patch.
     * @param request - The request in order to possibly obtain more info.
     *
     * @returns
     * A promise of the patched document.
     */
    patch(instance: DBType, propsToPatch?: (keyof DBType)[], request?: ExpressRequest): Promise<DBType>;
    apiCreate(pathPart?: string): ServerApi_Create<DBType> | ServerApi<any> | undefined;
    apiQuery(pathPart?: string): ServerApi<any> | undefined;
    apiQueryUnique(pathPart?: string): ServerApi<any> | undefined;
    apiUpdate(pathPart?: string): ServerApi<any> | undefined;
    apiDelete(pathPart?: string): ServerApi<any> | undefined;
    /**
     * Override this method, to control which server api endpoints are created automatically.
     *
     * @param pathPart - The path part.
     *
     * @returns
     * An array of api endpoints.
     */
    apis(pathPart?: string): ServerApi<any>[];
}