@causa/runtime-google 0.39.1 → 1.0.0-rc.1

package/dist/spanner/testing.js

@@ -1,5 +1,21 @@
 import { Database, Instance, Spanner } from '@google-cloud/spanner';
 import * as uuid from 'uuid';
+import { SpannerEntityManager } from './entity-manager.js';
+/**
+ * Sets default values for the database creation parameters.
+ *
+ * @param options The options for which defaults should be set where needed.
+ * @returns The {@link CreateDatabaseParameters}.
+ */
+function makeDatabaseParameters(options) {
+    const name = options.name ?? `test-${uuid.v4().slice(-10)}`;
+    const spanner = options.instance?.parent ?? options.spanner ?? new Spanner();
+    const instance = options.instance ?? spanner.instance(process.env.SPANNER_INSTANCE ?? '');
+    const sourceDatabaseName = options.sourceDatabaseName === null
+        ? null
+        : (options.sourceDatabaseName ?? process.env.SPANNER_DATABASE ?? null);
+    return { name, spanner, instance, sourceDatabaseName };
+}
 /**
  * Creates a new database.
  * This will destroy the existing database if it exists.
@@ -8,10 +24,7 @@ import * as uuid from 'uuid';
  * @returns The database object.
  */
 export async function createDatabase(options = {}) {
-    const name = options.name ?? `test-${uuid.v4().slice(-10)}`;
-    const spanner = options.spanner ?? new Spanner();
-    const instance = options.instance ?? spanner.instance(process.env.SPANNER_INSTANCE ?? '');
-    const sourceDatabaseName = options.sourceDatabaseName ?? process.env.SPANNER_DATABASE;
+    const { name, sourceDatabaseName, instance } = makeDatabaseParameters(options);
     const [databases] = await instance.getDatabases();
     const existingDatabase = databases.find((d) => d.formattedName_.split('/').pop() === name);
     await existingDatabase?.delete();
@@ -27,11 +40,63 @@ export async function createDatabase(options = {}) {
     return database;
 }
 /**
- * Returns a {@link NestJsModuleOverrider} that overrides the {@link Database} provider with the provided database.
- *
- * @param database The temporary database to use.
- * @returns The {@link NestJsModuleOverrider} to override the {@link Database} provider.
+ * A {@link Fixture} that creates a temporary Spanner database and injects it into the NestJS application.
+ * The specified tables will be cleared after each test.
  */
-export function overrideDatabase(database) {
-    return (builder) => builder.overrideProvider(Database).useValue(database);
+export class SpannerFixture {
+    /**
+     * The name of the temporary database.
+     */
+    name;
+    /**
+     * If `sourceDatabaseName` is provided, its DDL will be copied into the new database, otherwise it will try to copy
+     * the DDL from `process.env.SPANNER_DATABASE`.
+     * If `null`, no schema will be set on the created database.
+     */
+    sourceDatabaseName;
+    /**
+     * The Spanner client to use for tests.
+     */
+    spanner;
+    /**
+     * The Spanner instance to use for tests.
+     * By default, a new Spanner client will be created using the `SPANNER_INSTANCE` environment variable.
+     */
+    instance;
+    /**
+     * Types of entities (Spanner tables) to clear.
+     */
+    types;
+    /**
+     * The {@link SpannerEntityManager} used to clear tables.
+     */
+    entityManager;
+    /**
+     * The temporary test database created by this fixture.
+     */
+    database;
+    constructor(options = {}) {
+        const { name, sourceDatabaseName, spanner, instance } = makeDatabaseParameters(options);
+        this.name = name;
+        this.sourceDatabaseName = sourceDatabaseName;
+        this.spanner = spanner;
+        this.instance = instance;
+        this.types = options.types ?? [];
+    }
+    async init() {
+        this.database = await createDatabase(this);
+        this.entityManager = new SpannerEntityManager(this.database);
+        return (builder) => builder.overrideProvider(Database).useValue(this.database);
+    }
+    async clear() {
+        await this.entityManager.transaction(async (transaction) => {
+            for (const entity of this.types) {
+                await this.entityManager.clear(entity, { transaction });
+            }
+        });
+    }
+    async delete() {
+        await this.database.delete();
+        this.spanner.close();
+    }
 }

package/dist/spanner/types.d.ts

@@ -1,10 +1,4 @@
 import type { SpannerReadOnlyTransaction, SpannerReadWriteTransaction } from './entity-manager.js';
-/**
- * A partial Spanner entity instance, where nested objects can also be partial.
- */
-export type RecursivePartialEntity<T> = T extends Date ? T : T extends object ? Partial<T> | {
-    [P in keyof T]?: RecursivePartialEntity<T[P]>;
-} : T;
 /**
  * Option for a function that accepts a Spanner read-only transaction.
  */

package/dist/testing.d.ts

@@ -1,7 +1,41 @@
+import { type Fixture } from '@causa/runtime/nestjs/testing';
+import type { Type } from '@nestjs/common';
+import { FirestorePubSubTransactionRunner, SpannerOutboxTransactionRunner } from './transaction/index.js';
 export * from './app-check/testing.js';
 export * from './firebase/testing.js';
 export * from './firestore/testing.js';
 export * from './identity-platform/testing.js';
-export * from './pubsub/testing/index.js';
+export * from './pubsub/testing.js';
 export * from './spanner/testing.js';
-export * from './testing/index.js';
+/**
+ * Creates a NestJS application using the specified module, and sets up the fixture.
+ *
+ * @param appModule The NestJS module to create the application from.
+ * @param options Options when creating the GCP resources for the fixture.
+ * @returns The {@link GoogleAppFixture}.
+ */
+export declare function createGoogleFixtures(options?: {
+    /**
+     * Temporary Pub/Sub topics to create using the {@link PubSubFixture}.
+     */
+    pubSubTopics?: Record<string, Type>;
+    /**
+     * Temporary Firestore collections to create and to clear during teardown.
+     */
+    firestoreTypes?: Type[];
+    /**
+     * Spanner entities to clear during teardown.
+     */
+    spannerTypes?: Type[];
+    /**
+     * Whether the `AppCheckGuard` should be disabled.
+     * Defaults to `true`.
+     */
+    disableAppCheck?: boolean;
+    /**
+     * The transaction runner to use with the created {@link VersionedEntityFixture}.
+     * Defaults to {@link SpannerOutboxTransactionRunner}.
+     * If `null`, no versioned entity fixture is created.
+     */
+    versionedEntityRunner?: Type<SpannerOutboxTransactionRunner> | Type<FirestorePubSubTransactionRunner> | null;
+}): Fixture[];

package/dist/testing.js

@@ -1,7 +1,38 @@
+import {} from '@causa/runtime/nestjs/testing';
+import { VersionedEntityFixture } from '@causa/runtime/testing';
+import { FirestoreFixture } from './firestore/testing.js';
+import { AuthUsersFixture } from './identity-platform/testing.js';
+import { PubSubFixture } from './pubsub/testing.js';
+import { SpannerFixture } from './spanner/testing.js';
+import { AppCheckFixture, FirebaseFixture } from './testing.js';
+import { FirestorePubSubTransactionRunner, SpannerOutboxTransactionRunner, } from './transaction/index.js';
 export * from './app-check/testing.js';
 export * from './firebase/testing.js';
 export * from './firestore/testing.js';
 export * from './identity-platform/testing.js';
-export * from './pubsub/testing/index.js';
+export * from './pubsub/testing.js';
 export * from './spanner/testing.js';
-export * from './testing/index.js';
+/**
+ * Creates a NestJS application using the specified module, and sets up the fixture.
+ *
+ * @param appModule The NestJS module to create the application from.
+ * @param options Options when creating the GCP resources for the fixture.
+ * @returns The {@link GoogleAppFixture}.
+ */
+export function createGoogleFixtures(options = {}) {
+    const disableAppCheck = options.disableAppCheck ?? true;
+    const versionedEntityFixture = options.versionedEntityRunner !== null
+        ? [
+            new VersionedEntityFixture(options.versionedEntityRunner ?? SpannerOutboxTransactionRunner, PubSubFixture),
+        ]
+        : [];
+    return [
+        new FirebaseFixture(),
+        new AuthUsersFixture(),
+        new FirestoreFixture(options.firestoreTypes ?? []),
+        new SpannerFixture({ types: options.spannerTypes }),
+        new PubSubFixture(options.pubSubTopics ?? {}),
+        ...(disableAppCheck ? [new AppCheckFixture()] : []),
+        ...versionedEntityFixture,
+    ];
+}

package/dist/transaction/firestore-pubsub/index.d.ts

@@ -1,6 +1,7 @@
 export { FirestorePubSubTransactionModule } from './module.js';
+export * from './readonly-state-transaction.js';
 export { FirestorePubSubTransactionRunner } from './runner.js';
 export { SoftDeletedFirestoreCollection } from './soft-deleted-collection.decorator.js';
 export { FirestoreStateTransaction } from './state-transaction.js';
-export type { FirestoreCollectionResolver, FirestoreCollectionsForDocumentType, } from './state-transaction.js';
-export { FirestorePubSubTransaction } from './transaction.js';
+export * from './transaction.js';
+export type { FirestoreCollectionResolver, FirestoreCollectionsForDocumentType, } from './types.js';

package/dist/transaction/firestore-pubsub/index.js

@@ -1,5 +1,6 @@
 export { FirestorePubSubTransactionModule } from './module.js';
+export * from './readonly-state-transaction.js';
 export { FirestorePubSubTransactionRunner } from './runner.js';
 export { SoftDeletedFirestoreCollection } from './soft-deleted-collection.decorator.js';
 export { FirestoreStateTransaction } from './state-transaction.js';
-export { FirestorePubSubTransaction } from './transaction.js';
+export * from './transaction.js';

package/dist/transaction/firestore-pubsub/nestjs-collection-resolver.d.ts

@@ -1,6 +1,6 @@
 import { type Type } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
-import { type FirestoreCollectionResolver, type FirestoreCollectionsForDocumentType } from './state-transaction.js';
+import type { FirestoreCollectionResolver, FirestoreCollectionsForDocumentType } from './types.js';
 /**
  * A {@link FirestoreCollectionResolver} that uses NestJS dependency injection to resolve Firestore collections.
  */

package/dist/transaction/firestore-pubsub/nestjs-collection-resolver.js

@@ -13,7 +13,6 @@ import { CollectionReference } from 'firebase-admin/firestore';
 import { makeFirestoreDataConverter } from '../../firestore/index.js';
 import { getFirestoreCollectionInjectionName } from '../../firestore/inject-collection.decorator.js';
 import { getSoftDeletedFirestoreCollectionMetadataForType } from './soft-deleted-collection.decorator.js';
-import {} from './state-transaction.js';
 /**
  * A {@link FirestoreCollectionResolver} that uses NestJS dependency injection to resolve Firestore collections.
  */

package/dist/transaction/firestore-pubsub/readonly-state-transaction.d.ts

@@ -0,0 +1,37 @@
+import type { ReadOnlyStateTransaction, ReadOnlyTransactionOption } from '@causa/runtime';
+import type { Type } from '@nestjs/common';
+import { Transaction } from 'firebase-admin/firestore';
+import type { FirestoreCollectionResolver } from './types.js';
+/**
+ * Option for a function that accepts a {@link FirestoreReadOnlyStateTransaction}.
+ */
+export type FirestoreReadOnlyStateTransactionOption = ReadOnlyTransactionOption<FirestoreReadOnlyStateTransaction>;
+/**
+ * A {@link ReadOnlyStateTransaction} that uses Firestore for state storage.
+ *
+ * This transaction handles soft-deleted documents if the class is decorated with `SoftDeletedFirestoreCollection`,
+ * which means that documents with a `deletedAt` field set to a non-null value are considered deleted.
+ *
+ * {@link FirestoreStateTransaction.get} will return the document from either the regular or soft-delete collection, as
+ * expected by {@link ReadOnlyStateTransaction.get}.
+ */
+export declare class FirestoreReadOnlyStateTransaction implements ReadOnlyStateTransaction {
+    /**
+     * The Firestore transaction to use.
+     */
+    readonly firestoreTransaction: Transaction;
+    /**
+     * The resolver that provides the Firestore collections for a given document type.
+     */
+    readonly collectionResolver: FirestoreCollectionResolver;
+    constructor(
+    /**
+     * The Firestore transaction to use.
+     */
+    firestoreTransaction: Transaction, 
+    /**
+     * The resolver that provides the Firestore collections for a given document type.
+     */
+    collectionResolver: FirestoreCollectionResolver);
+    get<T extends object>(type: Type<T>, entity: Partial<T>): Promise<T | undefined>;
+}

package/dist/transaction/firestore-pubsub/readonly-state-transaction.js

@@ -0,0 +1,46 @@
+import { Transaction } from 'firebase-admin/firestore';
+import { getReferenceForFirestoreDocument } from '../../firestore/index.js';
+/**
+ * A {@link ReadOnlyStateTransaction} that uses Firestore for state storage.
+ *
+ * This transaction handles soft-deleted documents if the class is decorated with `SoftDeletedFirestoreCollection`,
+ * which means that documents with a `deletedAt` field set to a non-null value are considered deleted.
+ *
+ * {@link FirestoreStateTransaction.get} will return the document from either the regular or soft-delete collection, as
+ * expected by {@link ReadOnlyStateTransaction.get}.
+ */
+export class FirestoreReadOnlyStateTransaction {
+    firestoreTransaction;
+    collectionResolver;
+    constructor(
+    /**
+     * The Firestore transaction to use.
+     */
+    firestoreTransaction, 
+    /**
+     * The resolver that provides the Firestore collections for a given document type.
+     */
+    collectionResolver) {
+        this.firestoreTransaction = firestoreTransaction;
+        this.collectionResolver = collectionResolver;
+    }
+    async get(type, entity) {
+        const { activeCollection, softDelete } = this.collectionResolver.getCollectionsForType(type);
+        const activeDocRef = getReferenceForFirestoreDocument(activeCollection, entity, type);
+        const activeSnapshot = await this.firestoreTransaction.get(activeDocRef);
+        if (activeSnapshot.exists) {
+            return activeSnapshot.data();
+        }
+        if (!softDelete) {
+            return undefined;
+        }
+        const deletedDocRef = getReferenceForFirestoreDocument(softDelete.collection, entity, type);
+        const deletedSnapshot = await this.firestoreTransaction.get(deletedDocRef);
+        if (!deletedSnapshot.exists) {
+            return undefined;
+        }
+        const deletedDocument = deletedSnapshot.data();
+        delete deletedDocument[softDelete.expirationField];
+        return deletedDocument;
+    }
+}

package/dist/transaction/firestore-pubsub/runner.d.ts

@@ -1,9 +1,10 @@
-import { TransactionRunner } from '@causa/runtime';
+import { TransactionRunner, type ReadWriteTransactionOptions, type TransactionFn } from '@causa/runtime';
 import { Logger } from '@causa/runtime/nestjs';
 import { Firestore } from '@google-cloud/firestore';
 import { PubSubPublisher } from '../../pubsub/index.js';
-import { type FirestoreCollectionResolver } from './state-transaction.js';
+import { FirestoreReadOnlyStateTransaction } from './readonly-state-transaction.js';
 import { FirestorePubSubTransaction } from './transaction.js';
+import type { FirestoreCollectionResolver } from './types.js';
 /**
  * A {@link TransactionRunner} that uses Firestore for state and Pub/Sub for events.
  * A Firestore transaction is used as the main transaction. If it succeeds, events are published to Pub/Sub outside of
@@ -11,11 +12,12 @@ import { FirestorePubSubTransaction } from './transaction.js';
  * This runner and the transaction use the {@link FirestoreStateTransaction}, which handles soft-deleted documents. All
  * entities that are written to the state should be decorated with the `SoftDeletedFirestoreCollection` decorator.
  */
-export declare class FirestorePubSubTransactionRunner extends TransactionRunner<FirestorePubSubTransaction> {
+export declare class FirestorePubSubTransactionRunner extends TransactionRunner<FirestorePubSubTransaction, FirestoreReadOnlyStateTransaction> {
     readonly firestore: Firestore;
     readonly pubSubPublisher: PubSubPublisher;
     readonly collectionResolver: FirestoreCollectionResolver;
     private readonly logger;
     constructor(firestore: Firestore, pubSubPublisher: PubSubPublisher, collectionResolver: FirestoreCollectionResolver, logger: Logger);
-    run<T>(runFn: (transaction: FirestorePubSubTransaction) => Promise<T>): Promise<[T]>;
+    protected runReadWrite<RT>(options: ReadWriteTransactionOptions, runFn: TransactionFn<FirestorePubSubTransaction, RT>): Promise<RT>;
+    protected runReadOnly<RT>(runFn: TransactionFn<FirestoreReadOnlyStateTransaction, RT>): Promise<RT>;
 }

package/dist/transaction/firestore-pubsub/runner.js

@@ -8,13 +8,14 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 var FirestorePubSubTransactionRunner_1;
-import { BufferEventTransaction, TransactionRunner } from '@causa/runtime';
+import { OutboxEventTransaction, TransactionRunner, } from '@causa/runtime';
 import { Logger } from '@causa/runtime/nestjs';
 import { Firestore } from '@google-cloud/firestore';
 import { Injectable } from '@nestjs/common';
 import { wrapFirestoreOperation } from '../../firestore/index.js';
 import { PubSubPublisher } from '../../pubsub/index.js';
-import { FirestoreStateTransaction, } from './state-transaction.js';
+import { FirestoreReadOnlyStateTransaction } from './readonly-state-transaction.js';
+import { FirestoreStateTransaction } from './state-transaction.js';
 import { FirestorePubSubTransaction } from './transaction.js';
 /**
  * A {@link TransactionRunner} that uses Firestore for state and Pub/Sub for events.
@@ -36,19 +37,27 @@ let FirestorePubSubTransactionRunner = FirestorePubSubTransactionRunner_1 = clas
         this.logger = logger;
         this.logger.setContext(FirestorePubSubTransactionRunner_1.name);
     }
-    async run(runFn) {
+    async runReadWrite(options, runFn) {
         this.logger.info('Creating a Firestore Pub/Sub transaction.');
         const { result, eventTransaction } = await wrapFirestoreOperation(() => this.firestore.runTransaction(async (firestoreTransaction) => {
             const stateTransaction = new FirestoreStateTransaction(firestoreTransaction, this.collectionResolver);
-            const eventTransaction = new BufferEventTransaction(this.pubSubPublisher);
+            const eventTransaction = new OutboxEventTransaction(this.pubSubPublisher, options.publishOptions);
             const transaction = new FirestorePubSubTransaction(stateTransaction, eventTransaction);
             const result = await runFn(transaction);
             this.logger.info('Committing the Firestore transaction.');
             return { result, eventTransaction };
         }));
-        this.logger.info('Publishing Pub/Sub events.');
-        await eventTransaction.commit();
-        return [result];
+        if (eventTransaction.events.length > 0) {
+            this.logger.info('Publishing Pub/Sub events.');
+            await Promise.all(eventTransaction.events.map((e) => this.pubSubPublisher.publish(e)));
+        }
+        return result;
+    }
+    async runReadOnly(runFn) {
+        return await wrapFirestoreOperation(() => this.firestore.runTransaction(async (firestoreTransaction) => {
+            const transaction = new FirestoreReadOnlyStateTransaction(firestoreTransaction, this.collectionResolver);
+            return await runFn(transaction);
+        }, { readOnly: true }));
     }
 };
 FirestorePubSubTransactionRunner = FirestorePubSubTransactionRunner_1 = __decorate([

package/dist/transaction/firestore-pubsub/state-transaction.d.ts

@@ -1,62 +1,24 @@
-import type { FindReplaceStateTransaction } from '@causa/runtime';
+import type { StateTransaction } from '@causa/runtime';
 import type { Type } from '@nestjs/common';
-import { CollectionReference, Transaction } from 'firebase-admin/firestore';
-import type { SoftDeletedFirestoreCollectionMetadata } from './soft-deleted-collection.decorator.js';
+import { FirestoreReadOnlyStateTransaction } from './readonly-state-transaction.js';
 /**
- * The Firestore collections that should be used to create document references for a given document type.
- */
-export type FirestoreCollectionsForDocumentType<T> = {
-    /**
-     * The regular collection, where documents are stored when they are not deleted.
-     */
-    readonly activeCollection: CollectionReference<T>;
-    /**
-     * Configuration about the soft-delete collection, where documents are stored when their `deletedAt` field is not
-     * `null`. This can be `null` if the document type does not declare a soft-delete collection.
-     */
-    readonly softDelete: ({
-        /**
-         * The collection where soft-deleted documents are stored.
-         */
-        collection: CollectionReference<T>;
-    } & Pick<SoftDeletedFirestoreCollectionMetadata, 'expirationDelay' | 'expirationField'>) | null;
-};
-/**
- * A resolver that returns the Firestore collections for a given document type.
- * This allows using the {@link FirestoreStateTransaction} in various contexts, such as in a NestJS module. It also
- * enables testing with temporary collections.
- */
-export interface FirestoreCollectionResolver {
-    /**
-     * Returns the Firestore collections for a given document type.
-     *
-     * @param documentType The type of document.
-     * @returns The Firestore collections for the given document type.
-     */
-    getCollectionsForType<T>(documentType: Type<T>): FirestoreCollectionsForDocumentType<T>;
-}
-/**
- * A {@link FindReplaceStateTransaction} that uses Firestore for state storage.
+ * A {@link StateTransaction} that uses Firestore for state storage.
  *
  * This transaction handles soft-deleted documents if the class is decorated with `SoftDeletedFirestoreCollection`,
  * which means that documents with a `deletedAt` field set to a non-null value are considered deleted.
  * Soft-deleted documents are moved to a separate collection, where they are kept for a configurable amount of time
  * before being permanently deleted. See the `SoftDeletedFirestoreCollection` decorator for more information.
  *
- * {@link FirestoreStateTransaction.deleteWithSameKeyAs} will delete the document from any of the regular or soft-delete
- * collections. It does not throw an error if the document does not exist.
+ * {@link FirestoreStateTransaction.delete} will delete the document from any of the regular or soft-delete collections.
+ * It does not throw an error if the document does not exist.
  *
- * {@link FirestoreStateTransaction.findOneWithSameKeyAs} will return the document from either the regular or
- * soft-delete collection, as expected by {@link FindReplaceStateTransaction.findOneWithSameKeyAs}.
+ * {@link FirestoreStateTransaction.get} will return the document from either the regular or soft-delete collection, as
+ * expected by {@link StateTransaction.get}.
  *
- * {@link FirestoreStateTransaction.replace} will set the document in the relevant collection, either the regular or
+ * {@link FirestoreStateTransaction.set} will set the document in the relevant collection, either the regular or
  * soft-delete collection depending on the value of the `deletedAt` field.
  */
-export declare class FirestoreStateTransaction implements FindReplaceStateTransaction {
-    readonly transaction: Transaction;
-    readonly collectionResolver: FirestoreCollectionResolver;
-    constructor(transaction: Transaction, collectionResolver: FirestoreCollectionResolver);
-    deleteWithSameKeyAs<T extends object>(type: Type<T>, key: Partial<T>): Promise<void>;
-    findOneWithSameKeyAs<T extends object>(type: Type<T>, entity: Partial<T>): Promise<T | undefined>;
-    replace<T extends object>(entity: T): Promise<void>;
+export declare class FirestoreStateTransaction extends FirestoreReadOnlyStateTransaction implements StateTransaction {
+    delete<T extends object>(typeOrEntity: Type<T> | T, key?: Partial<T>): Promise<void>;
+    set<T extends object>(entity: T): Promise<void>;
 }

package/dist/transaction/firestore-pubsub/state-transaction.js

@@ -1,65 +1,42 @@
 import { plainToInstance } from 'class-transformer';
-import { CollectionReference, Transaction } from 'firebase-admin/firestore';
 import { getReferenceForFirestoreDocument } from '../../firestore/index.js';
+import { FirestoreReadOnlyStateTransaction } from './readonly-state-transaction.js';
 /**
- * A {@link FindReplaceStateTransaction} that uses Firestore for state storage.
+ * A {@link StateTransaction} that uses Firestore for state storage.
  *
  * This transaction handles soft-deleted documents if the class is decorated with `SoftDeletedFirestoreCollection`,
  * which means that documents with a `deletedAt` field set to a non-null value are considered deleted.
  * Soft-deleted documents are moved to a separate collection, where they are kept for a configurable amount of time
  * before being permanently deleted. See the `SoftDeletedFirestoreCollection` decorator for more information.
  *
- * {@link FirestoreStateTransaction.deleteWithSameKeyAs} will delete the document from any of the regular or soft-delete
- * collections. It does not throw an error if the document does not exist.
+ * {@link FirestoreStateTransaction.delete} will delete the document from any of the regular or soft-delete collections.
+ * It does not throw an error if the document does not exist.
  *
- * {@link FirestoreStateTransaction.findOneWithSameKeyAs} will return the document from either the regular or
- * soft-delete collection, as expected by {@link FindReplaceStateTransaction.findOneWithSameKeyAs}.
+ * {@link FirestoreStateTransaction.get} will return the document from either the regular or soft-delete collection, as
+ * expected by {@link StateTransaction.get}.
  *
- * {@link FirestoreStateTransaction.replace} will set the document in the relevant collection, either the regular or
+ * {@link FirestoreStateTransaction.set} will set the document in the relevant collection, either the regular or
  * soft-delete collection depending on the value of the `deletedAt` field.
  */
-export class FirestoreStateTransaction {
-    transaction;
-    collectionResolver;
-    constructor(transaction, collectionResolver) {
-        this.transaction = transaction;
-        this.collectionResolver = collectionResolver;
-    }
-    async deleteWithSameKeyAs(type, key) {
+export class FirestoreStateTransaction extends FirestoreReadOnlyStateTransaction {
+    async delete(typeOrEntity, key) {
+        const type = (key === undefined ? typeOrEntity.constructor : typeOrEntity);
+        key ??= typeOrEntity;
         const { activeCollection, softDelete } = this.collectionResolver.getCollectionsForType(type);
         const activeDocRef = getReferenceForFirestoreDocument(activeCollection, key, type);
-        this.transaction.delete(activeDocRef);
+        this.firestoreTransaction.delete(activeDocRef);
         if (!softDelete) {
             return;
         }
         const deletedDocRef = getReferenceForFirestoreDocument(softDelete.collection, key, type);
-        this.transaction.delete(deletedDocRef);
-    }
-    async findOneWithSameKeyAs(type, entity) {
-        const { activeCollection, softDelete } = this.collectionResolver.getCollectionsForType(type);
-        const activeDocRef = getReferenceForFirestoreDocument(activeCollection, entity, type);
-        const activeSnapshot = await this.transaction.get(activeDocRef);
-        if (activeSnapshot.exists) {
-            return activeSnapshot.data();
-        }
-        if (!softDelete) {
-            return undefined;
-        }
-        const deletedDocRef = getReferenceForFirestoreDocument(softDelete.collection, entity, type);
-        const deletedSnapshot = await this.transaction.get(deletedDocRef);
-        if (!deletedSnapshot.exists) {
-            return undefined;
-        }
-        const deletedDocument = deletedSnapshot.data();
-        delete deletedDocument[softDelete.expirationField];
-        return deletedDocument;
+        this.firestoreTransaction.delete(deletedDocRef);
     }
-    async replace(entity) {
+    async set(entity) {
         const documentType = entity.constructor;
         const { activeCollection, softDelete } = this.collectionResolver.getCollectionsForType(documentType);
         const activeDocRef = getReferenceForFirestoreDocument(activeCollection, entity);
         if (!softDelete) {
-            this.transaction.set(activeDocRef, entity);
+            this.firestoreTransaction.set(activeDocRef, entity);
             return;
         }
         const deletedDocRef = getReferenceForFirestoreDocument(softDelete.collection, entity);
@@ -70,12 +47,12 @@ export class FirestoreStateTransaction {
                 ...entity,
                 [expirationField]: expiresAt,
             });
-            this.transaction.delete(activeDocRef);
-            this.transaction.set(deletedDocRef, deletedDoc);
+            this.firestoreTransaction.delete(activeDocRef);
+            this.firestoreTransaction.set(deletedDocRef, deletedDoc);
         }
         else {
-            this.transaction.set(activeDocRef, entity);
-            this.transaction.delete(deletedDocRef);
+            this.firestoreTransaction.set(activeDocRef, entity);
+            this.firestoreTransaction.delete(deletedDocRef);
         }
     }
 }

package/dist/transaction/firestore-pubsub/transaction.d.ts

@@ -1,12 +1,24 @@
-import { BufferEventTransaction, Transaction } from '@causa/runtime';
+import { OutboxEventTransaction, Transaction, type PublishOptions, type TransactionOption } from '@causa/runtime';
+import type { Type } from '@nestjs/common';
 import { Transaction as FirestoreTransaction } from 'firebase-admin/firestore';
-import { FirestoreStateTransaction } from './state-transaction.js';
+import type { FirestoreStateTransaction } from './state-transaction.js';
+/**
+ * Option for a function that accepts a {@link FirestorePubSubTransaction}.
+ */
+export type FirestoreOutboxTransactionOption = TransactionOption<FirestorePubSubTransaction>;
 /**
  * A {@link Transaction} that uses Firestore for state storage and Pub/Sub for event publishing.
  */
-export declare class FirestorePubSubTransaction extends Transaction<FirestoreStateTransaction, BufferEventTransaction> {
+export declare class FirestorePubSubTransaction extends Transaction {
+    readonly stateTransaction: FirestoreStateTransaction;
+    private readonly eventTransaction;
+    constructor(stateTransaction: FirestoreStateTransaction, eventTransaction: OutboxEventTransaction, publishOptions?: PublishOptions);
     /**
      * The underlying {@link FirestoreTransaction} used by the state transaction.
      */
     get firestoreTransaction(): FirestoreTransaction;
+    set<T extends object>(entity: T): Promise<void>;
+    delete<T extends object>(type: Type<T> | T, key?: Partial<T>): Promise<void>;
+    get<T extends object>(type: Type<T>, entity: Partial<T>): Promise<T | undefined>;
+    publish(topic: string, event: object, options?: PublishOptions): Promise<void>;
 }

package/dist/transaction/firestore-pubsub/transaction.js

@@ -1,14 +1,32 @@
-import { BufferEventTransaction, Transaction } from '@causa/runtime';
+import { OutboxEventTransaction, Transaction, } from '@causa/runtime';
 import { Transaction as FirestoreTransaction } from 'firebase-admin/firestore';
-import { FirestoreStateTransaction } from './state-transaction.js';
 /**
  * A {@link Transaction} that uses Firestore for state storage and Pub/Sub for event publishing.
  */
 export class FirestorePubSubTransaction extends Transaction {
+    stateTransaction;
+    eventTransaction;
+    constructor(stateTransaction, eventTransaction, publishOptions = {}) {
+        super(publishOptions);
+        this.stateTransaction = stateTransaction;
+        this.eventTransaction = eventTransaction;
+    }
     /**
      * The underlying {@link FirestoreTransaction} used by the state transaction.
      */
     get firestoreTransaction() {
-        return this.stateTransaction.transaction;
+        return this.stateTransaction.firestoreTransaction;
+    }
+    set(entity) {
+        return this.stateTransaction.set(entity);
+    }
+    delete(type, key) {
+        return this.stateTransaction.delete(type, key);
+    }
+    get(type, entity) {
+        return this.stateTransaction.get(type, entity);
+    }
+    publish(topic, event, options) {
+        return this.eventTransaction.publish(topic, event, options);
     }
 }