@causa/runtime-google 0.35.4 → 0.37.0

package/dist/spanner/types.d.ts

@@ -1,6 +1,25 @@
+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.
+ */
+export type SpannerReadOnlyTransactionOption = {
+    /**
+     * The transaction to use.
+     */
+    readonly transaction?: SpannerReadOnlyTransaction;
+};
+/**
+ * Option for a function that accepts a Spanner read-write transaction.
+ */
+export type SpanerReadWriteTransactionOption = {
+    /**
+     * The transaction to use.
+     */
+    readonly transaction?: SpannerReadWriteTransaction;
+};

package/dist/testing/google-app-fixture.d.ts

@@ -1,7 +1,7 @@
 import type { VersionedEntity } from '@causa/runtime';
 import { type MakeTestAppFactoryOptions } from '@causa/runtime/nestjs/testing';
 import { Database, Spanner } from '@google-cloud/spanner';
-import type { INestApplication, Type } from '@nestjs/common';
+import type { INestApplication, NestApplicationOptions, Type } from '@nestjs/common';
 import { CollectionReference } from 'firebase-admin/firestore';
 import { Test } from 'supertest';
 import TestAgent from 'supertest/lib/agent.js';
@@ -177,6 +177,10 @@ export declare class GoogleAppFixture {
          * Options for the {@link makeTestAppFactory} function.
          */
         appFactoryOptions?: MakeTestAppFactoryOptions;
+        /**
+         * Options passed to the NestJS application factory.
+         */
+        nestApplicationOptions?: NestApplicationOptions;
         /**
          * Whether the `AppCheckGuard` should be disabled.
          * Defaults to `true`.

package/dist/testing/google-app-fixture.js

@@ -180,6 +180,7 @@ export class GoogleAppFixture {
             ? [appFactoryOptions.overrides]
             : (appFactoryOptions.overrides ?? []);
         const app = await createApp(appModule, {
+            nestApplicationOptions: options.nestApplicationOptions,
             appFactory: makeTestAppFactory({
                 ...appFactoryOptions,
                 overrides: [

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

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

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

@@ -8,6 +8,15 @@ import { SpannerOutboxSender } from './sender.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.
  * Events are stored in a Spanner table before being published.

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

@@ -63,9 +63,15 @@ export declare class SpannerOutboxSender extends OutboxEventSender {
      */
     readonly index: string | undefined;
     /**
-     * The SQL query used to fetch events from the outbox.
+     * The SQL query used to fetch (non-leased) events from the outbox.
+     * This should be run in a read-only transaction to avoid table-wide locking.
      */
     readonly fetchEventsSql: string;
+    /**
+     * The SQL query used to acquire a lease on events in the outbox.
+     * This is based on event IDs, that are checked again to have a null lease expiration.
+     */
+    readonly acquireLeaseSql: string;
     /**
      * The SQL query used to update events in the outbox after they have been successfully published.
      */
@@ -89,7 +95,7 @@ export declare class SpannerOutboxSender extends OutboxEventSender {
      *
      * @returns The SQL queries used to fetch and update events in the outbox.
      */
-    protected buildSql(): Pick<SpannerOutboxSender, 'fetchEventsSql' | 'successfulUpdateSql' | 'failedUpdateSql'>;
+    protected buildSql(): Pick<SpannerOutboxSender, 'fetchEventsSql' | 'acquireLeaseSql' | 'successfulUpdateSql' | 'failedUpdateSql'>;
     protected fetchEvents(): Promise<OutboxEvent[]>;
     protected updateOutbox(result: OutboxEventPublishResult): Promise<void>;
 }

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

@@ -33,9 +33,15 @@ export class SpannerOutboxSender extends OutboxEventSender {
      */
     index;
     /**
-     * The SQL query used to fetch events from the outbox.
+     * The SQL query used to fetch (non-leased) events from the outbox.
+     * This should be run in a read-only transaction to avoid table-wide locking.
      */
     fetchEventsSql;
+    /**
+     * The SQL query used to acquire a lease on events in the outbox.
+     * This is based on event IDs, that are checked again to have a null lease expiration.
+     */
+    acquireLeaseSql;
     /**
      * The SQL query used to update events in the outbox after they have been successfully published.
      */
@@ -64,6 +70,7 @@ export class SpannerOutboxSender extends OutboxEventSender {
         this.index = options.index;
         ({
             fetchEventsSql: this.fetchEventsSql,
+            acquireLeaseSql: this.acquireLeaseSql,
             successfulUpdateSql: this.successfulUpdateSql,
             failedUpdateSql: this.failedUpdateSql,
         } = this.buildSql());
@@ -76,27 +83,32 @@ export class SpannerOutboxSender extends OutboxEventSender {
     buildSql() {
         const table = this.entityManager.sqlTableName(this.outboxEventType);
         const tableWithIndex = this.entityManager.sqlTableName(this.outboxEventType, { index: this.index });
-        let filter = `${this.leaseExpirationColumn} IS NULL OR ${this.leaseExpirationColumn} < @currentTime`;
+        const noLeaseFilter = `\`${this.leaseExpirationColumn}\` IS NULL OR \`${this.leaseExpirationColumn}\` < @currentTime`;
+        let fetchFilter = noLeaseFilter;
         if (this.sharding) {
             const { column, count } = this.sharding;
-            filter = `${column} BETWEEN 0 AND ${count - 1} AND (${filter})`;
+            fetchFilter = `\`${column}\` BETWEEN 0 AND ${count - 1} AND (${fetchFilter})`;
         }
         const fetchEventsSql = `
+      SELECT
+        \`${this.idColumn}\` AS id,
+      FROM
+        ${tableWithIndex}
+      WHERE
+        ${fetchFilter}
+      LIMIT
+        @batchSize
+    `;
+        // This will not be run in the same transaction as `fetchEventsSql`. The `noLeaseFilter` is re-applied to avoid
+        // acquiring a lease on outbox events that have since been leased by another process.
+        const acquireLeaseSql = `
       UPDATE
         ${table}
       SET
         \`${this.leaseExpirationColumn}\` = @leaseExpiration
       WHERE
-        \`${this.idColumn}\` IN (
-          SELECT
-            \`${this.idColumn}\`
-          FROM
-            ${tableWithIndex}
-          WHERE
-            ${filter}
-          LIMIT
-            @batchSize
-        )
+        \`${this.idColumn}\` IN UNNEST(@ids)
+        AND (${noLeaseFilter})
       THEN RETURN
         ${this.entityManager.sqlColumns(this.outboxEventType)}`;
         const successfulUpdateSql = `
@@ -111,18 +123,29 @@ export class SpannerOutboxSender extends OutboxEventSender {
         \`${this.leaseExpirationColumn}\` = NULL
       WHERE
         \`${this.idColumn}\` IN UNNEST(@ids)`;
-        return { fetchEventsSql, successfulUpdateSql, failedUpdateSql };
+        return {
+            fetchEventsSql,
+            acquireLeaseSql,
+            successfulUpdateSql,
+            failedUpdateSql,
+        };
     }
     async fetchEvents() {
+        // Event IDs are first acquired in an (implicit) read-only transaction, to avoid a lock on the entire table.
+        const currentTime = new Date();
+        const eventIds = await this.entityManager.query({
+            sql: this.fetchEventsSql,
+            params: { currentTime, batchSize: this.batchSize },
+        });
+        if (eventIds.length === 0) {
+            return [];
+        }
+        const ids = eventIds.map(({ id }) => id);
         return await this.entityManager.transaction(async (transaction) => {
             const currentTime = new Date();
             const leaseExpiration = new Date(currentTime.getTime() + this.leaseDuration);
-            const params = {
-                leaseExpiration,
-                currentTime,
-                batchSize: this.batchSize,
-            };
-            return await this.entityManager.query({ transaction, entityType: this.outboxEventType }, { sql: this.fetchEventsSql, params });
+            const params = { ids, leaseExpiration, currentTime };
+            return await this.entityManager.query({ transaction, entityType: this.outboxEventType }, { sql: this.acquireLeaseSql, params });
         });
     }
     async updateOutbox(result) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@causa/runtime-google",
-  "version": "0.35.4",
+  "version": "0.37.0",
   "description": "An extension to the Causa runtime SDK (`@causa/runtime`), providing Google-specific features.",
   "repository": "github:causa-io/runtime-typescript-google",
   "license": "ISC",
@@ -35,33 +35,33 @@
     "@google-cloud/spanner": "^7.18.1",
     "@google-cloud/tasks": "^5.5.2",
     "@grpc/grpc-js": "^1.12.6",
-    "@nestjs/common": "^11.0.8",
+    "@nestjs/common": "^11.0.9",
     "@nestjs/config": "^4.0.0",
-    "@nestjs/core": "^11.0.8",
+    "@nestjs/core": "^11.0.9",
     "@nestjs/passport": "^11.0.5",
     "@nestjs/terminus": "^11.0.0",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.1",
     "express": "^4.21.2",
-    "firebase-admin": "^13.0.2",
+    "firebase-admin": "^13.1.0",
     "jsonwebtoken": "^9.0.2",
     "passport-http-bearer": "^1.0.1",
     "pino": "^9.6.0",
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
-    "@nestjs/testing": "^11.0.8",
-    "@swc/core": "^1.10.14",
+    "@nestjs/testing": "^11.0.9",
+    "@swc/core": "^1.10.16",
     "@swc/jest": "^0.2.37",
     "@tsconfig/node22": "^22.0.0",
     "@types/jest": "^29.5.14",
     "@types/jsonwebtoken": "^9.0.8",
-    "@types/node": "^22.13.1",
+    "@types/node": "^22.13.4",
     "@types/passport-http-bearer": "^1.0.41",
     "@types/supertest": "^6.0.2",
     "@types/uuid": "^10.0.0",
     "dotenv": "^16.4.7",
-    "eslint": "^9.19.0",
+    "eslint": "^9.20.1",
     "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-prettier": "^5.2.3",
     "jest": "^29.7.0",
@@ -71,7 +71,7 @@
     "ts-jest": "^29.2.5",
     "ts-node": "^10.9.2",
     "typescript": "^5.7.3",
-    "typescript-eslint": "^8.23.0",
+    "typescript-eslint": "^8.24.0",
     "uuid": "^11.0.5"
   }
 }