@causa/runtime-google 0.37.1 → 0.38.0

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.1",
+  "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",
@@ -51,27 +51,27 @@
   },
   "devDependencies": {
     "@nestjs/testing": "^11.0.10",
-    "@swc/core": "^1.10.17",
+    "@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.1",
-    "uuid": "^11.0.5"
+    "typescript-eslint": "^8.25.0",
+    "uuid": "^11.1.0"
   }
 }