@twin.org/entity-storage-connector-gcp-firestore 0.0.3-next.9 → 0.9.0

package/dist/es/firestoreEntityStorageConnector.js

@@ -1,9 +1,10 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-import { Firestore } from "@google-cloud/firestore";
+import { Filter, Firestore } from "@google-cloud/firestore";
 import { ContextIdHelper, ContextIdStore } from "@twin.org/context";
-import { BaseError, ComponentFactory, Converter, GeneralError, Guards, Is, ObjectHelper } from "@twin.org/core";
-import { ComparisonOperator, EntityConditions, EntitySchemaFactory, EntitySchemaHelper, SortDirection } from "@twin.org/entity";
+import { BaseError, ComponentFactory, Converter, GeneralError, Guards, HealthStatus, Is, ObjectHelper, Validation } from "@twin.org/core";
+import { ComparisonOperator, EntityConditions, EntitySchemaFactory, EntitySchemaHelper, LogicalOperator, SortDirection } from "@twin.org/entity";
+import { EntityStorageHelper } from "@twin.org/entity-storage-models";
 /**
  * Class for performing entity storage operations using Firestore.
  */
@@ -17,6 +18,17 @@ export class FirestoreEntityStorageConnector {
      * @internal
      */
     static _DEFAULT_LIMIT = 40;
+    /**
+     * Separator used between context ID parts in Firestore collection names.
+     * Must not be "/" which Firestore interprets as a path separator.
+     * @internal
+     */
+    static _PARTITION_SEPARATOR = ":";
+    /**
+     * The name for the schema.
+     * @internal
+     */
+    _entitySchemaName;
     /**
      * The schema for the entity.
      * @internal
@@ -58,6 +70,7 @@ export class FirestoreEntityStorageConnector {
             credentials = ObjectHelper.fromBytes(Converter.base64ToBytes(options.config.credentials));
         }
         this._config = options.config;
+        this._entitySchemaName = options.entitySchema;
         this._entitySchema = EntitySchemaFactory.get(options.entitySchema);
         this._partitionContextIds = options.partitionContextIds;
         this._primaryKey = EntitySchemaHelper.getPrimaryKey(this._entitySchema);
@@ -82,6 +95,34 @@ export class FirestoreEntityStorageConnector {
     className() {
         return FirestoreEntityStorageConnector.CLASS_NAME;
     }
+    /**
+     * Returns the health status of the component.
+     * @returns The health status of the component.
+     */
+    async health() {
+        try {
+            await this._firestoreClient.listCollections();
+            return [
+                {
+                    source: FirestoreEntityStorageConnector.CLASS_NAME,
+                    status: HealthStatus.Ok,
+                    description: "healthDescription",
+                    data: { projectId: this._config.projectId, collectionName: this._config.collectionName }
+                }
+            ];
+        }
+        catch {
+            return [
+                {
+                    source: FirestoreEntityStorageConnector.CLASS_NAME,
+                    status: HealthStatus.Error,
+                    description: "healthDescription",
+                    message: "connectionFailed",
+                    data: { projectId: this._config.projectId, collectionName: this._config.collectionName }
+                }
+            ];
+        }
+    }
     /**
      * Get the schema for the entities.
      * @returns The schema for the entities.
@@ -149,14 +190,14 @@ export class FirestoreEntityStorageConnector {
     async get(id, secondaryIndex, conditions) {
         Guards.stringValue(FirestoreEntityStorageConnector.CLASS_NAME, "id", id);
         const contextIds = await ContextIdStore.getContextIds();
-        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds, FirestoreEntityStorageConnector._PARTITION_SEPARATOR);
         try {
             const collection = this._firestoreClient.collection(this.collectionName(partitionKey));
             if (!Is.arrayValue(conditions)) {
                 const docRef = collection.doc(id);
                 const doc = await docRef.get();
                 if (doc.exists) {
-                    return doc.data();
+                    return EntityStorageHelper.unPrepareEntity(doc.data(), []);
                 }
             }
             // Use conditions to construct a query
@@ -175,8 +216,7 @@ export class FirestoreEntityStorageConnector {
             }
             const querySnapshot = await query.limit(1).get();
             if (!querySnapshot.empty) {
-                const entity = querySnapshot.docs[0].data();
-                return entity;
+                return EntityStorageHelper.unPrepareEntity(querySnapshot.docs[0].data(), []);
             }
         }
         catch (err) {
@@ -192,20 +232,22 @@ export class FirestoreEntityStorageConnector {
     async set(entity, conditions) {
         Guards.object(FirestoreEntityStorageConnector.CLASS_NAME, "entity", entity);
         const contextIds = await ContextIdStore.getContextIds();
-        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
-        EntitySchemaHelper.validateEntity(entity, this.getSchema());
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds, FirestoreEntityStorageConnector._PARTITION_SEPARATOR);
+        const prepared = EntityStorageHelper.prepareEntity(entity, this._entitySchema, undefined, {
+            nullBehavior: "nullify"
+        });
         try {
-            const id = entity[this._primaryKey.property];
+            const id = prepared[this._primaryKey.property];
             const collection = this._firestoreClient.collection(this.collectionName(partitionKey));
             const docRef = collection.doc(id);
             if (!Is.arrayValue(conditions)) {
-                await docRef.set(entity);
+                await docRef.set(prepared);
             }
             else {
                 await this._firestoreClient.runTransaction(async (transaction) => {
                     const docSnapshot = await transaction.get(docRef);
                     if (!docSnapshot.exists) {
-                        transaction.set(docRef, entity);
+                        transaction.set(docRef, prepared);
                     }
                     else {
                         const data = docSnapshot.data();
@@ -216,7 +258,7 @@ export class FirestoreEntityStorageConnector {
                                 value: c.value
                             }))
                         })) {
-                            transaction.set(docRef, entity);
+                            transaction.set(docRef, prepared);
                         }
                     }
                 });
@@ -226,6 +268,60 @@ export class FirestoreEntityStorageConnector {
             throw new GeneralError(FirestoreEntityStorageConnector.CLASS_NAME, "setEntityFailed", { id: entity.id }, err);
         }
     }
+    /**
+     * Set multiple entities in a batch.
+     * @param entities The entities to set.
+     * @returns Nothing.
+     */
+    async setBatch(entities) {
+        Guards.arrayValue(FirestoreEntityStorageConnector.CLASS_NAME, "entities", entities);
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds, FirestoreEntityStorageConnector._PARTITION_SEPARATOR);
+        const preparedEntities = entities.map(entity => EntityStorageHelper.prepareEntity(entity, this._entitySchema, undefined, {
+            nullBehavior: "nullify"
+        }));
+        try {
+            const collection = this._firestoreClient.collection(this.collectionName(partitionKey));
+            const chunkSize = FirestoreEntityStorageConnector._DEFAULT_LIMIT;
+            for (let i = 0; i < preparedEntities.length; i += chunkSize) {
+                const chunk = preparedEntities.slice(i, i + chunkSize);
+                const batch = this._firestoreClient.batch();
+                for (const entity of chunk) {
+                    const id = entity[this._primaryKey.property];
+                    const docRef = collection.doc(id);
+                    batch.set(docRef, entity);
+                }
+                await batch.commit();
+            }
+        }
+        catch (err) {
+            throw new GeneralError(FirestoreEntityStorageConnector.CLASS_NAME, "setBatchFailed", undefined, err);
+        }
+    }
+    /**
+     * Empty the storage by deleting all entities in the collection.
+     * @returns Nothing.
+     */
+    async empty() {
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds, FirestoreEntityStorageConnector._PARTITION_SEPARATOR);
+        try {
+            const collection = this._firestoreClient.collection(this.collectionName(partitionKey));
+            const snapshot = await collection.get();
+            const chunkSize = 500;
+            for (let i = 0; i < snapshot.docs.length; i += chunkSize) {
+                const chunk = snapshot.docs.slice(i, i + chunkSize);
+                const batch = this._firestoreClient.batch();
+                for (const doc of chunk) {
+                    batch.delete(doc.ref);
+                }
+                await batch.commit();
+            }
+        }
+        catch (err) {
+            throw new GeneralError(FirestoreEntityStorageConnector.CLASS_NAME, "emptyFailed", undefined, err);
+        }
+    }
     /**
      * Remove the entity.
      * @param id The id of the entity to remove.
@@ -235,7 +331,7 @@ export class FirestoreEntityStorageConnector {
     async remove(id, conditions) {
         Guards.stringValue(FirestoreEntityStorageConnector.CLASS_NAME, "id", id);
         const contextIds = await ContextIdStore.getContextIds();
-        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds, FirestoreEntityStorageConnector._PARTITION_SEPARATOR);
         try {
             const collection = this._firestoreClient.collection(this.collectionName(partitionKey));
             const docRef = collection.doc(id);
@@ -264,6 +360,146 @@ export class FirestoreEntityStorageConnector {
             throw new GeneralError(FirestoreEntityStorageConnector.CLASS_NAME, "removeEntityFailed", { id }, err);
         }
     }
+    /**
+     * Remove multiple entities by their primary key IDs using a Firestore WriteBatch.
+     * @param ids The ids of the entities to remove.
+     * @returns Nothing.
+     */
+    async removeBatch(ids) {
+        Guards.arrayValue(FirestoreEntityStorageConnector.CLASS_NAME, "ids", ids);
+        const contextIds = await ContextIdStore.getContextIds();
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds, FirestoreEntityStorageConnector._PARTITION_SEPARATOR);
+        try {
+            const collection = this._firestoreClient.collection(this.collectionName(partitionKey));
+            const chunkSize = 500;
+            for (let i = 0; i < ids.length; i += chunkSize) {
+                const chunk = ids.slice(i, i + chunkSize);
+                const batch = this._firestoreClient.batch();
+                for (const id of chunk) {
+                    const docRef = collection.doc(id);
+                    batch.delete(docRef);
+                }
+                await batch.commit();
+            }
+        }
+        catch (err) {
+            throw new GeneralError(FirestoreEntityStorageConnector.CLASS_NAME, "removeBatchFailed", undefined, err);
+        }
+    }
+    /**
+     * Teardown the storage by deleting all documents across all partition collections.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns True if the teardown process was successful.
+     */
+    async teardown(nodeLoggingComponentType) {
+        const nodeLogging = ComponentFactory.getIfExists(nodeLoggingComponentType);
+        await nodeLogging?.log({
+            level: "info",
+            source: FirestoreEntityStorageConnector.CLASS_NAME,
+            ts: Date.now(),
+            message: "storeTearingDown"
+        });
+        try {
+            await this.deleteAllPartitionCollections(this._config.collectionName);
+            await nodeLogging?.log({
+                level: "info",
+                source: FirestoreEntityStorageConnector.CLASS_NAME,
+                ts: Date.now(),
+                message: "storeTornDown"
+            });
+            return true;
+        }
+        catch (err) {
+            await nodeLogging?.log({
+                level: "error",
+                source: FirestoreEntityStorageConnector.CLASS_NAME,
+                ts: Date.now(),
+                message: "teardownFailed",
+                error: BaseError.fromError(err)
+            });
+            return false;
+        }
+    }
+    /**
+     * Get a unique list of all the context ids from the storage.
+     * @returns The list of unique context ids.
+     */
+    async getPartitionContextIds() {
+        const partitionContextIds = this._partitionContextIds;
+        if (!Is.arrayValue(partitionContextIds)) {
+            return [];
+        }
+        try {
+            const prefix = `${this._config.collectionName}_`;
+            const collections = await this._firestoreClient.listCollections();
+            const result = [];
+            for (const col of collections) {
+                if (col.id.startsWith(prefix)) {
+                    const partitionKey = col.id.slice(prefix.length);
+                    if (Is.stringValue(partitionKey)) {
+                        result.push(ContextIdHelper.shortSplit(partitionContextIds, partitionKey, FirestoreEntityStorageConnector._PARTITION_SEPARATOR));
+                    }
+                }
+            }
+            return result;
+        }
+        catch (err) {
+            throw new GeneralError(FirestoreEntityStorageConnector.CLASS_NAME, "getPartitionContextIdsFailed", undefined, err);
+        }
+    }
+    /**
+     * Create the target connector for performing the migration using a temporary collection name.
+     * @param newEntitySchema The name of the new entity schema to create the connector for.
+     * @returns Connector for performing the migration.
+     */
+    async createTargetConnector(newEntitySchema) {
+        const migrationCollectionName = `${this._config.collectionName}Migration${Date.now()}`;
+        return new FirestoreEntityStorageConnector({
+            entitySchema: newEntitySchema,
+            config: { ...this._config, collectionName: migrationCollectionName },
+            partitionContextIds: this._partitionContextIds
+        });
+    }
+    /**
+     * Finalize the migration by tearing down the old collections and replacing them with the target collections.
+     * @param targetConnector The target connector to finalize the migration with.
+     * @param options The options to control how the migration is finalized.
+     * @param loggingComponentType The optional component type to use for logging.
+     * @returns The final connector pointing at the original collection name.
+     */
+    async finalizeMigration(targetConnector, options, loggingComponentType) {
+        // Firestore has no collection-rename operation, so we create fresh collections under
+        // the original name, copy all documents from the migration collections, then delete the
+        // migration collections.
+        // Teardown all existing source collections to free up the original collection name prefix.
+        await this.teardown(loggingComponentType);
+        // Create a new connector at the original collection name but with the new schema.
+        const originalCollectionName = this._config.collectionName;
+        const finalConnector = new FirestoreEntityStorageConnector({
+            entitySchema: targetConnector._entitySchemaName,
+            config: { ...targetConnector._config, collectionName: originalCollectionName },
+            partitionContextIds: this._partitionContextIds
+        });
+        if (await finalConnector.bootstrap(loggingComponentType)) {
+            // Since there is no rename, we need to copy the data from the migration table to the new table
+            const partitions = await targetConnector.getPartitionContextIds();
+            const batchSize = options?.batchSize ?? FirestoreEntityStorageConnector._DEFAULT_LIMIT;
+            await this.bulkCopy(targetConnector, finalConnector, partitions, batchSize);
+            await targetConnector.teardown(loggingComponentType);
+            return finalConnector;
+        }
+        throw new GeneralError(FirestoreEntityStorageConnector.CLASS_NAME, "finalizeMigrationFailedBootstrap", undefined);
+    }
+    /**
+     * Cleanup the migration if a migration fails or needs to be aborted.
+     * @param targetConnector The target connector to cleanup.
+     * @param options The options to control how the migration is cleaned up.
+     * @param loggingComponentType The optional component type to use for logging.
+     */
+    async cleanupMigration(targetConnector, options, loggingComponentType) {
+        // If something failed the only thing to cleanup is the migration table
+        await targetConnector?.teardown?.(loggingComponentType);
+    }
     /**
      * Find all the entities which match the conditions.
      * @param conditions The conditions to match for the entities.
@@ -276,12 +512,64 @@ export class FirestoreEntityStorageConnector {
     async query(conditions, sortProperties, properties, cursor, limit) {
         const queryDescription = [];
         const contextIds = await ContextIdStore.getContextIds();
-        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds);
+        const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds, FirestoreEntityStorageConnector._PARTITION_SEPARATOR);
+        const finalLimit = limit ?? FirestoreEntityStorageConnector._DEFAULT_LIMIT;
+        EntityStorageHelper.validateSortProperties(this._entitySchema, sortProperties);
+        EntityStorageHelper.validateProperties(this._entitySchema, properties);
+        if (!Is.empty(limit)) {
+            const validationFailures = [];
+            Validation.integer("limit", limit, validationFailures, undefined, { minValue: 1 });
+            Validation.asValidationError(FirestoreEntityStorageConnector.CLASS_NAME, "query", validationFailures);
+        }
         try {
             const collection = this._firestoreClient.collection(this.collectionName(partitionKey));
+            // Firestore has no native substring search. When any condition needs in-memory
+            // filtering (string Includes / NotIncludes), fetch all matching docs and filter
+            // client-side, using an index-based cursor for pagination.
+            if (!Is.empty(conditions) && this.needsPostFilter(conditions)) {
+                queryDescription.push("InMemoryFilter");
+                let baseQuery = collection;
+                if (Is.arrayValue(sortProperties)) {
+                    for (const { property, sortDirection } of sortProperties) {
+                        baseQuery = baseQuery.orderBy(property, sortDirection === SortDirection.Ascending ? "asc" : "desc");
+                    }
+                }
+                const allSnapshot = await baseQuery.get();
+                let allEntities = allSnapshot.docs.map((doc) => EntityStorageHelper.unPrepareEntity(doc.data(), []));
+                allEntities = allEntities.filter(e => EntityConditions.check(e, conditions));
+                let projected;
+                if (Is.arrayValue(properties)) {
+                    projected = allEntities.map(e => {
+                        const out = {};
+                        for (const prop of properties) {
+                            if (prop in e) {
+                                out[prop] = e[prop];
+                            }
+                        }
+                        return out;
+                    });
+                }
+                else {
+                    projected = allEntities;
+                }
+                const start = Is.stringValue(cursor) ? Number.parseInt(cursor, 10) : 0;
+                const page = projected.slice(start, start + finalLimit);
+                const nextCursor = start + finalLimit < projected.length ? String(start + finalLimit) : undefined;
+                return { entities: page, cursor: nextCursor };
+            }
+            if (this.hasEmptyInCondition(conditions)) {
+                return { entities: [], cursor: undefined };
+            }
+            // Prune empty-In leaves from OR branches: the Firestore SDK throws on
+            // Filter.where(prop, "in", []) even inside an OR where other branches still match.
+            // hasEmptyInCondition above already handles the all-false case, so pruning here
+            // is safe — any removed leaf was a no-op branch.
+            const effectiveConditions = !Is.empty(conditions)
+                ? (this.pruneEmptyInConditions(conditions) ?? undefined)
+                : conditions;
             let query = collection;
-            if (!Is.empty(conditions)) {
-                query = this.applyConditions(query, conditions);
+            if (!Is.empty(effectiveConditions)) {
+                query = this.applyConditions(query, effectiveConditions);
                 queryDescription.push(`Conditions: ${JSON.stringify(conditions)}`);
             }
             if (Is.arrayValue(sortProperties)) {
@@ -291,24 +579,30 @@ export class FirestoreEntityStorageConnector {
                 queryDescription.push(`Sort: ${JSON.stringify(sortProperties)}`);
             }
             if (Is.stringValue(cursor)) {
-                const cursorDoc = await this._firestoreClient.doc(cursor).get();
-                if (cursorDoc?.exists) {
-                    query = query.startAfter(cursorDoc);
+                // Discard cursors from a different partition — startAfter() throws if the
+                // snapshot belongs to a different collection than the current query.
+                const cursorCollection = cursor.slice(0, cursor.lastIndexOf("/"));
+                if (cursorCollection === this.collectionName(partitionKey)) {
+                    const cursorDoc = await this._firestoreClient.doc(cursor).get();
+                    if (cursorDoc?.exists) {
+                        query = query.startAfter(cursorDoc);
+                    }
+                    queryDescription.push(`Cursor: ${cursor}`);
                 }
-                queryDescription.push(`Cursor: ${cursor}`);
             }
-            const finalLimit = limit ?? FirestoreEntityStorageConnector._DEFAULT_LIMIT;
-            query = query.limit(finalLimit);
+            query = query.limit(finalLimit + 1);
             queryDescription.push(`Limit: ${finalLimit}`);
-            if (properties) {
+            if (Is.arrayValue(properties)) {
                 query = query.select(...properties);
                 queryDescription.push(`Properties: ${properties.join(", ")}`);
             }
             const querySnapshot = await query.get();
-            const entities = querySnapshot.docs.map((doc) => doc.data());
+            const hasMore = querySnapshot.docs.length > finalLimit;
+            const resultDocs = hasMore ? querySnapshot.docs.slice(0, finalLimit) : querySnapshot.docs;
+            const entities = resultDocs.map((doc) => EntityStorageHelper.unPrepareEntity(doc.data(), []));
             let nextCursor;
-            if (entities.length === finalLimit) {
-                nextCursor = querySnapshot.docs[querySnapshot.docs.length - 1].ref.path;
+            if (hasMore) {
+                nextCursor = resultDocs[resultDocs.length - 1].ref.path;
             }
             return {
                 entities,
@@ -320,86 +614,249 @@ export class FirestoreEntityStorageConnector {
         }
     }
     /**
-     * Delete all entities in the collection.
-     * @returns Nothing.
-     * @internal
+     * Count all the entities which match the conditions.
+     * @param conditions The optional conditions to match for the entities.
+     * @returns The total count of entities in the storage.
      */
-    async collectionDelete() {
-        const collection = this._firestoreClient.collection(this.collectionName());
-        const batchSize = 500;
-        const query = collection.limit(batchSize);
+    async count(conditions) {
         try {
-            await this.deleteQueryBatch(query, batchSize);
+            const contextIds = await ContextIdStore.getContextIds();
+            const partitionKey = ContextIdHelper.combinedContextKey(contextIds, this._partitionContextIds, FirestoreEntityStorageConnector._PARTITION_SEPARATOR);
+            const collection = this._firestoreClient.collection(this.collectionName(partitionKey));
+            if (this.hasEmptyInCondition(conditions)) {
+                return 0;
+            }
+            if (!Is.empty(conditions) && this.needsPostFilter(conditions)) {
+                const allSnapshot = await collection.get();
+                const allEntities = allSnapshot.docs.map((doc) => EntityStorageHelper.unPrepareEntity(doc.data(), []));
+                return allEntities.filter(e => EntityConditions.check(e, conditions)).length;
+            }
+            const effectiveConditions = !Is.empty(conditions)
+                ? (this.pruneEmptyInConditions(conditions) ?? undefined)
+                : conditions;
+            let query = collection;
+            if (!Is.empty(effectiveConditions)) {
+                query = this.applyConditions(query, effectiveConditions);
+            }
+            const snapshot = await query.count().get();
+            return snapshot.data().count;
         }
-        catch (error) {
-            throw new GeneralError(FirestoreEntityStorageConnector.CLASS_NAME, "collectionDeleteFailed", { collectionName: this._config.collectionName }, error);
+        catch (err) {
+            throw new GeneralError(FirestoreEntityStorageConnector.CLASS_NAME, "countFailed", undefined, err);
+        }
+    }
+    /**
+     * Copy all entities from sourceConnector to destConnector, paging through each partition.
+     * @param sourceConnector The connector to read entities from.
+     * @param destConnector The connector to write entities to.
+     * @param partitions The partition list returned by getPartitionContextIds.
+     * @param batchSize The number of entities to read per page.
+     * @internal
+     */
+    async bulkCopy(sourceConnector, destConnector, partitions, batchSize) {
+        let partitionList;
+        if (Is.arrayValue(partitions)) {
+            partitionList = partitions;
+        }
+        else if (Is.arrayValue(sourceConnector._partitionContextIds)) {
+            partitionList = [];
+        }
+        else {
+            partitionList = [{}];
+        }
+        for (let i = 0; i < partitionList.length; i++) {
+            const partitionKey = ContextIdHelper.combinedContextKey(partitionList[i], sourceConnector._partitionContextIds, FirestoreEntityStorageConnector._PARTITION_SEPARATOR);
+            const sourceCollection = sourceConnector._firestoreClient.collection(sourceConnector.collectionName(partitionKey));
+            const destCollection = destConnector._firestoreClient.collection(destConnector.collectionName(partitionKey));
+            let lastDoc;
+            let hasMore = true;
+            while (hasMore) {
+                let pageQuery = sourceCollection.limit(batchSize);
+                if (lastDoc) {
+                    pageQuery = pageQuery.startAfter(lastDoc);
+                }
+                const snapshot = await pageQuery.get();
+                const docs = snapshot.docs;
+                for (let j = 0; j < docs.length; j += batchSize) {
+                    const chunk = docs.slice(j, j + batchSize);
+                    const batch = destConnector._firestoreClient.batch();
+                    for (const doc of chunk) {
+                        batch.set(destCollection.doc(doc.id), doc.data());
+                    }
+                    await batch.commit();
+                }
+                lastDoc = docs[docs.length - 1];
+                hasMore = docs.length === batchSize;
+            }
+        }
+    }
+    /**
+     * Delete all documents in every collection whose name starts with collectionName_.
+     * @param collectionName The base collection name prefix.
+     * @internal
+     */
+    async deleteAllPartitionCollections(collectionName) {
+        const prefix = `${collectionName}_`;
+        const collections = await this._firestoreClient.listCollections();
+        const chunkSize = 500;
+        for (const col of collections) {
+            if (col.id.startsWith(prefix)) {
+                const snapshot = await col.get();
+                for (let i = 0; i < snapshot.docs.length; i += chunkSize) {
+                    const chunk = snapshot.docs.slice(i, i + chunkSize);
+                    const batch = this._firestoreClient.batch();
+                    for (const doc of chunk) {
+                        batch.delete(doc.ref);
+                    }
+                    await batch.commit();
+                }
+            }
         }
     }
     /**
-     * Apply conditions to a Firestore query.
+     * Returns true when the condition tree is guaranteed to match nothing due to empty
+     * In lists, respecting AND/OR boolean semantics (#141):
+     * - AND group: true if ANY child is always-false (false AND x = false)
+     * - OR  group: true if ALL children are always-false (false OR false = false)
+     * - Leaf:      true only for `In []`
+     * @param condition The condition tree to inspect.
+     * @returns True if a short-circuit to empty results is required.
+     * @internal
+     */
+    hasEmptyInCondition(condition) {
+        if (Is.empty(condition)) {
+            return false;
+        }
+        if ("conditions" in condition) {
+            return condition.logicalOperator === LogicalOperator.Or
+                ? condition.conditions.every(c => this.hasEmptyInCondition(c))
+                : condition.conditions.some(c => this.hasEmptyInCondition(c));
+        }
+        return (condition.comparison === ComparisonOperator.In &&
+            Is.array(condition.value) &&
+            condition.value.length === 0);
+    }
+    /**
+     * Returns a copy of the condition tree with all empty-In leaves removed.
+     * Used to keep `In []` out of native Firestore Filter calls (the SDK throws on
+     * `Filter.where(prop, "in", [])`) while preserving correct OR semantics (#141).
+     * Returns null when the entire subtree reduces to nothing (caller should treat
+     * as no conditions).
+     * @param condition The condition to prune.
+     * @returns The pruned condition, or null if the subtree was fully removed.
+     * @internal
+     */
+    pruneEmptyInConditions(condition) {
+        if (!("conditions" in condition)) {
+            if (condition.comparison === ComparisonOperator.In &&
+                Is.array(condition.value) &&
+                condition.value.length === 0) {
+                return null;
+            }
+            return condition;
+        }
+        // For AND groups: if any child has an empty In, the whole AND is dead.
+        // Do not recurse — promoting the surviving siblings would turn a dead
+        // branch into a live one when this AND sits inside an OR (#141).
+        if (condition.logicalOperator !== LogicalOperator.Or && this.hasEmptyInCondition(condition)) {
+            return null;
+        }
+        // For OR groups: prune dead branches individually so the Firestore SDK
+        // never receives `In []`, while keeping live siblings.
+        const pruned = condition.conditions
+            .map(c => this.pruneEmptyInConditions(c))
+            .filter((c) => c !== null);
+        if (pruned.length === 0) {
+            return null;
+        }
+        if (pruned.length === 1) {
+            return pruned[0];
+        }
+        return { ...condition, conditions: pruned };
+    }
+    /**
+     * Returns true when any leaf condition requires client-side filtering
+     * (Firestore has no native string-contains / not-contains operator).
+     * @param condition The condition tree to inspect.
+     * @returns True if post-filtering is required.
+     * @internal
+     */
+    needsPostFilter(condition) {
+        if (Is.empty(condition)) {
+            return false;
+        }
+        if ("conditions" in condition) {
+            return condition.conditions.some(c => this.needsPostFilter(c));
+        }
+        const { comparison, value } = condition;
+        if (comparison === ComparisonOperator.NotIncludes) {
+            return true;
+        }
+        // Includes on a primitive (string/number) means substring search — not natively supported.
+        // Includes on an object means array-contains, which Firestore does support.
+        if (comparison === ComparisonOperator.Includes &&
+            (value === null || typeof value !== "object")) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Apply conditions to a Firestore query using composite Filter objects so that
+     * OR groups are handled correctly.
      * @param query The initial query.
      * @param condition The condition to apply.
      * @returns The updated query.
      * @internal
      */
     applyConditions(query, condition) {
+        return query.where(this.buildFilter(condition));
+    }
+    /**
+     * Recursively convert an EntityCondition tree into a Firestore Filter.
+     * Only called for native conditions (needsPostFilter must be false).
+     * @param condition The condition to convert.
+     * @returns A Firestore Filter.
+     * @throws GeneralError if the comparison operator is not supported.
+     * @internal
+     */
+    buildFilter(condition) {
         if ("conditions" in condition) {
-            // It's a group of conditions
-            for (const c of condition.conditions) {
-                query = this.applyConditions(query, c);
-            }
-            return query;
+            const filters = condition.conditions.map(c => this.buildFilter(c));
+            return condition.logicalOperator === LogicalOperator.Or
+                ? Filter.or(...filters)
+                : Filter.and(...filters);
         }
-        // It's a single condition
         const { property, comparison } = condition;
-        // Firestore has no undefined type — the SDK throws on undefined values.
-        // For Equals/NotEquals, null already has the correct semantics:
+        // Firestore has no undefined type — null has the correct semantics:
         //   == null  matches documents where the field is null OR missing
         //   != null  matches documents where the field exists and is not null
         const value = condition.value === undefined ? null : condition.value;
         switch (comparison) {
             case ComparisonOperator.Equals:
-                return query.where(property, "==", value);
+                return Filter.where(property, "==", value);
             case ComparisonOperator.NotEquals:
-                return query.where(property, "!=", value);
+                return Filter.where(property, "!=", value);
             case ComparisonOperator.GreaterThan:
-                return query.where(property, ">", value);
+                return Filter.where(property, ">", value);
             case ComparisonOperator.LessThan:
-                return query.where(property, "<", value);
+                return Filter.where(property, "<", value);
             case ComparisonOperator.GreaterThanOrEqual:
-                return query.where(property, ">=", value);
+                return Filter.where(property, ">=", value);
             case ComparisonOperator.LessThanOrEqual:
-                return query.where(property, "<=", value);
+                return Filter.where(property, "<=", value);
             case ComparisonOperator.In:
-                return query.where(property, "in", value);
+                return Filter.where(property, "in", value);
             case ComparisonOperator.Includes:
-                return query.where(property, "array-contains", value);
+                // Object value → array-contains (caller ensured needsPostFilter is false here)
+                return Filter.where(property, "array-contains", value);
             case ComparisonOperator.NotIncludes:
             default:
                 throw new GeneralError(FirestoreEntityStorageConnector.CLASS_NAME, "unsupportedComparisonOperator", { comparison });
         }
     }
-    /**
-     * Delete all entities in the collection.
-     * @returns Nothing.
-     * @internal
-     */
-    async deleteQueryBatch(query, batchSize) {
-        const snapshot = await query.get();
-        if (snapshot.size === 0) {
-            return;
-        }
-        const batch = this._firestoreClient.batch();
-        for (const doc of snapshot.docs) {
-            batch.delete(doc.ref);
-        }
-        await batch.commit();
-        if (snapshot.size === batchSize) {
-            await this.deleteQueryBatch(query, batchSize);
-        }
-    }
     /**
      * Get the collection name based on partition key.
+     * @param partitionKey The optional partition key to include in the collection name.
      * @returns The collection name.
      * @internal
      */