@causa/runtime-google 0.36.0 → 0.37.1

package/dist/spanner/entity-manager.d.ts

@@ -3,7 +3,7 @@ import { type Type as ParamType } from '@google-cloud/spanner/build/src/codec.js
 import type { TimestampBounds } from '@google-cloud/spanner/build/src/transaction.js';
 import { type Type } from '@nestjs/common';
 import { SpannerTableCache } from './table-cache.js';
-import type { RecursivePartialEntity } from './types.js';
+import type { RecursivePartialEntity, SpannerReadOnlyTransactionOption, SpannerReadWriteTransactionOption } from './types.js';
 /**
  * Any Spanner transaction that can be used for reading.
  */
@@ -16,24 +16,6 @@ export type SpannerReadWriteTransaction = Transaction;
  * A key for a Spanner row.
  */
 export type SpannerKey = (string | null)[];
-/**
- * Base options for all write operations.
- */
-type WriteOperationOptions = {
-    /**
-     * The {@link SpannerReadWriteTransaction} to use.
-     */
-    transaction?: SpannerReadWriteTransaction;
-};
-/**
- * Base options for all read operations.
- */
-type ReadOperationOptions = {
-    /**
-     * The {@link SpannerReadOnlyTransaction} to use.
-     */
-    transaction?: SpannerReadOnlyTransaction;
-};
 /**
  * Options for {@link SpannerEntityManager.snapshot}.
  */
@@ -67,7 +49,7 @@ export type SqlStatement = {
 /**
  * Options for {@link SpannerEntityManager.query}.
  */
-export type QueryOptions<T> = ReadOperationOptions & {
+export type QueryOptions<T> = SpannerReadOnlyTransactionOption & {
     /**
      * The type of entity to return in the list of results.
      */
@@ -76,7 +58,7 @@ export type QueryOptions<T> = ReadOperationOptions & {
 /**
  * Options when reading entities.
  */
-type FindOptions = ReadOperationOptions & {
+type FindOptions = SpannerReadOnlyTransactionOption & {
     /**
      * The index to use to look up the entity.
      */
@@ -231,7 +213,7 @@ export declare class SpannerEntityManager {
      * @param entityType The type of entity for which the table should be cleared.
      * @param options The options to use when running the operation.
      */
-    clear(entityType: Type, options?: WriteOperationOptions): Promise<void>;
+    clear(entityType: Type, options?: SpannerReadWriteTransactionOption): Promise<void>;
     /**
      * Runs the given SQL statement in the database.
      * By default, the statement is run in a {@link SpannerReadOnlyTransaction}. To perform a write operation, pass a
@@ -276,7 +258,7 @@ export declare class SpannerEntityManager {
      * @param entity The entity or array of entities to insert.
      * @param options Options for the operation.
      */
-    insert(entity: object | object[], options?: WriteOperationOptions): Promise<void>;
+    insert(entity: object | object[], options?: SpannerReadWriteTransactionOption): Promise<void>;
     /**
      * Replaces the given entities in the database.
      * If the entity already exists, all columns are overwritten, even if they are not present in the entity (in the case
@@ -288,7 +270,7 @@ export declare class SpannerEntityManager {
      * @param entity The entity to write.
      * @param options Options for the operation.
      */
-    replace(entity: object | object[], options?: WriteOperationOptions): Promise<void>;
+    replace(entity: object | object[], options?: SpannerReadWriteTransactionOption): Promise<void>;
     /**
      * Updates the given entity in the database.
      *
@@ -306,7 +288,7 @@ export declare class SpannerEntityManager {
      * @param options Options for the operation.
      * @returns The updated entity.
      */
-    update<T>(entityType: Type<T>, update: RecursivePartialEntity<T>, options?: WriteOperationOptions & Pick<FindOptions, 'includeSoftDeletes'> & {
+    update<T>(entityType: Type<T>, update: RecursivePartialEntity<T>, options?: SpannerReadWriteTransactionOption & Pick<FindOptions, 'includeSoftDeletes'> & {
         /**
          * A function that will be called with the entity before it is updated.
          * This function can throw an error to prevent the update.
@@ -327,7 +309,7 @@ export declare class SpannerEntityManager {
      * @param options Options for the operation.
      * @returns The deleted entity.
      */
-    delete<T>(entityType: Type<T>, key: SpannerKey | SpannerKey[number], options?: WriteOperationOptions & Pick<FindOptions, 'includeSoftDeletes'> & {
+    delete<T>(entityType: Type<T>, key: SpannerKey | SpannerKey[number], options?: SpannerReadWriteTransactionOption & Pick<FindOptions, 'includeSoftDeletes'> & {
         /**
          * A function that will be called with the entity before it is deleted.
          * This function can throw an error to prevent the deletion.

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 SpannerReadWriteTransactionOption = {
+    /**
+     * The transaction to use.
+     */
+    readonly transaction?: SpannerReadWriteTransaction;
+};

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.36.0",
+  "version": "0.37.1",
   "description": "An extension to the Causa runtime SDK (`@causa/runtime`), providing Google-specific features.",
   "repository": "github:causa-io/runtime-typescript-google",
   "license": "ISC",
@@ -35,9 +35,9 @@
     "@google-cloud/spanner": "^7.18.1",
     "@google-cloud/tasks": "^5.5.2",
     "@grpc/grpc-js": "^1.12.6",
-    "@nestjs/common": "^11.0.9",
+    "@nestjs/common": "^11.0.10",
     "@nestjs/config": "^4.0.0",
-    "@nestjs/core": "^11.0.9",
+    "@nestjs/core": "^11.0.10",
     "@nestjs/passport": "^11.0.5",
     "@nestjs/terminus": "^11.0.0",
     "class-transformer": "^0.5.1",
@@ -50,8 +50,8 @@
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
-    "@nestjs/testing": "^11.0.9",
-    "@swc/core": "^1.10.16",
+    "@nestjs/testing": "^11.0.10",
+    "@swc/core": "^1.10.17",
     "@swc/jest": "^0.2.37",
     "@tsconfig/node22": "^22.0.0",
     "@types/jest": "^29.5.14",
@@ -71,7 +71,7 @@
     "ts-jest": "^29.2.5",
     "ts-node": "^10.9.2",
     "typescript": "^5.7.3",
-    "typescript-eslint": "^8.24.0",
+    "typescript-eslint": "^8.24.1",
     "uuid": "^11.0.5"
   }
 }