@nu-art/firebase-backend 0.400.5

package/firestore-v3/DocWrapperV3.d.ts

@@ -0,0 +1,32 @@
+import { DBProto, UniqueId } from '@nu-art/ts-common';
+import { FirestoreType_DocumentReference } from '../firestore/types.js';
+import { Transaction } from 'firebase-admin/firestore';
+import { FirestoreCollectionV3 } from './FirestoreCollectionV3.js';
+import type { firestore as Fa } from 'firebase-admin';
+export type UpdateObject<Proto extends DBProto<any>> = {
+    _id: UniqueId;
+} & Fa.UpdateData<Proto['dbType']>;
+export declare class DocWrapperV3<Proto extends DBProto<any>> {
+    readonly ref: FirestoreType_DocumentReference<Proto['dbType']>;
+    readonly collection: FirestoreCollectionV3<Proto>;
+    data?: Proto['dbType'];
+    protected constructor(collection: FirestoreCollectionV3<Proto>, ref: FirestoreType_DocumentReference<Proto['dbType']>, data?: Proto['dbType']);
+    fromCache: () => Proto["dbType"] | undefined;
+    cleanCache: () => DocWrapperV3<Proto>;
+    private assertId;
+    get: (transaction?: Transaction) => Promise<Proto["dbType"] | undefined>;
+    prepareForCreate: (preDBItem: Proto["uiType"], transaction?: Transaction, upgrade?: boolean) => Promise<Proto["dbType"]>;
+    create: (preDBItem: Proto["uiType"], transaction?: Transaction) => Promise<Proto["dbType"]>;
+    prepareForSet: (updatedDBItem: Proto["dbType"], dbItem?: Proto["dbType"], transaction?: Transaction, upgrade?: boolean) => Promise<Proto["dbType"]>;
+    set: (item: Proto["uiType"] | Proto["dbType"], transaction?: Transaction) => Promise<Proto["dbType"]>;
+    private postWriteProcessing;
+    prepareForUpdate(updateData: UpdateObject<Proto['dbType']>, transaction?: Transaction): Promise<UpdateObject<Proto["dbType"]>>;
+    /**
+     * Recursively replaces any undefined or null fields in DB item with firestore.FieldValue.delete()
+     * @private
+     * @param updateData
+     */
+    private updateDeletedFields;
+    update: (updateData: UpdateObject<Proto["dbType"]>) => Promise<Proto["dbType"] | undefined>;
+    delete: (transaction?: Transaction) => Promise<Proto["dbType"] | undefined>;
+}

package/firestore-v3/DocWrapperV3.js

@@ -0,0 +1,148 @@
+import { _keys, currentTimeMillis, exists, MUSTNeverHappenException } from '@nu-art/ts-common';
+import { assertUniqueId } from './FirestoreCollectionV3.js';
+import { HttpCodes } from '@nu-art/ts-common/core/exceptions/http-codes';
+import { addDeletedToTransaction } from './consts.js';
+import admin from 'firebase-admin';
+const { FieldValue } = admin.firestore;
+export class DocWrapperV3 {
+    ref;
+    collection;
+    data;
+    constructor(collection, ref, data) {
+        this.collection = collection;
+        this.ref = ref;
+        this.data = data;
+    }
+    fromCache = () => {
+        return this.data;
+    };
+    cleanCache = () => {
+        delete this.data;
+        return this;
+    };
+    assertId(item) {
+        item._id = assertUniqueId(item, this.collection.uniqueKeys);
+        if (item._id !== this.ref.id)
+            throw new MUSTNeverHappenException(`Composed _id does not match doc ref id! \n expected: ${this.ref.id} \n actual: ${item._id} \n`);
+    }
+    get = async (transaction) => {
+        if (transaction)
+            return this.data ?? (this.data = (await transaction.get(this.ref)).data());
+        return this.data ?? (this.data = (await this.ref.get()).data());
+    };
+    prepareForCreate = async (preDBItem, transaction, upgrade = true) => {
+        const now = currentTimeMillis();
+        this.assertId(preDBItem);
+        preDBItem.__updated = preDBItem.__created = now;
+        if (upgrade) {
+            preDBItem._v = this.collection.getVersion();
+            await this.collection.hooks?.upgradeInstances([preDBItem]);
+        }
+        await this.collection.hooks?.preWriteProcessing?.(preDBItem, undefined, transaction);
+        this.collection.validateItem(preDBItem);
+        return preDBItem;
+    };
+    create = async (preDBItem, transaction) => {
+        const dbItem = await this.prepareForCreate(preDBItem);
+        if (transaction) {
+            transaction.create(this.ref, dbItem);
+            this.data = dbItem;
+        }
+        else
+            await this.ref.create(dbItem);
+        this.postWriteProcessing({ updated: dbItem }, 'create', transaction);
+        return dbItem;
+    };
+    prepareForSet = async (updatedDBItem, dbItem, transaction, upgrade = true) => {
+        if (!dbItem)
+            return this.prepareForCreate(updatedDBItem, transaction);
+        this.assertId(updatedDBItem);
+        updatedDBItem.__created = dbItem.__created;
+        this.collection.dbDef.lockKeys?.forEach(lockedKey => {
+            if (exists(dbItem[lockedKey]))
+                updatedDBItem[lockedKey] = dbItem[lockedKey];
+        });
+        updatedDBItem.__updated = currentTimeMillis();
+        if (this.collection.needsUpgrade(updatedDBItem._v)) {
+            await this.collection.hooks?.upgradeInstances([updatedDBItem]);
+        }
+        updatedDBItem._v = this.collection.getVersion();
+        await this.collection.hooks?.preWriteProcessing?.(updatedDBItem, dbItem, transaction);
+        this.collection.validateItem(updatedDBItem);
+        return updatedDBItem;
+    };
+    set = async (item, transaction) => {
+        if (!transaction)
+            return this.collection.runTransaction((transaction) => this.set(item, transaction));
+        const currDBItem = await this.get(transaction);
+        if ((currDBItem?.__updated || 0) > (item.__updated || currentTimeMillis()))
+            throw HttpCodes._4XX.ENTITY_IS_OUTDATED('Item is outdated', `${this.collection.collection.path}/${currDBItem?._id} is outdated`);
+        const newDBItem = await this.prepareForSet(item, currDBItem, transaction, false);
+        // Will always get here with a transaction!
+        transaction.set(this.ref, newDBItem);
+        this.data = currDBItem;
+        this.postWriteProcessing({ updated: newDBItem, before: currDBItem }, 'set', transaction);
+        return newDBItem;
+    };
+    postWriteProcessing(data, actionType, transaction) {
+        const toExecute = () => this.collection.hooks?.postWriteProcessing?.(data, actionType);
+        if (transaction)
+            // @ts-ignore
+            transaction.postTransaction(toExecute);
+        else
+            toExecute();
+    }
+    async prepareForUpdate(updateData, transaction) {
+        delete updateData.__created;
+        delete updateData._v;
+        updateData.__updated = currentTimeMillis();
+        // this.collection.dbDef.lockKeys?.forEach(lockedKey => {
+        // 	(updateData as Partial<Proto['dbType']>)[lockedKey] = undefined;
+        // });
+        this.updateDeletedFields(updateData);
+        await this.collection.validateUpdateData(updateData, transaction);
+        return updateData;
+    }
+    /**
+     * Recursively replaces any undefined or null fields in DB item with firestore.FieldValue.delete()
+     * @private
+     * @param updateData
+     */
+    updateDeletedFields(updateData) {
+        if (typeof updateData !== 'object' || updateData === null)
+            return;
+        _keys(updateData).forEach(_key => {
+            const _value = updateData[_key];
+            if (!exists(_value)) {
+                updateData[_key] = FieldValue.delete();
+            }
+            else {
+                this.updateDeletedFields(_value);
+            }
+        });
+    }
+    update = async (updateData) => {
+        updateData = await this.prepareForUpdate(updateData);
+        await this.ref.update(updateData);
+        const dbItem = await this.get();
+        this.postWriteProcessing({ updated: dbItem }, 'update');
+        return dbItem;
+    };
+    delete = async (transaction) => {
+        if (!transaction)
+            return this.collection.runTransaction(transaction => this.delete(transaction));
+        const dbItem = await this.get(transaction);
+        if (!dbItem)
+            return;
+        addDeletedToTransaction(transaction, {
+            dbKey: this.collection.dbDef.entityName,
+            ids: [dbItem._id]
+        });
+        await this.collection.hooks?.canDeleteItems([dbItem], transaction);
+        // Will always get here with a transaction!
+        transaction.delete(this.ref);
+        this.cleanCache();
+        this.postWriteProcessing({ deleted: dbItem }, 'delete', transaction);
+        return dbItem;
+    };
+}

package/firestore-v3/FirestoreCollectionV3.d.ts

@@ -0,0 +1,154 @@
+import { CustomException, DBDef_V3, DBProto, InvalidResult, Logger, UniqueId } from '@nu-art/ts-common';
+import { FirestoreType_Collection, FirestoreType_DocumentReference } from '../firestore/types.js';
+import { Clause_Where, FirestoreQuery, MultiWriteOperation } from '@nu-art/firebase-shared';
+import { FirestoreWrapperBEV3 } from './FirestoreWrapperBEV3.js';
+import { Transaction } from 'firebase-admin/firestore';
+import { firestore } from 'firebase-admin';
+import { DocWrapperV3, UpdateObject } from './DocWrapperV3.js';
+import UpdateData = firestore.UpdateData;
+export type PostWriteProcessingData<Proto extends DBProto<any>> = {
+    before?: Proto['dbType'] | Proto['dbType'][];
+    updated?: Proto['dbType'] | Proto['dbType'][];
+    deleted?: Proto['dbType'] | Proto['dbType'][] | null;
+};
+export type CollectionActionType = 'create' | 'set' | 'update' | 'delete';
+export type FirestoreCollectionHooks<Proto extends DBProto<any>> = {
+    canDeleteItems: (dbItems: Proto['dbType'][], transaction?: Transaction) => Promise<void>;
+    preWriteProcessing?: (dbInstance: Proto['dbType'], originalDbInstance?: Proto['dbType'], transaction?: Transaction) => Promise<void>;
+    manipulateQuery?: (query: FirestoreQuery<Proto['dbType']>) => FirestoreQuery<Proto['dbType']>;
+    postWriteProcessing?: (data: PostWriteProcessingData<Proto>, actionType: CollectionActionType, transaction?: Transaction) => Promise<void>;
+    upgradeInstances: (instances: Proto['dbType'][]) => Promise<any>;
+};
+export type MultiWriteItem<Op extends MultiWriteOperation, Proto extends DBProto<any>> = Op extends 'delete' ? undefined : Op extends 'update' ? UpdateObject<Proto['dbType']> : Proto;
+type MultiWriteType = 'bulk' | 'batch';
+/**
+ * # <ins>FirestoreBulkException</ins>
+ * @category Exceptions
+ */
+export declare class FirestoreBulkException extends CustomException {
+    causes?: Error[];
+    constructor(causes?: Error[]);
+}
+/**
+ * FirestoreCollection is a class for handling Firestore collections.
+ */
+export declare class FirestoreCollectionV3<Proto extends DBProto<any>> extends Logger {
+    readonly wrapper: FirestoreWrapperBEV3;
+    readonly collection: FirestoreType_Collection;
+    readonly dbDef: DBDef_V3<Proto>;
+    readonly uniqueKeys: Proto['uniqueKeys'][] | string[];
+    private readonly validator;
+    readonly hooks?: FirestoreCollectionHooks<Proto['dbType']>;
+    constructor(wrapper: FirestoreWrapperBEV3, _dbDef: DBDef_V3<Proto>, hooks?: FirestoreCollectionHooks<Proto['dbType']>);
+    doc: Readonly<{
+        _: (ref: FirestoreType_DocumentReference<Proto["dbType"]>, data?: Proto["dbType"]) => DocWrapperV3<Proto>;
+        unique: (id: Proto["uniqueParam"]) => DocWrapperV3<Proto>;
+        item: (item: Proto["uiType"]) => DocWrapperV3<Proto>;
+        all: (_ids: (Proto["uniqueParam"])[]) => DocWrapperV3<Proto>[];
+        allItems: (preDBItems: Proto["uiType"][]) => DocWrapperV3<Proto>[];
+        query: (query: FirestoreQuery<Proto["dbType"]>, transaction?: Transaction) => Promise<DocWrapperV3<Proto>[]>;
+        unManipulatedQuery: (query: FirestoreQuery<Proto["dbType"]>, transaction?: Transaction) => Promise<DocWrapperV3<Proto>[]>;
+    }>;
+    private getAll;
+    private _customQuery;
+    query: Readonly<{
+        unique: (_id: Proto["uniqueParam"], transaction?: Transaction) => Promise<Proto["dbType"] | undefined>;
+        uniqueAssert: (_id: Proto["uniqueParam"], transaction?: Transaction) => Promise<Proto["dbType"]>;
+        uniqueWhere: (where: Clause_Where<Proto["dbType"]>, transaction?: Transaction) => Promise<Proto["dbType"]>;
+        uniqueCustom: (query: FirestoreQuery<Proto["dbType"]>, transaction?: Transaction) => Promise<Proto["dbType"]>;
+        all: (_ids: (Proto["uniqueParam"])[], transaction?: Transaction) => Promise<(Proto["dbType"] | undefined)[]>;
+        custom: (query: FirestoreQuery<Proto["dbType"]>, transaction?: Transaction) => Promise<Proto["dbType"][]>;
+        where: (where: Clause_Where<Proto["dbType"]>, transaction?: Transaction) => Promise<Proto["dbType"][]>;
+        unManipulatedQuery: (query: FirestoreQuery<Proto["dbType"]>, transaction?: Transaction) => Promise<Proto["dbType"][]>;
+    }>;
+    uniqueGetOrCreate: (where: Clause_Where<Proto["dbType"]>, toCreate: (transaction?: Transaction) => Promise<Proto["uiType"]>, transaction?: Transaction) => Promise<Proto["dbType"] | Proto["uiType"]>;
+    protected _createAll: (preDBItems: Proto["uiType"][], transaction?: Transaction, multiWriteType?: MultiWriteType) => Promise<Proto["dbType"][]>;
+    create: Readonly<{
+        item: (preDBItem: Proto["uiType"], transaction?: Transaction) => Promise<Proto["dbType"]>;
+        all: (preDBItems: Proto["uiType"][], transaction?: Transaction, multiWriteType?: MultiWriteType) => Promise<Proto["dbType"][]>;
+    }>;
+    private _setAll;
+    set: Readonly<{
+        item: (preDBItem: Proto["uiType"], transaction?: Transaction) => Promise<Proto["dbType"]>;
+        all: (items: (Proto["uiType"] | Proto["dbType"])[], transaction?: Transaction) => Promise<Awaited<Proto["dbType"]>[]>;
+        /**
+         * Multi is a non atomic operation
+         */
+        multi: (items: (Proto["uiType"] | Proto["dbType"])[], transaction?: Transaction, multiWriteType?: MultiWriteType) => Promise<Awaited<Proto["dbType"]>[]>;
+    }>;
+    private upgradeInstances;
+    protected _updateAll: (updateData: UpdateObject<Proto["dbType"]>[], multiWriteType?: MultiWriteType) => Promise<Proto["dbType"][]>;
+    validateUpdateData(updateData: UpdateData<Proto['dbType']>, transaction?: Transaction): Promise<void>;
+    protected _deleteQuery: (query: FirestoreQuery<Proto["dbType"]>, transaction?: Transaction, multiWriteType?: MultiWriteType) => Promise<NonNullable<Proto["dbType"]>[]>;
+    protected _deleteUnManipulatedQuery: (query: FirestoreQuery<Proto["dbType"]>, transaction?: Transaction, multiWriteType?: MultiWriteType) => Promise<NonNullable<Proto["dbType"]>[]>;
+    protected _deleteAll: (docsToBeDeleted: DocWrapperV3<Proto>[], transaction?: Transaction, multiWriteType?: MultiWriteType) => Promise<Proto["dbType"][]>;
+    private deleteCollection;
+    delete: Readonly<{
+        unique: (id: Proto["uniqueParam"], transaction?: Transaction) => Promise<Proto["dbType"] | undefined>;
+        item: (item: Proto["uiType"], transaction?: Transaction) => Promise<Proto["dbType"] | undefined>;
+        all: (ids: (Proto["uniqueParam"])[], transaction?: Transaction) => Promise<Proto["dbType"][]>;
+        allDocs: (docs: DocWrapperV3<Proto>[], transaction?: Transaction) => Promise<Proto["dbType"][]>;
+        allItems: (items: Proto["uiType"][], transaction?: Transaction) => Promise<Proto["dbType"][]>;
+        query: (query: FirestoreQuery<Proto["dbType"]>, transaction?: Transaction) => Promise<Proto["dbType"][]>;
+        unManipulatedQuery: (query: FirestoreQuery<Proto["dbType"]>, transaction?: Transaction) => Promise<Proto["dbType"][]>;
+        where: (where: Clause_Where<Proto["dbType"]>, transaction?: Transaction) => Promise<Proto["dbType"][]>;
+        /**
+         * Multi is a non atomic operation - doesn't use transactions. Use 'all' variants for transaction.
+         */
+        multi: {
+            all: (ids: UniqueId[], multiWriteType?: MultiWriteType) => Promise<Proto["dbType"][]>;
+            items: (items: Proto["uiType"][], multiWriteType?: MultiWriteType) => Promise<Proto["dbType"][]>;
+            allDocs: (docs: DocWrapperV3<Proto>[], multiWriteType?: MultiWriteType) => Promise<Proto["dbType"][]>;
+            query: (query: FirestoreQuery<Proto["dbType"]>, multiWriteType?: MultiWriteType) => Promise<NonNullable<Proto["dbType"]>[]>;
+        };
+        yes: {
+            iam: {
+                sure: {
+                    iwant: {
+                        todelete: {
+                            the: {
+                                collection: {
+                                    delete: () => Promise<void>;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    }>;
+    /**
+     * @param writer Type of BulkWriter - can be Bulk writer or Batch writer
+     * @param doc
+     * @param operation create/update/set/delete
+     * @param item - mandatory for everything but delete
+     */
+    private addToMultiWrite;
+    private multiWrite;
+    private bulkWrite;
+    /**
+     * @param docs docs to write to
+     * @param operation create/update/set/delete
+     * @param items mandatory for everything but delete
+     */
+    private batchWrite;
+    /**
+     * A firestore transaction is run globally on the firestore project and not specifically on any collection, locking specific documents in the project.
+     * @param processor
+     * @param transaction A transaction that was provided to be used
+     */
+    runTransaction: <ReturnType>(processor: (transaction: Transaction) => Promise<ReturnType>, transaction?: Transaction) => Promise<ReturnType>;
+    runTransactionInChunks: <T = any, R = any>(items: T[], processor: (chunk: typeof items, transaction: Transaction) => Promise<R[]>, chunkSize?: number) => Promise<R[]>;
+    getVersion: () => any;
+    needsUpgrade: (version?: string) => boolean;
+    validateItem(dbItem: Proto['dbType']): void;
+    protected onValidationError(instance: Proto['dbType'], results: InvalidResult<Proto['dbType']>): void;
+    private assertNoDuplicatedIds;
+    composeDbObjectUniqueId: (item: Proto["uiType"]) => string;
+}
+/**
+ * If the collection has unique keys, assert they exist, and use them to generate the _id.
+ * In the case an _id already exists, verify it is not different from the uniqueKeys-generated _id.
+ */
+export declare const assertUniqueId: <Proto extends DBProto<any>>(item: Proto["dbType"], keys: Proto["uniqueKeys"]) => string;
+export {};