@nu-art/firebase-backend 0.400.5

package/firestore-v3/FirestoreCollectionV3.js

@@ -0,0 +1,470 @@
+/*
+ * Firebase is a simpler Typescript wrapper to all of firebase services.
+ *
+ * Copyright (C) 2020 Adam van der Kruk aka TacB0sS
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { __stringify, _keys, ApiException, BadImplementationException, batchActionParallel, compare, Const_UniqueKeys, CustomException, DB_Object_validator, dbIdLength, dbObjectToId, deepClone, DefaultDBVersion, Exception, exists, filterDuplicates, filterInstances, generateHex, keepPartialObject, Logger, MUSTNeverHappenException, StaticLogger, tsValidateResult, tsValidateUniqueId, ValidationException } from '@nu-art/ts-common';
+import { FirestoreInterfaceV3 } from './FirestoreInterfaceV3.js';
+import { DocWrapperV3 } from './DocWrapperV3.js';
+import { composeDbObjectUniqueId } from '@nu-art/firebase-shared';
+import { _EmptyQuery, maxBatch } from '@nu-art/firebase-shared';
+import { HttpCodes } from '@nu-art/ts-common/core/exceptions/http-codes';
+import { addDeletedToTransaction } from './consts.js';
+const defaultMultiWriteType = 'batch';
+/**
+ * # <ins>FirestoreBulkException</ins>
+ * @category Exceptions
+ */
+export class FirestoreBulkException extends CustomException {
+    causes;
+    constructor(causes) {
+        super(FirestoreBulkException, __stringify(causes?.map(_err => _err.message)));
+        this.causes = causes;
+    }
+}
+/**
+ * If one of the validators is a function, returns an array of functions.
+ * If both validators are objects, returns a merged object.
+ */
+const getDbDefValidator = (dbDef) => {
+    if (typeof dbDef.modifiablePropsValidator === 'object' && typeof dbDef.generatedPropsValidator === 'object')
+        return { ...dbDef.generatedPropsValidator, ...dbDef.modifiablePropsValidator, ...DB_Object_validator };
+    if (typeof dbDef.modifiablePropsValidator === 'function' && typeof dbDef.generatedPropsValidator === 'function')
+        return [dbDef.modifiablePropsValidator, dbDef.generatedPropsValidator];
+    if (typeof dbDef.modifiablePropsValidator === 'function')
+        return [dbDef.modifiablePropsValidator, (instance) => {
+                const partialInstance = keepPartialObject(instance, _keys(dbDef.generatedPropsValidator));
+                return tsValidateResult(partialInstance, dbDef.generatedPropsValidator);
+            }];
+    return [dbDef.generatedPropsValidator, (instance) => {
+            return tsValidateResult(keepPartialObject(instance, _keys(dbDef.modifiablePropsValidator)), dbDef.modifiablePropsValidator);
+        }];
+};
+/**
+ * FirestoreCollection is a class for handling Firestore collections.
+ */
+export class FirestoreCollectionV3 extends Logger {
+    wrapper;
+    collection;
+    dbDef;
+    uniqueKeys;
+    validator;
+    hooks;
+    constructor(wrapper, _dbDef, hooks) {
+        super();
+        this.wrapper = wrapper;
+        if (!/[a-z-]{3,}/.test(_dbDef.backend.name))
+            StaticLogger.logWarning('Please follow name pattern for collections /[a-z-]{3,}/');
+        this.collection = wrapper.firestore.collection(_dbDef.backend.name);
+        this.dbDef = _dbDef;
+        this.uniqueKeys = this.dbDef.uniqueKeys || Const_UniqueKeys;
+        this.validator = getDbDefValidator(_dbDef);
+        this.hooks = hooks;
+    }
+    // ############################## DocWrapper ##############################
+    doc = Object.freeze({
+        _: (ref, data) => {
+            if (tsValidateResult(ref.id, tsValidateUniqueId))
+                throw new MUSTNeverHappenException(`Tackled a docRef with id that is an invalid UniqueId: '${ref.id}'`);
+            // @ts-ignore
+            return new DocWrapperV3(this, ref, data);
+        },
+        unique: (id) => {
+            if (!id)
+                throw new MUSTNeverHappenException('Did not receive an _id at doc.unique!');
+            if (typeof id !== 'string')
+                id = assertUniqueId(id, this.uniqueKeys);
+            const doc = this.wrapper.firestore.doc(`${this.collection.path}/${id}`);
+            return this.doc._(doc);
+        },
+        item: (item) => {
+            item._id = assertUniqueId(item, this.uniqueKeys);
+            return this.doc.unique(item._id);
+        },
+        all: (_ids) => _ids.map(this.doc.unique),
+        allItems: (preDBItems) => {
+            // At this point all preDB MUST have ids
+            return preDBItems.map(preDBItem => this.doc.item(preDBItem));
+        },
+        query: async (query, transaction) => {
+            return (await this._customQuery(query, true, transaction)).map(_snapshot => this.doc._(_snapshot.ref, _snapshot.data()));
+        },
+        unManipulatedQuery: async (query, transaction) => {
+            return (await this._customQuery(query, false, transaction)).map(_snapshot => this.doc._(_snapshot.ref, _snapshot.data()));
+        },
+    });
+    // ############################## Query ##############################
+    getAll = async (docs, transaction) => {
+        if (docs.length === 0)
+            return [];
+        return (await (transaction ?? this.wrapper.firestore).getAll(...docs.map(_doc => _doc.ref))).map(_snapshot => _snapshot.data());
+    };
+    _customQuery = async (tsQuery, canManipulateQuery, transaction) => {
+        if (canManipulateQuery)
+            tsQuery = this.hooks?.manipulateQuery?.(deepClone(tsQuery)) ?? tsQuery;
+        const firestoreQuery = FirestoreInterfaceV3.buildQuery(this, tsQuery);
+        if (transaction)
+            return (await transaction.get(firestoreQuery)).docs;
+        return (await firestoreQuery.get()).docs;
+    };
+    query = Object.freeze({
+        unique: async (_id, transaction) => await this.doc.unique(_id).get(transaction),
+        uniqueAssert: async (_id, transaction) => {
+            const resultItem = await this.query.unique(_id, transaction);
+            if (!resultItem)
+                throw new ApiException(404, `Could not find ${this.dbDef.entityName} with _id: ${__stringify(_id)}`);
+            return resultItem;
+        },
+        uniqueWhere: async (where, transaction) => this.query.uniqueCustom({ where }, transaction),
+        uniqueCustom: async (query, transaction) => {
+            const thisShouldBeOnlyOne = await this.query.custom(query, transaction);
+            if (thisShouldBeOnlyOne.length === 0)
+                throw new ApiException(404, `Could not find ${this.dbDef.entityName} with unique query: ${JSON.stringify(query)}`);
+            if (thisShouldBeOnlyOne.length > 1)
+                throw new BadImplementationException(`Too many results (${thisShouldBeOnlyOne.length}) in collection (${this.dbDef.dbKey}) for query: ${__stringify(query)}`);
+            return thisShouldBeOnlyOne[0];
+        },
+        all: async (_ids, transaction) => await this.getAll(this.doc.all(_ids), transaction),
+        custom: async (query, transaction) => {
+            return (await this._customQuery(query, true, transaction)).map(snapshot => snapshot.data());
+        },
+        where: async (where, transaction) => {
+            return this.query.custom({ where }, transaction);
+        },
+        unManipulatedQuery: async (query, transaction) => {
+            return (await this._customQuery(query, false, transaction)).map(snapshot => snapshot.data());
+        },
+    });
+    uniqueGetOrCreate = async (where, toCreate, transaction) => {
+        try {
+            return await this.query.uniqueWhere(where, transaction);
+        }
+        catch (e) {
+            return toCreate(transaction);
+        }
+    };
+    // ############################## Create ##############################
+    _createAll = async (preDBItems, transaction, multiWriteType = defaultMultiWriteType) => {
+        if (preDBItems.length === 1)
+            return [await this.create.item(preDBItems[0], transaction)];
+        const docs = this.doc.allItems(preDBItems);
+        const dbItems = await Promise.all(docs.map((doc, i) => doc.prepareForCreate(preDBItems[i], transaction)));
+        this.assertNoDuplicatedIds(dbItems, 'create.all');
+        if (transaction)
+            docs.forEach((doc, i) => transaction.create(doc.ref, dbItems[i]));
+        else
+            await this.multiWrite(multiWriteType, docs, 'create', dbItems);
+        await this.hooks?.postWriteProcessing?.({ updated: dbItems }, 'create');
+        return dbItems;
+    };
+    create = Object.freeze({
+        item: async (preDBItem, transaction) => await this.doc.item(preDBItem)
+            .create(preDBItem, transaction),
+        all: this._createAll,
+    });
+    // ############################## Set ##############################
+    _setAll = async (items, transaction, multiWriteType = defaultMultiWriteType, performUpgrade = true) => {
+        //Get all items
+        const docs = this.doc.allItems(items);
+        const dbItems = await this.getAll(docs);
+        //Prepare all items
+        const preparedItems = await Promise.all(dbItems.map(async (_dbItem, i) => {
+            return !exists(_dbItem)
+                ? await docs[i].prepareForCreate(items[i], transaction, performUpgrade)
+                : await docs[i].prepareForSet(items[i], _dbItem, transaction, performUpgrade);
+        }));
+        this.assertNoDuplicatedIds(preparedItems, 'set.all');
+        //Write all items
+        if (transaction)
+            // here we do not call doc.set because we have performed all the preparation for the dbitems as a group of items before this call
+            docs.map((doc, i) => transaction.set(doc.ref, preparedItems[i]));
+        else
+            await this.multiWrite(multiWriteType, docs, 'set', preparedItems);
+        //postWriteProcessing if provided
+        if (preparedItems.length) //Only call postWriteProcessing if we actually set items
+            await this.hooks?.postWriteProcessing?.({ before: dbItems, updated: preparedItems }, 'set');
+        return preparedItems;
+    };
+    set = Object.freeze({
+        item: async (preDBItem, transaction) => {
+            // We've noticed that we call preWriteProcessing twice on create.
+            // if(!preDBItem._id)
+            // 	await this.hooks?.preWriteProcessing?.(preDBItem, undefined, transaction);
+            return await this.doc.item(preDBItem).set(preDBItem, transaction);
+        },
+        all: (items, transaction) => {
+            if (transaction)
+                return this._setAll(items, transaction);
+            return this.runTransactionInChunks(items, (chunk, transaction) => this._setAll(chunk, transaction));
+        },
+        /**
+         * Multi is a non atomic operation
+         */
+        multi: (items, transaction, multiWriteType = defaultMultiWriteType) => {
+            return this._setAll(items, transaction, multiWriteType);
+        },
+    });
+    // @ts-ignore
+    upgradeInstances = (items) => {
+        return this._setAll(items, undefined, defaultMultiWriteType, false);
+    };
+    // ############################## Update ##############################
+    _updateAll = async (updateData, multiWriteType = defaultMultiWriteType) => {
+        const docs = this.doc.all(updateData.map(_data => _data._id));
+        const toUpdate = await Promise.all(docs.map(async (_doc, i) => await _doc.prepareForUpdate(updateData[i])));
+        await this.multiWrite(multiWriteType, docs, 'update', toUpdate);
+        const dbItems = await this.getAll(docs);
+        await this.hooks?.postWriteProcessing?.({ updated: dbItems }, 'update');
+        return dbItems;
+    };
+    async validateUpdateData(updateData, transaction) {
+    }
+    // update = Object.freeze({
+    // 	item: (updateData: UpdateObject<Proto['dbType']>) => this.doc.unique(updateData._id).update(updateData),
+    // 	all: this._updateAll,
+    // });
+    // ############################## Delete ##############################
+    _deleteQuery = async (query, transaction, multiWriteType = defaultMultiWriteType) => {
+        if (!exists(query) || compare(query, _EmptyQuery))
+            throw new MUSTNeverHappenException('An empty query was passed to delete.query!');
+        const docsToBeDeleted = await this.doc.query(query, transaction);
+        // Because we query for docs, these docs and their data must exist in Firestore.
+        const itemsToReturn = docsToBeDeleted.map(doc => doc.data); // Data must exist here.
+        await this._deleteAll(docsToBeDeleted, transaction, multiWriteType);
+        return itemsToReturn;
+    };
+    _deleteUnManipulatedQuery = async (query, transaction, multiWriteType = defaultMultiWriteType) => {
+        if (!exists(query) || compare(query, _EmptyQuery))
+            throw new MUSTNeverHappenException('An empty query was passed to delete.query!');
+        const docsToBeDeleted = await this.doc.unManipulatedQuery(query, transaction);
+        // Because we query for docs, these docs and their data must exist in Firestore.
+        const itemsToReturn = docsToBeDeleted.map(doc => doc.data); // Data must exist here.
+        await this._deleteAll(docsToBeDeleted, transaction, multiWriteType);
+        return itemsToReturn;
+    };
+    _deleteAll = async (docsToBeDeleted, transaction, multiWriteType = defaultMultiWriteType) => {
+        const dbItems = filterInstances(await this.getAll(docsToBeDeleted, transaction));
+        const itemsToCheck = dbItems.filter((item, index) => docsToBeDeleted[index].ref.id == item._id);
+        addDeletedToTransaction(transaction, {
+            dbKey: this.dbDef.dbKey,
+            ids: dbItems.map(dbObjectToId)
+        });
+        await this.hooks?.canDeleteItems(itemsToCheck, transaction);
+        if (transaction)
+            // here we do not call doc.delete because we have performed all the delete preparation as a group of items before this call
+            docsToBeDeleted.map(async (doc) => transaction.delete(doc.ref));
+        else
+            await this.multiWrite(multiWriteType, docsToBeDeleted, 'delete');
+        await this.hooks?.postWriteProcessing?.({ deleted: dbItems }, 'delete', transaction);
+        return dbItems;
+    };
+    deleteCollection = async () => {
+        const refs = await this.collection.listDocuments();
+        const bulk = this.wrapper.firestore.bulkWriter();
+        refs.forEach(_ref => bulk.delete(_ref));
+        // deleted: null means that the whole collection has been deleted
+        await this.hooks?.postWriteProcessing?.({ deleted: null }, 'delete');
+        await bulk.close();
+    };
+    delete = Object.freeze({
+        unique: async (id, transaction) => await this.doc.unique(id).delete(transaction),
+        item: async (item, transaction) => await this.doc.item(item).delete(transaction),
+        all: async (ids, transaction) => {
+            if (!transaction)
+                return this.runTransactionInChunks(ids, (chunk, t) => this.delete.all(chunk, t));
+            return this._deleteAll(ids.map(id => this.doc.unique(id)), transaction);
+        },
+        allDocs: async (docs, transaction) => {
+            if (!transaction)
+                return this.runTransactionInChunks(docs, (chunk, t) => this.delete.allDocs(chunk, t));
+            return await this._deleteAll(docs, transaction);
+        },
+        allItems: async (items, transaction) => {
+            if (!transaction)
+                return this.runTransactionInChunks(items, (chunk, t) => this.delete.allItems(chunk, t));
+            return await this._deleteAll(items.map(_item => this.doc.item(_item)), transaction);
+        },
+        query: async (query, transaction) => {
+            if (!transaction) {
+                //query all docs and then delete in chunks
+                if (!exists(query) || compare(query, _EmptyQuery))
+                    throw new MUSTNeverHappenException('An empty query was passed to delete.query!');
+                const docs = await this.doc.query(query, transaction);
+                const items = docs.map(doc => doc.data); // Data must exist here.
+                await this.runTransactionInChunks(docs, (chunk, t) => this._deleteAll(chunk, t));
+                return items;
+            }
+            return await this._deleteQuery(query, transaction);
+        },
+        unManipulatedQuery: async (query, transaction) => {
+            if (!transaction) {
+                //query all docs and then delete in chunks
+                if (!exists(query) || compare(query, _EmptyQuery))
+                    throw new MUSTNeverHappenException('An empty query was passed to delete.query!');
+                const docs = await this.doc.unManipulatedQuery(query, transaction);
+                const items = docs.map(doc => doc.data); // Data must exist here.
+                await this.runTransactionInChunks(docs, (chunk, t) => this._deleteAll(chunk, t));
+                return items;
+            }
+            return await this._deleteUnManipulatedQuery(query, transaction);
+        },
+        where: async (where, transaction) => {
+            return this.delete.query({ where }, transaction);
+        },
+        /**
+         * Multi is a non atomic operation - doesn't use transactions. Use 'all' variants for transaction.
+         */
+        multi: {
+            all: async (ids, multiWriteType = defaultMultiWriteType) => await this._deleteAll(ids.map(id => this.doc.unique(id)), undefined, multiWriteType),
+            items: async (items, multiWriteType = defaultMultiWriteType) => await this._deleteAll(items.map(_item => this.doc.item(_item)), undefined, multiWriteType),
+            allDocs: async (docs, multiWriteType = defaultMultiWriteType) => await this._deleteAll(docs, undefined, multiWriteType),
+            query: async (query, multiWriteType = defaultMultiWriteType) => await this._deleteQuery(query, undefined, multiWriteType)
+        },
+        yes: { iam: { sure: { iwant: { todelete: { the: { collection: { delete: this.deleteCollection } } } } } } }
+    });
+    // ############################## Multi Write ##############################
+    /**
+     * @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
+     */
+    addToMultiWrite = (writer, doc, operation, item) => {
+        switch (operation) {
+            case 'create':
+                writer.create(doc.ref, item);
+                break;
+            case 'set':
+                // @ts-ignore
+                writer.set(doc.ref, item);
+                break;
+            case 'update':
+                // @ts-ignore
+                writer.update(doc.ref, item);
+                break;
+            case 'delete':
+                writer.delete(doc.ref);
+                break;
+        }
+        return item;
+    };
+    multiWrite = async (type, docs, operation, items) => {
+        if (type === 'bulk')
+            return this.bulkWrite(docs, operation, items);
+        if (type === 'batch')
+            return this.batchWrite(docs, operation, items);
+        throw new Exception(`Unknown type passed to multiWrite: ${type}`);
+    };
+    bulkWrite = async (docs, operation, items) => {
+        const bulk = this.wrapper.firestore.bulkWriter();
+        const errors = [];
+        bulk.onWriteError(error => {
+            errors.push(error);
+            return false;
+        });
+        docs.forEach((doc, index) => this.addToMultiWrite(bulk, doc, operation, items?.[index]));
+        await bulk.close();
+        if (errors.length)
+            throw new FirestoreBulkException(errors);
+    };
+    /**
+     * @param docs docs to write to
+     * @param operation create/update/set/delete
+     * @param items mandatory for everything but delete
+     */
+    batchWrite = async (docs, operation, items) => {
+        for (let batchIndex = 0; batchIndex < docs.length; batchIndex += maxBatch) {
+            const batch = this.wrapper.firestore.batch();
+            const chunk = docs.slice(batchIndex, batchIndex + maxBatch);
+            chunk.map((_doc, index) => this.addToMultiWrite(batch, _doc, operation, items?.[batchIndex + index]));
+            await batch.commit();
+        }
+    };
+    // ############################## General ##############################
+    /**
+     * 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 = async (processor, transaction) => {
+        return this.wrapper.runTransaction(processor, transaction);
+    };
+    runTransactionInChunks = async (items, processor, chunkSize = maxBatch) => {
+        return batchActionParallel(items, chunkSize, (chunk) => this.runTransaction(t => processor(chunk, t)));
+    };
+    getVersion = () => {
+        return this.dbDef.versions?.[0] || DefaultDBVersion;
+    };
+    needsUpgrade = (version) => {
+        const versions = this.dbDef.versions || [DefaultDBVersion];
+        if (!version)
+            return false;
+        const index = versions.indexOf(version);
+        if (index === -1)
+            throw HttpCodes._4XX.BAD_REQUEST('Invalid Object Version', `Provided item with version(${version}) which doesn't exist for collection '${this.dbDef.dbKey} (${__stringify(this.dbDef.versions)})' `);
+        return index !== 0;
+    };
+    validateItem(dbItem) {
+        const results = tsValidateResult(dbItem, this.validator);
+        if (results) {
+            this.onValidationError(dbItem, results);
+        }
+    }
+    onValidationError(instance, results) {
+        StaticLogger.logError(`error validating ${this.dbDef.entityName}:`, instance, 'With Error: ', results);
+        // console.error(`error validating ${this.dbDef.entityName}:`, instance, 'With Error: ', results);
+        // const errorBody = {type: 'bad-input', body: {result: results, input: instance}};
+        const validationException = new ValidationException(`error validating ${this.dbDef.entityName}`, instance, results);
+        throw new ApiException(HttpCodes._4XX.FAILED_VALIDATION.code, `error validating ${this.dbDef.entityName}`).setErrorBody(validationException);
+    }
+    assertNoDuplicatedIds(items, originFunctionName) {
+        if (filterDuplicates(items, dbObjectToId).length === items.length)
+            return;
+        const idCountMap = items.reduce((countMap, item) => {
+            // Count the number of appearances of each _id
+            countMap[item._id] = !exists(countMap[item._id]) ? 1 : 1 + countMap[item._id];
+            return countMap;
+        }, {});
+        // DEBUG - print the duplicate _ids
+        // _keys(idCountMap).forEach(key => {
+        // 	if (idCountMap[key] > 1)
+        // 		this.logWarning(`${idCountMap[key]} times ${key}`);
+        // });
+        // Throw exception if an _id appears more than once
+        _keys(idCountMap).forEach(key => {
+            if (idCountMap[key] === 1)
+                delete idCountMap[key];
+        });
+        throw new BadImplementationException(`${originFunctionName} received the same _id twice: ${__stringify(idCountMap, true)}`);
+    }
+    composeDbObjectUniqueId = (item) => {
+        return composeDbObjectUniqueId(item, this.uniqueKeys);
+    };
+}
+/**
+ * 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 const assertUniqueId = (item, keys) => {
+    // If there are no specific uniqueKeys, generate a random _id.
+    if (compare(keys, Const_UniqueKeys))
+        return item._id ?? generateHex(dbIdLength);
+    const _id = composeDbObjectUniqueId(item, keys);
+    // If the item has an _id, and it matches the uniqueKeys-generated _id, all is well.
+    // If the uniqueKeys-generated _id doesn't match the existing _id, this means someone had changed the uniqueKeys or _id which must never happen.
+    if (exists(item._id) && _id !== item._id)
+        throw new MUSTNeverHappenException(`When checking the existing _id, it did not match the _id composed from the unique keys! \n expected: ${_id} \n actual: ${item._id}`);
+    return _id;
+};

package/firestore-v3/FirestoreInterfaceV3.d.ts

@@ -0,0 +1,10 @@
+import { FirestoreQuery } from '@nu-art/firebase-shared';
+import { FirestoreType_DocumentSnapshot } from '../firestore/types.js';
+import { FirestoreCollectionV3 } from './FirestoreCollectionV3.js';
+import { DBProto } from '@nu-art/ts-common';
+import { Query } from 'firebase-admin/firestore';
+export declare class FirestoreInterfaceV3 {
+    static buildQuery<Proto extends DBProto<any>>(collection: FirestoreCollectionV3<Proto>, query?: FirestoreQuery<Proto['dbType']>): Query<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
+    private static isQueryObject;
+    static assertUniqueDocument(results: FirestoreType_DocumentSnapshot[], query: FirestoreQuery<any>, collectionName: string): (FirestoreType_DocumentSnapshot | undefined);
+}

package/firestore-v3/FirestoreInterfaceV3.js

@@ -0,0 +1,107 @@
+/*
+ * Firebase is a simpler Typescript wrapper to all of firebase services.
+ *
+ * Copyright (C) 2020 Adam van der Kruk aka TacB0sS
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ComparatorMap } from '@nu-art/firebase-shared';
+import { __stringify, BadImplementationException, ImplementationMissingException, StaticLogger } from '@nu-art/ts-common';
+export class FirestoreInterfaceV3 {
+    static buildQuery(collection, query) {
+        try {
+            let myQuery = collection.collection;
+            if (query && query.select)
+                myQuery = myQuery.select ? myQuery.select(...query.select) : myQuery;
+            if (query && query.where) {
+                const whereClause = query.where;
+                myQuery = Object.keys(whereClause).reduce((_query, _whereField) => {
+                    const whereField = _whereField;
+                    const whereValue = whereClause[whereField];
+                    if (whereValue === undefined || whereValue === null)
+                        return _query;
+                    const processObject = (___query, whereKey, _whereValue) => {
+                        const valueType = typeof _whereValue;
+                        if (Array.isArray(_whereValue)) {
+                            if (_whereValue.length === 0 || _whereValue.length > 10)
+                                throw new BadImplementationException('While querying in an array you can only provide one or more values to query by and not more than 10... this ' +
+                                    'is due to Firestore limitation... ');
+                            if (_whereValue.length === 1)
+                                return _query.where(whereKey, 'array-contains', _whereValue[0]);
+                            return _query.where(whereKey, 'array-contains-any', _whereValue);
+                        }
+                        if (this.isQueryObject(_whereValue)) {
+                            const comparatorKey = Object.keys(_whereValue)[0];
+                            const comparator = ComparatorMap[comparatorKey];
+                            if (!comparator)
+                                throw new ImplementationMissingException(`could not find comparator for: ${comparatorKey} in query: ${JSON.stringify(query)}`);
+                            const value = _whereValue[comparatorKey];
+                            if (value === undefined)
+                                throw new ImplementationMissingException(`no value: ${comparatorKey} in query: ${JSON.stringify(query)}`);
+                            return _query.where(whereKey, comparator, value);
+                        }
+                        if (valueType === 'string' || valueType === 'number' || valueType === 'boolean')
+                            return ___query.where(whereKey, '==', _whereValue);
+                        if (valueType === 'object') {
+                            return Object.keys(_whereValue).reduce((__query, key) => {
+                                return processObject(__query, `${whereKey}.${key}`, _whereValue[key]);
+                            }, ___query);
+                        }
+                        throw new ImplementationMissingException(`Could not compose where clause for '${whereKey}' with value type '${valueType}'in query: ${__stringify(___query)}`);
+                    };
+                    return processObject(_query, whereField, whereValue);
+                }, myQuery);
+            }
+            if (query && query.orderBy)
+                myQuery = query.orderBy.reduce((_query, field) => {
+                    return _query.orderBy ? _query.orderBy(field.key, field.order) : _query;
+                }, myQuery);
+            if (query && query.limit)
+                if (typeof query.limit === 'number')
+                    myQuery = myQuery.limit(query.limit);
+                else {
+                    const page = query.limit.page || 0;
+                    // console.log(`limit: ${query.limit.itemsCount} * ${page}`);
+                    if (page > 0)
+                        myQuery = myQuery.offset(query.limit.itemsCount * page);
+                    myQuery = myQuery.limit(query.limit.itemsCount);
+                }
+            return myQuery;
+        }
+        catch (e) {
+            StaticLogger.logError(`Query: ${JSON.stringify(query)}`);
+            StaticLogger.logError(`Error: ${e}`);
+            throw e;
+        }
+    }
+    static isQueryObject(whereValue) {
+        const keys = Object.keys(whereValue);
+        return typeof whereValue === 'object' && keys.length === 1 && (whereValue['$ac'] !== undefined ||
+            whereValue['$aca'] !== undefined ||
+            whereValue['$in'] !== undefined ||
+            whereValue['$nin'] !== undefined ||
+            whereValue['$gt'] !== undefined ||
+            whereValue['$gte'] !== undefined ||
+            whereValue['$lt'] !== undefined ||
+            whereValue['$lte'] !== undefined ||
+            whereValue['$neq'] !== undefined ||
+            whereValue['$eq'] !== undefined);
+    }
+    static assertUniqueDocument(results, query, collectionName) {
+        if (results.length > 1)
+            throw new BadImplementationException(`too many results for query: ${__stringify(query)} in collection: ${collectionName}`);
+        if (results.length === 0)
+            return;
+        return results[0];
+    }
+}

package/firestore-v3/FirestoreWrapperBEV3.d.ts

@@ -0,0 +1,16 @@
+import { FirestoreCollectionHooks, FirestoreCollectionV3 } from './FirestoreCollectionV3.js';
+import { FirestoreType, FirestoreType_Collection } from '../firestore/types.js';
+import { FirebaseSession } from '../auth/firebase-session.js';
+import { FirebaseBaseWrapper } from '../auth/FirebaseBaseWrapper.js';
+import { DBDef_V3, DBProto } from '@nu-art/ts-common';
+import { Transaction } from 'firebase-admin/firestore';
+export declare class FirestoreWrapperBEV3 extends FirebaseBaseWrapper {
+    readonly firestore: FirestoreType;
+    private readonly collections;
+    constructor(firebaseSession: FirebaseSession<any>, dbName?: string);
+    runTransaction: <ReturnType>(processor: (transaction: Transaction) => Promise<ReturnType>, transaction?: Transaction) => Promise<ReturnType>;
+    getCollection<Proto extends DBProto<any>>(dbDef: DBDef_V3<Proto>, hooks?: FirestoreCollectionHooks<Proto['dbType']>): FirestoreCollectionV3<Proto>;
+    listen<Proto extends DBProto<any>>(collection: FirestoreCollectionV3<Proto>, doc: string): void;
+    listCollections(): Promise<FirestoreType_Collection[]>;
+    isEmulator(): boolean;
+}