@nu-art/firebase-backend 0.401.9 → 0.500.6

package/firestore/FirestoreCollection.js

@@ -15,170 +15,442 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { BadImplementationException, batchAction, exists, generateHex, StaticLogger } from '@nu-art/ts-common';
+import { dbObjectToId } from '@nu-art/db-api-shared';
+import { __stringify, _keys, ApiException, BadImplementationException, batchActionParallel, compare, Const_UniqueKeys, CustomException, DB_Object_validator, dbIdLength, deepClone, DefaultDBVersion, Exception, exists, filterDuplicates, filterInstances, generateHex, keepPartialObject, Logger, MUSTNeverHappenException, StaticLogger, tsValidateResult, tsValidateUniqueId, ValidationException } from '@nu-art/ts-common';
 import { FirestoreInterface } from './FirestoreInterface.js';
-import { FirestoreTransaction } from './FirestoreTransaction.js';
+import { DocWrapper } from './DocWrapper.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, getActiveTransaction } from './consts.js';
+const defaultMultiWriteType = 'batch';
 /**
- * FirestoreCollection is a class for handling Firestore collections. It takes in the name, FirestoreWrapperBE instance, and uniqueKeys as parameters.
+ * # <ins>FirestoreBulkException</ins>
+ * @category Exceptions
  */
-export class FirestoreCollection {
-    name;
+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 FirestoreCollection extends Logger {
     wrapper;
     collection;
-    /**
-     * External unique as in there must never ever be two that answer the same query
-     */
-    externalUniqueFilter;
-    /**
-     * @param name
-     * @param wrapper
-     * @param uniqueKeys
-     */
-    constructor(name, wrapper, uniqueKeys) {
-        this.name = name;
+    dbDef;
+    uniqueKeys;
+    validator;
+    hooks;
+    constructor(wrapper, _dbDef, hooks) {
+        super();
         this.wrapper = wrapper;
-        if (!/[a-z-]{3,}/.test(name))
+        if (!/[a-z-]{3,}/.test(_dbDef.backend.name))
             StaticLogger.logWarning('Please follow name pattern for collections /[a-z-]{3,}/');
-        this.collection = wrapper.firestore.collection(name);
-        this.externalUniqueFilter = (instance) => {
-            if (!uniqueKeys)
-                throw new BadImplementationException('In order to use a unique query your collection MUST have a unique filter');
-            return uniqueKeys.reduce((where, key) => {
-                if (!exists(instance[key]))
-                    throw new BadImplementationException(`No where properties are allowed to be null or undefined.\nWhile querying collection '${this.name}' we found property '${String(key)}' to be '${where[key]}'`);
-                where[key] = instance[key];
-                return where;
-            }, {});
-        };
+        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;
     }
-    /**
-     Executes a Firestore query on the collection.
-     @param ourQuery - The query to execute.
-     @returns A Promise that resolves to an array of FirestoreType_DocumentSnapshot objects.
-     @private
-     */
-    async _query(ourQuery) {
-        const myQuery = FirestoreInterface.buildQuery(this, ourQuery);
-        return (await myQuery.get()).docs;
+    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 DocWrapper(this, ref, data);
+        },
+        unique: (id) => {
+            if (!id)
+                throw new MUSTNeverHappenException('Did not receive an _id at doc.unique!');
+            let idStr;
+            if (typeof id !== 'string')
+                idStr = assertUniqueId(id, this.uniqueKeys);
+            else
+                idStr = id;
+            const doc = this.wrapper.firestore.doc(`${this.collection.path}/${idStr}`);
+            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) => {
+            return preDBItems.map(preDBItem => this.doc.item(preDBItem));
+        },
+        query: async (query) => {
+            return (await this._customQuery(query, true)).map(_snapshot => this.doc._(_snapshot.ref, _snapshot.data()));
+        },
+        unManipulatedQuery: async (query) => {
+            return (await this._customQuery(query, false)).map(_snapshot => this.doc._(_snapshot.ref, _snapshot.data()));
+        },
+    });
+    getAll = async (docs) => {
+        if (docs.length === 0)
+            return [];
+        const transaction = getActiveTransaction();
+        return (await (transaction ?? this.wrapper.firestore).getAll(...docs.map(_doc => _doc.ref))).map(_snapshot => _snapshot.data());
+    };
+    _customQuery = async (tsQuery, canManipulateQuery) => {
+        if (canManipulateQuery)
+            tsQuery = this.hooks?.manipulateQuery?.(deepClone(tsQuery)) ?? tsQuery;
+        const firestoreQuery = FirestoreInterface.buildQuery(this, tsQuery);
+        const transaction = getActiveTransaction();
+        if (transaction)
+            return (await transaction.get(firestoreQuery)).docs;
+        return (await firestoreQuery.get()).docs;
+    };
+    query = Object.freeze({
+        unique: async (_id) => await this.doc.unique(_id).get(),
+        uniqueAssert: async (_id) => {
+            const resultItem = await this.query.unique(_id);
+            if (!resultItem)
+                throw new ApiException(404, `Could not find ${this.dbDef.entityName} with _id: ${__stringify(_id)}`);
+            return resultItem;
+        },
+        uniqueWhere: async (where) => this.query.uniqueCustom({ where }),
+        uniqueCustom: async (query) => {
+            const thisShouldBeOnlyOne = await this.query.custom(query);
+            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) => await this.getAll(this.doc.all(_ids)),
+        custom: async (query) => {
+            return (await this._customQuery(query, true)).map(snapshot => snapshot.data());
+        },
+        where: async (where) => {
+            return this.query.custom({ where });
+        },
+        unManipulatedQuery: async (query) => {
+            return (await this._customQuery(query, false)).map(snapshot => snapshot.data());
+        },
+    });
+    uniqueGetOrCreate = async (where, toCreate) => {
+        try {
+            return await this.query.uniqueWhere(where);
+        }
+        catch (e) {
+            return toCreate();
+        }
+    };
+    _createAll = async (preDBItems, multiWriteType = defaultMultiWriteType) => {
+        if (preDBItems.length === 1)
+            return [await this.create.item(preDBItems[0])];
+        const transaction = getActiveTransaction();
+        const docs = this.doc.allItems(preDBItems);
+        const dbItems = await Promise.all(docs.map((doc, i) => doc.prepareForCreate(preDBItems[i])));
+        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) => await this.doc.item(preDBItem)
+            .create(preDBItem),
+        all: this._createAll,
+    });
+    _setAll = async (items, multiWriteType = defaultMultiWriteType, performUpgrade = true) => {
+        const transaction = getActiveTransaction();
+        const docs = this.doc.allItems(items);
+        const dbItems = await this.getAll(docs);
+        const preparedItems = await Promise.all(dbItems.map(async (_dbItem, i) => {
+            return !exists(_dbItem)
+                ? await docs[i].prepareForCreate(items[i], performUpgrade)
+                : await docs[i].prepareForSet(items[i], _dbItem, performUpgrade);
+        }));
+        this.assertNoDuplicatedIds(preparedItems, 'set.all');
+        if (transaction)
+            docs.map((doc, i) => transaction.set(doc.ref, preparedItems[i]));
+        else
+            await this.multiWrite(multiWriteType, docs, 'set', preparedItems);
+        if (preparedItems.length)
+            await this.hooks?.postWriteProcessing?.({ before: dbItems, updated: preparedItems }, 'set');
+        return preparedItems;
+    };
+    set = Object.freeze({
+        item: async (preDBItem) => {
+            return await this.doc.item(preDBItem).set(preDBItem);
+        },
+        all: (items) => {
+            if (getActiveTransaction())
+                return this._setAll(items);
+            return this.runTransactionInChunks(items, (chunk) => this._setAll(chunk));
+        },
+        /**
+         * Multi is a non atomic operation
+         */
+        multi: (items, multiWriteType = defaultMultiWriteType) => {
+            return this._setAll(items, multiWriteType);
+        },
+    });
+    // @ts-ignore
+    upgradeInstances = (items) => {
+        return this._setAll(items, defaultMultiWriteType, false);
+    };
+    _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) {
     }
+    // update = Object.freeze({
+    // 	item: (updateData: UpdateObject<Proto['dbType']>) => this.doc.unique(updateData._id).update(updateData),
+    // 	all: this._updateAll,
+    // });
+    _deleteQuery = async (query, 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);
+        const itemsToReturn = docsToBeDeleted.map(doc => doc.data);
+        await this._deleteAll(docsToBeDeleted, multiWriteType);
+        return itemsToReturn;
+    };
+    _deleteUnManipulatedQuery = async (query, 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);
+        const itemsToReturn = docsToBeDeleted.map(doc => doc.data);
+        await this._deleteAll(docsToBeDeleted, multiWriteType);
+        return itemsToReturn;
+    };
+    _deleteAll = async (docsToBeDeleted, multiWriteType = defaultMultiWriteType) => {
+        const transaction = getActiveTransaction();
+        const dbItems = filterInstances(await this.getAll(docsToBeDeleted));
+        const itemsToCheck = dbItems.filter((item, index) => docsToBeDeleted[index].ref.id == item._id);
+        addDeletedToTransaction({
+            dbKey: this.dbDef.dbKey,
+            ids: dbItems.map(dbObjectToId)
+        });
+        await this.hooks?.canDeleteItems(itemsToCheck);
+        if (transaction)
+            docsToBeDeleted.map(async (doc) => transaction.delete(doc.ref));
+        else
+            await this.multiWrite(multiWriteType, docsToBeDeleted, 'delete');
+        await this.hooks?.postWriteProcessing?.({ deleted: dbItems }, 'delete');
+        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) => await this.doc.unique(id).delete(),
+        item: async (item) => await this.doc.item(item).delete(),
+        all: async (ids) => {
+            if (!getActiveTransaction())
+                return this.runTransactionInChunks(ids, (chunk) => this.delete.all(chunk));
+            return this._deleteAll(ids.map(id => this.doc.unique(id)));
+        },
+        allDocs: async (docs) => {
+            if (!getActiveTransaction())
+                return this.runTransactionInChunks(docs, (chunk) => this.delete.allDocs(chunk));
+            return await this._deleteAll(docs);
+        },
+        allItems: async (items) => {
+            if (!getActiveTransaction())
+                return this.runTransactionInChunks(items, (chunk) => this.delete.allItems(chunk));
+            return await this._deleteAll(items.map(_item => this.doc.item(_item)));
+        },
+        query: async (query) => {
+            if (!getActiveTransaction()) {
+                if (!exists(query) || compare(query, _EmptyQuery))
+                    throw new MUSTNeverHappenException('An empty query was passed to delete.query!');
+                const docs = await this.doc.query(query);
+                const items = docs.map(doc => doc.data);
+                await this.runTransactionInChunks(docs, (chunk) => this._deleteAll(chunk));
+                return items;
+            }
+            return await this._deleteQuery(query);
+        },
+        unManipulatedQuery: async (query) => {
+            if (!getActiveTransaction()) {
+                if (!exists(query) || compare(query, _EmptyQuery))
+                    throw new MUSTNeverHappenException('An empty query was passed to delete.query!');
+                const docs = await this.doc.unManipulatedQuery(query);
+                const items = docs.map(doc => doc.data);
+                await this.runTransactionInChunks(docs, (chunk) => this._deleteAll(chunk));
+                return items;
+            }
+            return await this._deleteUnManipulatedQuery(query);
+        },
+        where: async (where) => {
+            return this.delete.query({ where });
+        },
+        /**
+         * 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)), multiWriteType),
+            items: async (items, multiWriteType = defaultMultiWriteType) => await this._deleteAll(items.map(_item => this.doc.item(_item)), multiWriteType),
+            allDocs: async (docs, multiWriteType = defaultMultiWriteType) => await this._deleteAll(docs, multiWriteType),
+            query: async (query, multiWriteType = defaultMultiWriteType) => await this._deleteQuery(query, multiWriteType)
+        },
+        yes: { iam: { sure: { iwant: { todelete: { the: { collection: { delete: this.deleteCollection } } } } } } }
+    });
     /**
-
-     Executes a unique Firestore query on the collection.
-     @param ourQuery - The query to execute.
-     @returns A Promise that resolves to a single FirestoreType_DocumentSnapshot object, or undefined if no match is found.
-     @private
+     * @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
      */
-    async _queryUnique(ourQuery) {
-        const results = await this._query(ourQuery);
-        return FirestoreInterface.assertUniqueDocument(results, ourQuery, this.name);
-    }
+    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);
+    };
     /**
-     Executes a unique Firestore query on the collection and returns the matching object.
-     @param ourQuery - The query to execute.
-     @returns A Promise that resolves to the matching object, or undefined if no match is found.
+     * @param docs docs to write to
+     * @param operation create/update/set/delete
+     * @param items mandatory for everything but delete
      */
-    async queryUnique(ourQuery) {
-        const doc = await this._queryUnique(ourQuery);
-        if (!doc)
-            return;
-        return doc.data();
-    }
-    async insert(instance, _id) {
-        await this.createDocumentReference(_id).set(instance);
-        return instance;
-    }
-    async insertAll(instances) {
-        return await Promise.all(instances.map(instance => this.insert(instance)));
-    }
-    async query(ourQuery) {
-        return (await this._query(ourQuery)).map(result => result.data());
-    }
-    async upsert(instance) {
-        return this.runInTransaction((transaction) => transaction.upsert(this, instance));
-    }
-    async upsertAll(instances) {
-        return batchAction(instances, 500, async (chunked) => this.runInTransaction(transaction => transaction.upsertAll(this, chunked)));
-    }
-    async patch(instance) {
-        return this.runInTransaction(transaction => transaction.patch(this, instance));
-    }
-    async deleteItem(instance) {
-        return this.runInTransaction((transaction) => transaction.deleteItem(this, instance));
-    }
-    async deleteUnique(query) {
-        return this.runInTransaction((transaction) => transaction.deleteUnique(this, query));
-    }
-    async delete(query) {
-        const docRefs = await this._query(query);
-        return this.deleteBatch(docRefs);
-    }
-    async deleteBatch(docRefs) {
-        return await batchAction(docRefs, 200, async (chunk) => {
+    batchWrite = async (docs, operation, items) => {
+        for (let batchIndex = 0; batchIndex < docs.length; batchIndex += maxBatch) {
             const batch = this.wrapper.firestore.batch();
-            const toRet = [];
-            await chunk.reduce((_batch, val) => {
-                toRet.push(val.data());
-                return _batch.delete(val.ref);
-            }, batch).commit();
-            return toRet;
-        });
-    }
-    async deleteAll() {
-        const docRefs = await this._query();
-        return this.deleteBatch(docRefs);
-    }
-    async getAll(select) {
-        return this.query({ select });
-    }
-    async runInTransaction(processor) {
-        const firestore = this.wrapper.firestore;
-        return firestore.runTransaction(async (transaction) => {
-            return processor(new FirestoreTransaction(transaction));
-        });
+            const chunk = docs.slice(batchIndex, batchIndex + maxBatch);
+            chunk.map((_doc, index) => this.addToMultiWrite(batch, _doc, operation, items?.[batchIndex + index]));
+            await batch.commit();
+        }
+    };
+    /**
+     * Runs the processor within a Firestore transaction scope. If already inside a transaction
+     * (detected via MemKey), the existing transaction is reused. Otherwise a new one is created.
+     */
+    runTransaction = async (processor) => {
+        return this.wrapper.runTransaction(processor);
+    };
+    runTransactionInChunks = async (items, processor, chunkSize = maxBatch) => {
+        return batchActionParallel(items, chunkSize, (chunk) => this.runTransaction(() => processor(chunk)));
+    };
+    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);
+        }
     }
-    createDocumentReference(_id) {
-        const id = _id || generateHex(16);
-        return this.wrapper.firestore.doc(`${this.name}/${id}`);
+    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);
     }
-    getUniqueFilter = () => this.externalUniqueFilter;
-    async newQueryUnique(ourQuery) {
-        const doc = await this._queryUnique(ourQuery);
-        if (!doc || !doc.exists)
+    assertNoDuplicatedIds(items, originFunctionName) {
+        if (filterDuplicates(items, dbObjectToId).length === items.length)
             return;
-        return new DocWrapper(this.wrapper, doc);
-    }
-    async newQuery(ourQuery) {
-        const docs = await this._query(ourQuery);
-        return docs.filter(doc => doc.exists).map(doc => new DocWrapper(this.wrapper, doc));
-    }
-}
-export class DocWrapper {
-    wrapper;
-    doc;
-    constructor(wrapper, doc) {
-        this.wrapper = wrapper;
-        this.doc = doc;
-    }
-    async runInTransaction(processor) {
-        const firestore = this.wrapper.firestore;
-        return firestore.runTransaction(processor);
+        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)}`);
     }
-    delete = async (transaction) => {
-        if (!transaction) {
-            // const item = this.doc.data();   TODO: TBD do we need a create and run in transaction for each delete??
-            // this.doc.ref.delete();
-            // return item;
-            return this.runInTransaction(this.delete);
-        }
-        const item = this.get();
-        transaction.delete(this.doc.ref);
-        return item;
-    };
-    get = () => this.doc.data();
-    set = async (instance, transaction) => {
-        if (!transaction)
-            return this.runInTransaction((_transaction) => this.set(instance, _transaction));
-        transaction.set(this.doc.ref, instance);
-        return instance;
+    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/FirestoreInterface.d.ts

@@ -1,11 +1,10 @@
 import { FirestoreQuery } from '@nu-art/firebase-shared';
 import { FirestoreType_DocumentSnapshot } from './types.js';
 import { FirestoreCollection } from './FirestoreCollection.js';
-import { TS_Object } from '@nu-art/ts-common';
+import { DB_Prototype } from '@nu-art/db-api-shared';
 import { Query } from 'firebase-admin/firestore';
 export declare class FirestoreInterface {
-    static buildQuery<Type extends TS_Object>(collection: FirestoreCollection<Type>, query?: FirestoreQuery<Type>): Query<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
+    static buildQuery<Proto extends DB_Prototype>(collection: FirestoreCollection<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);
-    static buildUniqueQuery<Type extends TS_Object>(collection: FirestoreCollection<Type>, instance: Type): FirestoreQuery<Type>;
 }

package/firestore/FirestoreInterface.js

@@ -73,7 +73,7 @@ export class FirestoreInterface {
                     const page = query.limit.page || 0;
                     // console.log(`limit: ${query.limit.itemsCount} * ${page}`);
                     if (page > 0)
-                        myQuery = myQuery.offset(query.limit.itemsCount * page + 1);
+                        myQuery = myQuery.offset(query.limit.itemsCount * page);
                     myQuery = myQuery.limit(query.limit.itemsCount);
                 }
             return myQuery;
@@ -104,8 +104,4 @@ export class FirestoreInterface {
             return;
         return results[0];
     }
-    static buildUniqueQuery(collection, instance) {
-        const where = collection.externalUniqueFilter(instance);
-        return { where };
-    }
 }

package/firestore/FirestoreWrapperBE.d.ts

@@ -1,16 +1,15 @@
-import { FirestoreCollection } from './FirestoreCollection.js';
+import { FirestoreCollectionHooks, FirestoreCollection } from './FirestoreCollection.js';
 import { FirestoreType, FirestoreType_Collection } from './types.js';
-import { FilterKeys } from '@nu-art/firebase-shared';
 import { FirebaseSession } from '../auth/firebase-session.js';
 import { FirebaseBaseWrapper } from '../auth/FirebaseBaseWrapper.js';
-import { DB_Object, TS_Object } from '@nu-art/ts-common';
+import { Database, DB_Prototype } from '@nu-art/db-api-shared';
 export declare class FirestoreWrapperBE extends FirebaseBaseWrapper {
     readonly firestore: FirestoreType;
     private readonly collections;
     constructor(firebaseSession: FirebaseSession<any>, dbName?: string);
-    getCollection<Type extends TS_Object>(name: string, uniqueKeys?: FilterKeys<Type>): FirestoreCollection<Type>;
-    listen<Type extends DB_Object>(collection: FirestoreCollection<Type>, doc: string): void;
-    deleteCollection(name: string): Promise<TS_Object[]>;
+    runTransaction: <ReturnType>(processor: () => Promise<ReturnType>) => Promise<ReturnType>;
+    getCollection<Proto extends DB_Prototype>(dbDef: Database<Proto>, hooks?: FirestoreCollectionHooks<Proto['dbType']>): FirestoreCollection<Proto>;
+    listen<Proto extends DB_Prototype>(collection: FirestoreCollection<Proto>, doc: string): void;
     listCollections(): Promise<FirestoreType_Collection[]>;
     isEmulator(): boolean;
 }