@causa/runtime-google 1.0.0 → 1.1.0

package/dist/pubsub/publisher.js

@@ -5,11 +5,10 @@ import { getConfigurationKeyForTopic } from './configuration.js';
 import { PubSubTopicNotConfiguredError } from './errors.js';
 /**
  * The default options to use when publishing messages.
- * Batching is disabled as the most common use case is to publish a single message at a time, for which latency is more
- * important than throughput.
+ * Batching is minimal, as latency should be prioritized over throughput.
  */
 const DEFAULT_PUBLISH_OPTIONS = {
-    batching: { maxMessages: 1 },
+    batching: { maxMilliseconds: 5 },
 };
 /**
  * An implementation of the {@link EventPublisher} using Google Pub/Sub as the broker.
@@ -117,26 +116,12 @@ export class PubSubPublisher {
         if (attributes && 'eventId' in attributes) {
             messageInfo.eventId = attributes.eventId;
         }
-        try {
-            const messageId = await pubSubTopic.publishMessage({
-                data,
-                attributes,
-                orderingKey: key,
-            });
-            this.logger.info({ publishedMessage: { ...messageInfo, messageId } }, 'Published message to Pub/Sub.');
-        }
-        catch (error) {
-            this.logger.error({
-                failedMessage: {
-                    ...messageInfo,
-                    data: data.toString('base64'),
-                    attributes,
-                    key,
-                },
-                error: error.stack,
-            }, 'Failed to publish message to Pub/Sub.');
-            throw error;
-        }
+        const messageId = await pubSubTopic.publishMessage({
+            data,
+            attributes,
+            orderingKey: key,
+        });
+        this.logger.info({ publishedMessage: { ...messageInfo, messageId } }, 'Published message to Pub/Sub.');
     }
     async flush() {
         await Promise.all(Object.values(this.topicCache).map((topic) => topic.flush()));

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

@@ -1,6 +1,6 @@
 import { Database, Snapshot, Transaction } from '@google-cloud/spanner';
 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 { ExecuteSqlRequest, TimestampBounds } from '@google-cloud/spanner/build/src/transaction.js';
 import { type Type } from '@nestjs/common';
 import { SpannerTableCache } from './table-cache.js';
 import type { SpannerReadOnlyTransactionOption, SpannerReadWriteTransactionOption } from './types.js';
@@ -53,7 +53,7 @@ export type SqlStatement = {
 /**
  * Options for {@link SpannerEntityManager.query}.
  */
-export type QueryOptions<T> = SpannerReadOnlyTransactionOption & {
+export type QueryOptions<T> = SpannerReadOnlyTransactionOption & Pick<ExecuteSqlRequest, 'requestOptions'> & {
     /**
      * The type of entity to return in the list of results.
      */
@@ -62,7 +62,7 @@ export type QueryOptions<T> = SpannerReadOnlyTransactionOption & {
 /**
  * Options when reading entities.
  */
-type FindOptions = SpannerReadOnlyTransactionOption & {
+type FindOptions = SpannerReadOnlyTransactionOption & Pick<ExecuteSqlRequest, 'requestOptions'> & {
     /**
      * The index to use to look up the entity.
      */

package/dist/spanner/entity-manager.js

@@ -141,6 +141,7 @@ let SpannerEntityManager = class SpannerEntityManager {
                 json: true,
                 jsonOptions: { wrapNumbers: true },
                 index: options.index,
+                requestOptions: options.requestOptions,
             });
             const row = rows[0];
             if (row && options.index && !options.columns) {
@@ -210,7 +211,7 @@ let SpannerEntityManager = class SpannerEntityManager {
             if (options.transaction) {
                 return await runFn(options.transaction);
             }
-            return await this.database.runTransactionAsync(async (transaction) => {
+            return await this.database.runTransactionAsync({ requestOptions: { transactionTag: options.tag } }, async (transaction) => {
                 try {
                     const result = await runFn(transaction);
                     if (transaction.ended) {
@@ -275,10 +276,11 @@ let SpannerEntityManager = class SpannerEntityManager {
             ? optionsOrStatement
             : {};
         const sqlStatement = statement ?? optionsOrStatement;
-        const { entityType } = options;
+        const { entityType, requestOptions } = options;
         return await this.snapshot({ transaction: options.transaction }, async (transaction) => {
             const [rows] = await transaction.run({
                 ...sqlStatement,
+                requestOptions,
                 json: true,
                 jsonOptions: { wrapNumbers: entityType != null },
             });

package/dist/spanner/types.d.ts

@@ -1,4 +1,6 @@
+import { protos } from '@google-cloud/spanner';
 import type { SpannerReadOnlyTransaction, SpannerReadWriteTransaction } from './entity-manager.js';
+export declare const SpannerRequestPriority: typeof protos.google.spanner.v1.RequestOptions.Priority;
 /**
  * Option for a function that accepts a Spanner read-only transaction.
  */
@@ -15,5 +17,15 @@ export type SpannerReadWriteTransactionOption = {
     /**
      * The transaction to use.
      */
-    readonly transaction?: SpannerReadWriteTransaction;
+    readonly transaction: SpannerReadWriteTransaction;
+} | {
+    /**
+     * The transaction to use.
+     */
+    readonly transaction?: undefined;
+    /**
+     * A tag to assign to the transaction.
+     * This can only be provided when creating a new transaction.
+     */
+    readonly tag?: string;
 };

package/dist/spanner/types.js

@@ -1 +1,2 @@
-export {};
+import { protos } from '@google-cloud/spanner';
+export const SpannerRequestPriority = protos.google.spanner.v1.RequestOptions.Priority;

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

@@ -1,6 +1,6 @@
 import { TransactionRunner, type ReadWriteTransactionOptions, type TransactionFn } from '@causa/runtime';
 import { Logger } from '@causa/runtime/nestjs';
-import { Firestore } from '@google-cloud/firestore';
+import { Firestore } from 'firebase-admin/firestore';
 import { PubSubPublisher } from '../../pubsub/index.js';
 import { FirestoreReadOnlyStateTransaction } from './readonly-state-transaction.js';
 import { FirestorePubSubTransaction } from './transaction.js';

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

@@ -10,8 +10,8 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var FirestorePubSubTransactionRunner_1;
 import { OutboxEventTransaction, TransactionRunner, } from '@causa/runtime';
 import { Logger } from '@causa/runtime/nestjs';
-import { Firestore } from '@google-cloud/firestore';
 import { Injectable } from '@nestjs/common';
+import { Firestore } from 'firebase-admin/firestore';
 import { wrapFirestoreOperation } from '../../firestore/index.js';
 import { PubSubPublisher } from '../../pubsub/index.js';
 import { FirestoreReadOnlyStateTransaction } from './readonly-state-transaction.js';

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

@@ -32,9 +32,14 @@ function parseSenderOptions(defaultOptions, customOptions, config) {
     const index = config.get('SPANNER_OUTBOX_INDEX');
     const shardingColumn = config.get('SPANNER_OUTBOX_SHARDING_COLUMN');
     const shardingCount = validateIntOrUndefined('SPANNER_OUTBOX_SHARDING_COUNT');
+    const shardingDisableRoundRobin = !!config.get('SPANNER_OUTBOX_SHARDING_DISABLE_ROUND_ROBIN');
     const leaseDuration = validateIntOrUndefined('SPANNER_OUTBOX_LEASE_DURATION');
     const sharding = shardingColumn && shardingCount
-        ? { column: shardingColumn, count: shardingCount }
+        ? {
+            column: shardingColumn,
+            count: shardingCount,
+            roundRobin: !shardingDisableRoundRobin,
+        }
         : undefined;
     const envOptionsWithUndefined = {
         batchSize,

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

@@ -1,10 +1,19 @@
-import { OutboxTransactionRunner, type OutboxEvent, type OutboxEventTransaction, type ReadWriteTransactionOptions, type TransactionFn } from '@causa/runtime';
+import { OutboxTransactionRunner, type OutboxEvent, type OutboxEventTransaction, type ReadOnlyTransactionOption, type ReadWriteTransactionOptions, type TransactionFn, type TransactionOption } from '@causa/runtime';
 import { Logger } from '@causa/runtime/nestjs';
 import type { Type } from '@nestjs/common';
 import { SpannerEntityManager } from '../../spanner/index.js';
 import { SpannerReadOnlyStateTransaction } from './readonly-transaction.js';
 import { SpannerOutboxSender } from './sender.js';
 import { SpannerOutboxTransaction } from './transaction.js';
+/**
+ * Options for a Spanner outbox transaction.
+ */
+export type SpannerOutboxReadWriteTransactionOptions = ReadWriteTransactionOptions & {
+    /**
+     * The Spanner tag to assign to the transaction.
+     */
+    tag?: string;
+};
 /**
  * An {@link OutboxTransactionRunner} that uses a {@link SpannerOutboxTransaction} to run transactions.
  * Events are stored in a Spanner table before being published.
@@ -13,5 +22,10 @@ export declare class SpannerOutboxTransactionRunner extends OutboxTransactionRun
     readonly entityManager: SpannerEntityManager;
     constructor(entityManager: SpannerEntityManager, outboxEventType: Type<OutboxEvent>, sender: SpannerOutboxSender, logger: Logger);
     protected runReadOnly<RT>(runFn: TransactionFn<SpannerReadOnlyStateTransaction, RT>): Promise<RT>;
-    protected runStateTransaction<RT>(eventTransactionFactory: () => OutboxEventTransaction, options: ReadWriteTransactionOptions, runFn: TransactionFn<SpannerOutboxTransaction, RT>): Promise<RT>;
+    protected runStateTransaction<RT>(eventTransactionFactory: () => OutboxEventTransaction, options: SpannerOutboxReadWriteTransactionOptions, runFn: TransactionFn<SpannerOutboxTransaction, RT>): Promise<RT>;
+    run<RT>(runFn: TransactionFn<SpannerOutboxTransaction, RT>): Promise<RT>;
+    run<RT>(options: TransactionOption<SpannerOutboxTransaction> | SpannerOutboxReadWriteTransactionOptions, runFn: TransactionFn<SpannerOutboxTransaction, RT>): Promise<RT>;
+    run<RT>(options: ReadOnlyTransactionOption<SpannerReadOnlyStateTransaction> & {
+        readOnly: true;
+    }, runFn: TransactionFn<SpannerReadOnlyStateTransaction, RT>): Promise<RT>;
 }

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

@@ -23,7 +23,7 @@ export class SpannerOutboxTransactionRunner extends OutboxTransactionRunner {
         });
     }
     async runStateTransaction(eventTransactionFactory, options, runFn) {
-        return await this.entityManager.transaction(async (dbTransaction) => {
+        return await this.entityManager.transaction({ tag: options.tag }, async (dbTransaction) => {
             const stateTransaction = new SpannerStateTransaction(this.entityManager, dbTransaction);
             const eventTransaction = eventTransactionFactory();
             const transaction = new SpannerOutboxTransaction(stateTransaction, eventTransaction, options.publishOptions);
@@ -36,4 +36,7 @@ export class SpannerOutboxTransactionRunner extends OutboxTransactionRunner {
             }
         });
     }
+    async run(optionsOrRunFn, runFn) {
+        return super.run(optionsOrRunFn, runFn);
+    }
 }

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

@@ -3,9 +3,9 @@ import { Logger } from '@causa/runtime/nestjs';
 import type { Type } from '@nestjs/common';
 import { SpannerEntityManager } from '../../spanner/index.js';
 /**
- * Sharding options for the {@link SpannerOutboxSender}.
+ * The sharding configuration for the {@link SpannerOutboxSender}.
  */
-export type SpannerOutboxSenderShardingOptions = {
+type SpannerOutboxSenderSharding = {
     /**
      * The name of the column used for sharding.
      */
@@ -14,7 +14,16 @@ export type SpannerOutboxSenderShardingOptions = {
      * The number of shards.
      */
     readonly count: number;
+    /**
+     * Whether events are fetched one shard at a time in a round-robin fashion, or all shards at once.
+     * Defaults to `true`.
+     */
+    readonly roundRobin: boolean;
 };
+/**
+ * Sharding options for the {@link SpannerOutboxSender}.
+ */
+export type SpannerOutboxSenderShardingOptions = Pick<SpannerOutboxSenderSharding, 'column' | 'count'> & Partial<SpannerOutboxSenderSharding>;
 /**
  * Options for the {@link SpannerOutboxSender}.
  */
@@ -49,7 +58,17 @@ export declare class SpannerOutboxSender extends OutboxEventSender {
      * Sharding options.
      * If `null`, queries to fetch events will not use sharding.
      */
-    readonly sharding: SpannerOutboxSenderShardingOptions | undefined;
+    readonly sharding: SpannerOutboxSenderSharding | undefined;
+    /**
+     * If sharding round-robin is enabled, the permutation of shard indices determining the order in which shards are
+     * queried by {@link SpannerOutboxSender.fetchEvents}.
+     */
+    private readonly shardsPermutation;
+    /**
+     * If sharding round-robin is enabled, the index of the next shard to query in
+     * {@link SpannerOutboxSender.fetchEvents}.
+     */
+    private shardsPermutationIndex;
     /**
      * The name of the column used for the {@link OutboxEvent.id} property.
      */
@@ -99,3 +118,4 @@ export declare class SpannerOutboxSender extends OutboxEventSender {
     protected fetchEvents(): Promise<OutboxEvent[]>;
     protected updateOutbox(result: OutboxEventPublishResult): Promise<void>;
 }
+export {};

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

@@ -1,6 +1,6 @@
 import { OutboxEventSender, } from '@causa/runtime';
 import { Logger } from '@causa/runtime/nestjs';
-import { SpannerEntityManager } from '../../spanner/index.js';
+import { SpannerEntityManager, SpannerRequestPriority, } from '../../spanner/index.js';
 /**
  * The default name for the {@link OutboxEvent.id} column.
  */
@@ -20,6 +20,16 @@ export class SpannerOutboxSender extends OutboxEventSender {
      * If `null`, queries to fetch events will not use sharding.
      */
     sharding;
+    /**
+     * If sharding round-robin is enabled, the permutation of shard indices determining the order in which shards are
+     * queried by {@link SpannerOutboxSender.fetchEvents}.
+     */
+    shardsPermutation;
+    /**
+     * If sharding round-robin is enabled, the index of the next shard to query in
+     * {@link SpannerOutboxSender.fetchEvents}.
+     */
+    shardsPermutationIndex;
     /**
      * The name of the column used for the {@link OutboxEvent.id} property.
      */
@@ -63,11 +73,19 @@ export class SpannerOutboxSender extends OutboxEventSender {
         super(publisher, logger, options);
         this.entityManager = entityManager;
         this.outboxEventType = outboxEventType;
-        this.sharding = options.sharding;
+        this.sharding = options.sharding
+            ? { roundRobin: true, ...options.sharding }
+            : undefined;
         this.idColumn = options.idColumn ?? DEFAULT_ID_COLUMN;
         this.leaseExpirationColumn =
             options.leaseExpirationColumn ?? DEFAULT_LEASE_EXPIRATION_COLUMN;
         this.index = options.index;
+        if (this.sharding?.roundRobin) {
+            this.shardsPermutation = Array.from({ length: this.sharding.count }, (_, i) => [i, Math.random()])
+                .sort(([, a], [, b]) => a - b)
+                .map(([i]) => i);
+            this.shardsPermutationIndex = 0;
+        }
         ({
             fetchEventsSql: this.fetchEventsSql,
             acquireLeaseSql: this.acquireLeaseSql,
@@ -86,8 +104,11 @@ export class SpannerOutboxSender extends OutboxEventSender {
         const noLeaseFilter = `\`${this.leaseExpirationColumn}\` IS NULL OR \`${this.leaseExpirationColumn}\` < @currentTime`;
         let fetchFilter = noLeaseFilter;
         if (this.sharding) {
-            const { column, count } = this.sharding;
-            fetchFilter = `\`${column}\` BETWEEN 0 AND ${count - 1} AND (${fetchFilter})`;
+            const { column, count, roundRobin } = this.sharding;
+            const shardFilter = (roundRobin ?? true)
+                ? `\`${column}\` = @shard`
+                : `\`${column}\` BETWEEN 0 AND ${count - 1}`;
+            fetchFilter = `(${shardFilter}) AND (${fetchFilter})`;
         }
         const fetchEventsSql = `
       SELECT
@@ -131,12 +152,17 @@ export class SpannerOutboxSender extends OutboxEventSender {
         };
     }
     async fetchEvents() {
+        const params = {
+            currentTime: new Date(),
+            batchSize: this.batchSize,
+        };
+        if (this.shardsPermutationIndex !== undefined && this.shardsPermutation) {
+            params.shard = this.shardsPermutation[this.shardsPermutationIndex];
+            this.shardsPermutationIndex =
+                (this.shardsPermutationIndex + 1) % this.shardsPermutation.length;
+        }
         // 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 },
-        });
+        const eventIds = await this.entityManager.query({ requestOptions: { priority: SpannerRequestPriority.PRIORITY_MEDIUM } }, { sql: this.fetchEventsSql, params });
         if (eventIds.length === 0) {
             return [];
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@causa/runtime-google",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "An extension to the Causa runtime SDK (`@causa/runtime`), providing Google-specific features.",
   "repository": {
     "type": "git",
@@ -35,7 +35,7 @@
     "@causa/runtime": "^1.0.0",
     "@google-cloud/precise-date": "^5.0.0",
     "@google-cloud/pubsub": "^5.1.0",
-    "@google-cloud/spanner": "^8.0.0",
+    "@google-cloud/spanner": "^8.1.0",
     "@google-cloud/tasks": "^6.2.0",
     "@grpc/grpc-js": "^1.13.4",
     "@nestjs/common": "^11.1.5",
@@ -54,28 +54,26 @@
   },
   "devDependencies": {
     "@nestjs/testing": "^11.1.5",
-    "@swc/core": "^1.13.0",
+    "@swc/core": "^1.13.3",
     "@swc/jest": "^0.2.39",
     "@tsconfig/node22": "^22.0.2",
     "@types/jest": "^30.0.0",
     "@types/jsonwebtoken": "^9.0.10",
-    "@types/node": "^22.16.4",
+    "@types/node": "^22.17.0",
     "@types/passport-http-bearer": "^1.0.41",
     "@types/supertest": "^6.0.3",
     "@types/uuid": "^10.0.0",
-    "dotenv": "^17.2.0",
-    "eslint": "^9.31.0",
-    "eslint-config-prettier": "^10.1.5",
-    "eslint-plugin-prettier": "^5.5.1",
-    "jest": "^30.0.4",
+    "dotenv": "^17.2.1",
+    "eslint": "^9.32.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.3",
+    "jest": "^30.0.5",
     "jest-extended": "^6.0.0",
-    "pino-pretty": "^13.0.0",
+    "pino-pretty": "^13.1.1",
     "rimraf": "^6.0.1",
-    "supertest": "^7.1.3",
-    "ts-jest": "^29.4.0",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.8.3",
-    "typescript-eslint": "^8.37.0",
+    "supertest": "^7.1.4",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.39.0",
     "uuid": "^11.1.0"
   }
 }