@causa/runtime-google 0.37.0 → 0.38.0

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

@@ -17,7 +17,7 @@ export type SpannerReadOnlyTransactionOption = {
 /**
  * Option for a function that accepts a Spanner read-write transaction.
  */
-export type SpanerReadWriteTransactionOption = {
+export type SpannerReadWriteTransactionOption = {
     /**
      * The transaction to use.
      */

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

@@ -11,11 +11,22 @@ import type { EventAttributes, OutboxEvent } from '@causa/runtime';
  *   data BYTES(MAX) NOT NULL,
  *   attributes JSON NOT NULL,
  *   leaseExpiration TIMESTAMP,
+ *   publishedAt TIMESTAMP,
  *   -- 20 is the number of shards.
  *   shard INT64 AS (MOD(ABS(FARM_FINGERPRINT(id)), 20)),
- * ) PRIMARY KEY (id);
- * CREATE INDEX OutboxEventsByShardAndLeaseExpiration ON OutboxEvent(shard, leaseExpiration)
+ * ) PRIMARY KEY (id)
+ * ROW DELETION POLICY (OLDER_THAN(publishedAt, INTERVAL 0 DAY));
+ * CREATE INDEX OutboxEventsByShardAndLeaseExpiration ON OutboxEvent(shard, leaseExpiration) STORING (publishedAt);
  * ```
+ *
+ * Compared to the {@link OutboxEvent} interface, this requires a `publishedAt` column to be defined, on which the row
+ * deletion policy should be set. This allows updating published events rather than deleting them directly.
+ * Updating published events allows setting the `leaseExpiration` column to a distant date, such that those events are
+ * not scanned when fetching events to publish.
+ * Because Spanner allows for version retention, recently deleted rows are still scanned (even as part of an efficient
+ * index scan). This can affect performances if the rows are not updated before being deleted, because the
+ * `leaseExpiration` date of published events would end up back in the scanned range - in the past (although rows are
+ * deleted and not returned).
  */
 export declare class SpannerOutboxEvent implements OutboxEvent {
     constructor(init: SpannerOutboxEvent);
@@ -24,4 +35,8 @@ export declare class SpannerOutboxEvent implements OutboxEvent {
     readonly data: Buffer;
     readonly attributes: EventAttributes;
     readonly leaseExpiration: Date | null;
+    /**
+     * The date at which the event was successfully published.
+     */
+    readonly publishedAt: Date | null;
 }

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

@@ -20,11 +20,22 @@ import { SpannerColumn, SpannerTable } from '../../spanner/index.js';
  *   data BYTES(MAX) NOT NULL,
  *   attributes JSON NOT NULL,
  *   leaseExpiration TIMESTAMP,
+ *   publishedAt TIMESTAMP,
  *   -- 20 is the number of shards.
  *   shard INT64 AS (MOD(ABS(FARM_FINGERPRINT(id)), 20)),
- * ) PRIMARY KEY (id);
- * CREATE INDEX OutboxEventsByShardAndLeaseExpiration ON OutboxEvent(shard, leaseExpiration)
+ * ) PRIMARY KEY (id)
+ * ROW DELETION POLICY (OLDER_THAN(publishedAt, INTERVAL 0 DAY));
+ * CREATE INDEX OutboxEventsByShardAndLeaseExpiration ON OutboxEvent(shard, leaseExpiration) STORING (publishedAt);
  * ```
+ *
+ * Compared to the {@link OutboxEvent} interface, this requires a `publishedAt` column to be defined, on which the row
+ * deletion policy should be set. This allows updating published events rather than deleting them directly.
+ * Updating published events allows setting the `leaseExpiration` column to a distant date, such that those events are
+ * not scanned when fetching events to publish.
+ * Because Spanner allows for version retention, recently deleted rows are still scanned (even as part of an efficient
+ * index scan). This can affect performances if the rows are not updated before being deleted, because the
+ * `leaseExpiration` date of published events would end up back in the scanned range - in the past (although rows are
+ * deleted and not returned).
  */
 let SpannerOutboxEvent = class SpannerOutboxEvent {
     constructor(init) {
@@ -35,6 +46,10 @@ let SpannerOutboxEvent = class SpannerOutboxEvent {
     data;
     attributes;
     leaseExpiration;
+    /**
+     * The date at which the event was successfully published.
+     */
+    publishedAt;
 };
 __decorate([
     SpannerColumn(),
@@ -56,6 +71,10 @@ __decorate([
     SpannerColumn(),
     __metadata("design:type", Object)
 ], SpannerOutboxEvent.prototype, "leaseExpiration", void 0);
+__decorate([
+    SpannerColumn(),
+    __metadata("design:type", Object)
+], SpannerOutboxEvent.prototype, "publishedAt", void 0);
 SpannerOutboxEvent = __decorate([
     SpannerTable({ name: 'OutboxEvent', primaryKey: ['id'] }),
     __metadata("design:paramtypes", [SpannerOutboxEvent])

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

@@ -1,5 +1,5 @@
-import type { OutboxEvent } from '@causa/runtime';
 import type { DynamicModule, Type } from '@nestjs/common';
+import { SpannerOutboxEvent } from './event.js';
 import { type SpannerOutboxSenderOptions } from './sender.js';
 /**
  * Options for the {@link SpannerOutboxTransactionModule}.
@@ -10,7 +10,7 @@ export type SpannerOutboxTransactionModuleOptions = SpannerOutboxSenderOptions &
      * This should be a valid class decorated with `@SpannerTable`.
      * Defaults to {@link SpannerOutboxEvent}.
      */
-    outboxEventType?: Type<OutboxEvent>;
+    outboxEventType?: Type<SpannerOutboxEvent>;
 };
 /**
  * The module providing the {@link SpannerOutboxTransactionRunner}.

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

@@ -29,6 +29,7 @@ function parseSenderOptions(defaultOptions, customOptions, config) {
     const pollingInterval = validateIntOrUndefined('SPANNER_OUTBOX_POLLING_INTERVAL');
     const idColumn = config.get('SPANNER_OUTBOX_ID_COLUMN');
     const leaseExpirationColumn = config.get('SPANNER_OUTBOX_LEASE_EXPIRATION_COLUMN');
+    const publishedAtColumn = config.get('SPANNER_OUTBOX_PUBLISHED_AT_COLUMN');
     const index = config.get('SPANNER_OUTBOX_INDEX');
     const shardingColumn = config.get('SPANNER_OUTBOX_SHARDING_COLUMN');
     const shardingCount = validateIntOrUndefined('SPANNER_OUTBOX_SHARDING_COUNT');
@@ -41,6 +42,7 @@ function parseSenderOptions(defaultOptions, customOptions, config) {
         pollingInterval,
         idColumn,
         leaseExpirationColumn,
+        publishedAtColumn,
         index,
         sharding,
         leaseDuration,

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

@@ -1,8 +1,9 @@
-import { OutboxTransactionRunner, type OutboxEvent, type OutboxEventTransaction } from '@causa/runtime';
+import { OutboxTransactionRunner, type OutboxEventTransaction } 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 type { SpannerOutboxEvent } from './event.js';
 import { SpannerOutboxSender } from './sender.js';
 /**
  * A {@link SpannerTransaction} that uses an {@link OutboxEventTransaction}.
@@ -23,6 +24,6 @@ export type SpannerOutboxTransactionOption = {
  */
 export declare class SpannerOutboxTransactionRunner extends OutboxTransactionRunner<SpannerOutboxTransaction> {
     readonly entityManager: SpannerEntityManager;
-    constructor(entityManager: SpannerEntityManager, outboxEventType: Type<OutboxEvent>, sender: SpannerOutboxSender, logger: Logger);
+    constructor(entityManager: SpannerEntityManager, outboxEventType: Type<SpannerOutboxEvent>, sender: SpannerOutboxSender, logger: Logger);
     protected runStateTransaction<RT>(eventTransactionFactory: () => OutboxEventTransaction, runFn: (transaction: SpannerOutboxTransaction) => Promise<RT>): Promise<RT>;
 }

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

@@ -34,6 +34,11 @@ export type SpannerOutboxSenderOptions = OutboxEventSenderOptions & {
      * Defaults to `leaseExpiration`.
      */
     readonly leaseExpirationColumn?: string;
+    /**
+     * The name of the column used to store the timestamp at which the event was published.
+     * Defaults to `publishedAt`.
+     */
+    readonly publishedAtColumn?: string;
     /**
      * The index used to fetch events.
      */
@@ -58,6 +63,10 @@ export declare class SpannerOutboxSender extends OutboxEventSender {
      * The name of the column used for the {@link OutboxEvent.leaseExpiration} property.
      */
     readonly leaseExpirationColumn: string;
+    /**
+     * The name of the column used for the {@link OutboxEvent.publishedAt} property.
+     */
+    readonly publishedAtColumn: string;
     /**
      * The index used to fetch events.
      */

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

@@ -9,6 +9,10 @@ const DEFAULT_ID_COLUMN = 'id';
  * The default name for the {@link OutboxEvent.leaseExpiration} column.
  */
 const DEFAULT_LEASE_EXPIRATION_COLUMN = 'leaseExpiration';
+/**
+ * The default name for the {@link OutboxEvent.publishedAt} column.
+ */
+const DEFAULT_PUBLISHED_AT_COLUMN = 'publishedAt';
 /**
  * An {@link OutboxEventSender} that uses a Spanner table to store events.
  */
@@ -28,6 +32,10 @@ export class SpannerOutboxSender extends OutboxEventSender {
      * The name of the column used for the {@link OutboxEvent.leaseExpiration} property.
      */
     leaseExpirationColumn;
+    /**
+     * The name of the column used for the {@link OutboxEvent.publishedAt} property.
+     */
+    publishedAtColumn;
     /**
      * The index used to fetch events.
      */
@@ -67,6 +75,8 @@ export class SpannerOutboxSender extends OutboxEventSender {
         this.idColumn = options.idColumn ?? DEFAULT_ID_COLUMN;
         this.leaseExpirationColumn =
             options.leaseExpirationColumn ?? DEFAULT_LEASE_EXPIRATION_COLUMN;
+        this.publishedAtColumn =
+            options.publishedAtColumn ?? DEFAULT_PUBLISHED_AT_COLUMN;
         this.index = options.index;
         ({
             fetchEventsSql: this.fetchEventsSql,
@@ -83,7 +93,11 @@ export class SpannerOutboxSender extends OutboxEventSender {
     buildSql() {
         const table = this.entityManager.sqlTableName(this.outboxEventType);
         const tableWithIndex = this.entityManager.sqlTableName(this.outboxEventType, { index: this.index });
-        const noLeaseFilter = `\`${this.leaseExpirationColumn}\` IS NULL OR \`${this.leaseExpirationColumn}\` < @currentTime`;
+        const noLeaseFilter = `(
+        \`${this.leaseExpirationColumn}\` IS NULL OR
+        \`${this.leaseExpirationColumn}\` < @currentTime
+      ) AND
+      \`${this.publishedAtColumn}\` IS NULL`;
         let fetchFilter = noLeaseFilter;
         if (this.sharding) {
             const { column, count } = this.sharding;
@@ -112,8 +126,11 @@ export class SpannerOutboxSender extends OutboxEventSender {
       THEN RETURN
         ${this.entityManager.sqlColumns(this.outboxEventType)}`;
         const successfulUpdateSql = `
-      DELETE FROM
+      UPDATE
         ${table}
+      SET
+        \`${this.leaseExpirationColumn}\` = '9999-12-31T00:00:00.000Z',
+        \`${this.publishedAtColumn}\` = @currentTime
       WHERE
         \`${this.idColumn}\` IN UNNEST(@ids)`;
         const failedUpdateSql = `
@@ -156,7 +173,7 @@ export class SpannerOutboxSender extends OutboxEventSender {
         if (successfulSends.length > 0) {
             batchUpdates.push({
                 sql: this.successfulUpdateSql,
-                params: { ids: successfulSends },
+                params: { ids: successfulSends, currentTime: new Date() },
             });
         }
         if (failedSends.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@causa/runtime-google",
-  "version": "0.37.0",
+  "version": "0.38.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,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,28 +50,28 @@
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
-    "@nestjs/testing": "^11.0.9",
-    "@swc/core": "^1.10.16",
+    "@nestjs/testing": "^11.0.10",
+    "@swc/core": "^1.11.1",
     "@swc/jest": "^0.2.37",
     "@tsconfig/node22": "^22.0.0",
     "@types/jest": "^29.5.14",
-    "@types/jsonwebtoken": "^9.0.8",
-    "@types/node": "^22.13.4",
+    "@types/jsonwebtoken": "^9.0.9",
+    "@types/node": "^22.13.5",
     "@types/passport-http-bearer": "^1.0.41",
     "@types/supertest": "^6.0.2",
     "@types/uuid": "^10.0.0",
     "dotenv": "^16.4.7",
-    "eslint": "^9.20.1",
+    "eslint": "^9.21.0",
     "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-prettier": "^5.2.3",
     "jest": "^29.7.0",
     "jest-extended": "^4.0.2",
     "rimraf": "^6.0.1",
     "supertest": "^7.0.0",
-    "ts-jest": "^29.2.5",
+    "ts-jest": "^29.2.6",
     "ts-node": "^10.9.2",
     "typescript": "^5.7.3",
-    "typescript-eslint": "^8.24.0",
-    "uuid": "^11.0.5"
+    "typescript-eslint": "^8.25.0",
+    "uuid": "^11.1.0"
   }
 }