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

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);
     }
 }

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

@@ -0,0 +1,36 @@
+import type { Type } from '@nestjs/common';
+import type { CollectionReference } from 'firebase-admin/firestore';
+import type { SoftDeletedFirestoreCollectionMetadata } from './soft-deleted-collection.decorator.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>;
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/transaction/index.d.ts

@@ -1,5 +1,2 @@
 export * from './firestore-pubsub/index.js';
 export * from './spanner-outbox/index.js';
-export * from './spanner-pubsub/index.js';
-export { SpannerStateTransaction } from './spanner-state-transaction.js';
-export { SpannerTransaction } from './spanner-transaction.js';

package/dist/transaction/index.js

@@ -1,5 +1,2 @@
 export * from './firestore-pubsub/index.js';
 export * from './spanner-outbox/index.js';
-export * from './spanner-pubsub/index.js';
-export { SpannerStateTransaction } from './spanner-state-transaction.js';
-export { SpannerTransaction } from './spanner-transaction.js';

package/dist/transaction/spanner-outbox/index.d.ts

@@ -1,5 +1,7 @@
 export { SpannerOutboxEvent } from './event.js';
 export { SpannerOutboxTransactionModule } from './module.js';
+export * from './readonly-transaction.js';
 export { SpannerOutboxTransactionRunner } from './runner.js';
-export type { SpannerOutboxTransaction, SpannerOutboxTransactionOption, } from './runner.js';
 export { SpannerOutboxSender } from './sender.js';
+export { SpannerStateTransaction } from './state-transaction.js';
+export * from './transaction.js';

package/dist/transaction/spanner-outbox/index.js

@@ -1,4 +1,7 @@
 export { SpannerOutboxEvent } from './event.js';
 export { SpannerOutboxTransactionModule } from './module.js';
+export * from './readonly-transaction.js';
 export { SpannerOutboxTransactionRunner } from './runner.js';
 export { SpannerOutboxSender } from './sender.js';
+export { SpannerStateTransaction } from './state-transaction.js';
+export * from './transaction.js';

package/dist/transaction/spanner-outbox/readonly-transaction.d.ts

@@ -0,0 +1,22 @@
+import type { ReadOnlyStateTransaction, ReadOnlyTransactionOption } from '@causa/runtime';
+import type { Type } from '@nestjs/common';
+import { SpannerEntityManager, type SpannerReadOnlyTransaction, type SpannerReadWriteTransaction } from '../../spanner/index.js';
+/**
+ * Option for a function that accepts a {@link SpannerReadOnlyStateTransaction}.
+ */
+export type SpannerReadOnlyStateTransactionOption = ReadOnlyTransactionOption<SpannerReadOnlyStateTransaction>;
+/**
+ * A {@link ReadOnlyStateTransaction} that uses Spanner for state storage.
+ */
+export declare class SpannerReadOnlyStateTransaction implements ReadOnlyStateTransaction {
+    readonly entityManager: SpannerEntityManager;
+    readonly spannerTransaction: SpannerReadWriteTransaction | SpannerReadOnlyTransaction;
+    /**
+     * Creates a new {@link SpannerReadOnlyStateTransaction}.
+     *
+     * @param entityManager The {@link SpannerEntityManager} to use to access entities in the state.
+     * @param spannerTransaction The {@link SpannerReadWriteTransaction} or {@link SpannerReadOnlyTransaction} to use.
+     */
+    constructor(entityManager: SpannerEntityManager, spannerTransaction: SpannerReadWriteTransaction | SpannerReadOnlyTransaction);
+    get<T extends object>(type: Type<T>, entity: Partial<T>): Promise<T | undefined>;
+}

package/dist/transaction/spanner-outbox/readonly-transaction.js

@@ -0,0 +1,25 @@
+import { SpannerEntityManager, } from '../../spanner/index.js';
+/**
+ * A {@link ReadOnlyStateTransaction} that uses Spanner for state storage.
+ */
+export class SpannerReadOnlyStateTransaction {
+    entityManager;
+    spannerTransaction;
+    /**
+     * Creates a new {@link SpannerReadOnlyStateTransaction}.
+     *
+     * @param entityManager The {@link SpannerEntityManager} to use to access entities in the state.
+     * @param spannerTransaction The {@link SpannerReadWriteTransaction} or {@link SpannerReadOnlyTransaction} to use.
+     */
+    constructor(entityManager, spannerTransaction) {
+        this.entityManager = entityManager;
+        this.spannerTransaction = spannerTransaction;
+    }
+    async get(type, entity) {
+        const primaryKey = this.entityManager.getPrimaryKey(entity, type);
+        return await this.entityManager.findOneByKey(type, primaryKey, {
+            transaction: this.spannerTransaction,
+            includeSoftDeletes: true,
+        });
+    }
+}

package/dist/transaction/spanner-outbox/runner.d.ts

@@ -1,28 +1,17 @@
-import { OutboxTransactionRunner, type OutboxEvent, type OutboxEventTransaction } from '@causa/runtime';
+import { OutboxTransactionRunner, type OutboxEvent, type OutboxEventTransaction, type ReadWriteTransactionOptions, type TransactionFn } from '@causa/runtime';
 import { Logger } from '@causa/runtime/nestjs';
 import type { Type } from '@nestjs/common';
 import { SpannerEntityManager } from '../../spanner/index.js';
-import { SpannerTransaction } from '../spanner-transaction.js';
+import { SpannerReadOnlyStateTransaction } from './readonly-transaction.js';
 import { SpannerOutboxSender } from './sender.js';
+import { SpannerOutboxTransaction } from './transaction.js';
 /**
- * A {@link SpannerTransaction} that uses an {@link OutboxEventTransaction}.
- */
-export type SpannerOutboxTransaction = SpannerTransaction<OutboxEventTransaction>;
-/**
- * Option for a function that accepts a {@link SpannerOutboxTransaction}.
- */
-export type SpannerOutboxTransactionOption = {
-    /**
-     * The transaction to use.
-     */
-    readonly transaction?: SpannerOutboxTransaction;
-};
-/**
- * An {@link OutboxTransactionRunner} that uses a {@link SpannerTransaction} to run transactions.
+ * An {@link OutboxTransactionRunner} that uses a {@link SpannerOutboxTransaction} to run transactions.
  * Events are stored in a Spanner table before being published.
  */
-export declare class SpannerOutboxTransactionRunner extends OutboxTransactionRunner<SpannerOutboxTransaction> {
+export declare class SpannerOutboxTransactionRunner extends OutboxTransactionRunner<SpannerOutboxTransaction, SpannerReadOnlyStateTransaction> {
     readonly entityManager: SpannerEntityManager;
     constructor(entityManager: SpannerEntityManager, outboxEventType: Type<OutboxEvent>, sender: SpannerOutboxSender, logger: Logger);
-    protected runStateTransaction<RT>(eventTransactionFactory: () => OutboxEventTransaction, runFn: (transaction: SpannerOutboxTransaction) => Promise<RT>): Promise<RT>;
+    protected runReadOnly<RT>(runFn: TransactionFn<SpannerReadOnlyStateTransaction, RT>): Promise<RT>;
+    protected runStateTransaction<RT>(eventTransactionFactory: () => OutboxEventTransaction, options: ReadWriteTransactionOptions, runFn: TransactionFn<SpannerOutboxTransaction, RT>): Promise<RT>;
 }

package/dist/transaction/spanner-outbox/runner.js

@@ -1,12 +1,13 @@
 import { OutboxTransactionRunner, } from '@causa/runtime';
 import { Logger } from '@causa/runtime/nestjs';
 import { SpannerEntityManager } from '../../spanner/index.js';
-import { SpannerStateTransaction } from '../spanner-state-transaction.js';
-import { SpannerTransaction } from '../spanner-transaction.js';
-import { throwRetryableInTransactionIfNeeded } from '../spanner-utils.js';
+import { SpannerReadOnlyStateTransaction } from './readonly-transaction.js';
 import { SpannerOutboxSender } from './sender.js';
+import { throwRetryableInTransactionIfNeeded } from './spanner-utils.js';
+import { SpannerStateTransaction } from './state-transaction.js';
+import { SpannerOutboxTransaction } from './transaction.js';
 /**
- * An {@link OutboxTransactionRunner} that uses a {@link SpannerTransaction} to run transactions.
+ * An {@link OutboxTransactionRunner} that uses a {@link SpannerOutboxTransaction} to run transactions.
  * Events are stored in a Spanner table before being published.
  */
 export class SpannerOutboxTransactionRunner extends OutboxTransactionRunner {
@@ -15,11 +16,17 @@ export class SpannerOutboxTransactionRunner extends OutboxTransactionRunner {
         super(outboxEventType, sender, logger);
         this.entityManager = entityManager;
     }
-    async runStateTransaction(eventTransactionFactory, runFn) {
+    async runReadOnly(runFn) {
+        return await this.entityManager.snapshot(async (dbTransaction) => {
+            const transaction = new SpannerReadOnlyStateTransaction(this.entityManager, dbTransaction);
+            return await runFn(transaction);
+        });
+    }
+    async runStateTransaction(eventTransactionFactory, options, runFn) {
         return await this.entityManager.transaction(async (dbTransaction) => {
             const stateTransaction = new SpannerStateTransaction(this.entityManager, dbTransaction);
             const eventTransaction = eventTransactionFactory();
-            const transaction = new SpannerTransaction(stateTransaction, eventTransaction);
+            const transaction = new SpannerOutboxTransaction(stateTransaction, eventTransaction, options.publishOptions);
             try {
                 return await runFn(transaction);
             }

package/dist/transaction/{spanner-utils.js → spanner-outbox/spanner-utils.js}

@@ -1,6 +1,6 @@
 import { TransactionOldTimestampError } from '@causa/runtime';
 import { setTimeout } from 'timers/promises';
-import { TemporarySpannerError } from '../spanner/index.js';
+import { TemporarySpannerError } from '../../spanner/index.js';
 /**
  * The delay, in milliseconds, over which a timestamp issue is deemed irrecoverable.
  */

package/dist/transaction/spanner-outbox/state-transaction.d.ts

@@ -0,0 +1,20 @@
+import type { StateTransaction } from '@causa/runtime';
+import type { Type } from '@nestjs/common';
+import { SpannerEntityManager, type SpannerReadWriteTransaction } from '../../spanner/index.js';
+import { SpannerReadOnlyStateTransaction } from './readonly-transaction.js';
+/**
+ * A {@link StateTransaction} that uses Spanner for state storage.
+ */
+export declare class SpannerStateTransaction extends SpannerReadOnlyStateTransaction implements StateTransaction {
+    readonly entityManager: SpannerEntityManager;
+    readonly spannerTransaction: SpannerReadWriteTransaction;
+    /**
+     * Creates a new {@link SpannerStateTransaction}.
+     *
+     * @param entityManager The {@link SpannerEntityManager} to use to access entities in the state.
+     * @param spannerTransaction The {@link SpannerReadWriteTransaction} to use for the transaction.
+     */
+    constructor(entityManager: SpannerEntityManager, spannerTransaction: SpannerReadWriteTransaction);
+    set<T extends object>(entity: T): Promise<void>;
+    delete<T extends object>(typeOrEntity: Type<T> | T, key?: Partial<T>): Promise<void>;
+}

package/dist/transaction/spanner-outbox/state-transaction.js

@@ -0,0 +1,34 @@
+import { SpannerEntityManager, } from '../../spanner/index.js';
+import { SpannerReadOnlyStateTransaction } from './readonly-transaction.js';
+/**
+ * A {@link StateTransaction} that uses Spanner for state storage.
+ */
+export class SpannerStateTransaction extends SpannerReadOnlyStateTransaction {
+    entityManager;
+    spannerTransaction;
+    /**
+     * Creates a new {@link SpannerStateTransaction}.
+     *
+     * @param entityManager The {@link SpannerEntityManager} to use to access entities in the state.
+     * @param spannerTransaction The {@link SpannerReadWriteTransaction} to use for the transaction.
+     */
+    constructor(entityManager, spannerTransaction) {
+        super(entityManager, spannerTransaction);
+        this.entityManager = entityManager;
+        this.spannerTransaction = spannerTransaction;
+    }
+    async set(entity) {
+        await this.entityManager.replace(entity, {
+            transaction: this.spannerTransaction,
+        });
+    }
+    async delete(typeOrEntity, key) {
+        const type = (key === undefined ? typeOrEntity.constructor : typeOrEntity);
+        key ??= typeOrEntity;
+        const primaryKey = this.entityManager.getPrimaryKey(key, type);
+        await this.entityManager.delete(type, primaryKey, {
+            transaction: this.spannerTransaction,
+            includeSoftDeletes: true,
+        });
+    }
+}

package/dist/transaction/spanner-outbox/transaction.d.ts

@@ -0,0 +1,28 @@
+import { OutboxEventTransaction, Transaction, type OutboxTransaction, type PublishOptions, type TransactionOption } from '@causa/runtime';
+import type { Type } from '@nestjs/common';
+import { SpannerEntityManager, type SpannerReadWriteTransaction } from '../../spanner/index.js';
+import type { SpannerStateTransaction } from './state-transaction.js';
+/**
+ * Option for a function that accepts a {@link SpannerOutboxTransaction}.
+ */
+export type SpannerOutboxTransactionOption = TransactionOption<SpannerOutboxTransaction>;
+/**
+ * A {@link Transaction} that uses Spanner for state (and outbox) storage, and Pub/Sub for event publishing.
+ */
+export declare class SpannerOutboxTransaction extends Transaction implements OutboxTransaction {
+    readonly stateTransaction: SpannerStateTransaction;
+    readonly eventTransaction: OutboxEventTransaction;
+    constructor(stateTransaction: SpannerStateTransaction, eventTransaction: OutboxEventTransaction, publishOptions?: PublishOptions);
+    /**
+     * The underlying {@link SpannerTransaction} used by the state transaction.
+     */
+    get spannerTransaction(): SpannerReadWriteTransaction;
+    /**
+     * The underlying {@link SpannerEntityManager} used by the state transaction.
+     */
+    get entityManager(): SpannerEntityManager;
+    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>;
+}