@causa/runtime-google 1.1.0 → 1.3.0

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

@@ -114,6 +114,8 @@ export declare class SpannerEntityManager {
     /**
      * Returns the (quoted) name of the table for the given entity type.
      *
+     * @deprecated Use {@link sqlTable} instead.
+     *
      * @param entityTypeOrTable The type of entity, or the unquoted table name.
      * @param options Options when constructing the table name (e.g. the index to use).
      * @returns The name of the table, quoted with backticks.
@@ -130,6 +132,25 @@ export declare class SpannerEntityManager {
          */
         disableQueryNullFilteredIndexEmulatorCheck?: boolean;
     }): string;
+    /**
+     * Returns the (quoted) name of the table for the given entity type.
+     *
+     * @param entityTypeOrTable The type of entity, or the unquoted table name.
+     * @param options Options when constructing the table name (e.g. the index to use).
+     * @returns The name of the table, quoted with backticks.
+     */
+    sqlTable(entityTypeOrTable: Type | string, options?: {
+        /**
+         * Sets a table hint to indicate which index to use when querying the table.
+         * The value will be quoted with backticks.
+         */
+        index?: string;
+        /**
+         * Sets a table hint to disable the check that prevents queries from using null-filtered indexes.
+         * This is useful when using the emulator, which does not support null-filtered indexes.
+         */
+        disableQueryNullFilteredIndexEmulatorCheck?: boolean;
+    }): string;
     /**
      * Returns the (quoted) list of columns for the given entity type or list of columns.
      *
@@ -139,7 +160,16 @@ export declare class SpannerEntityManager {
      * @param entityTypeOrColumns The type of entity, or the unquoted list of columns.
      * @returns The list of columns, quoted with backticks and joined.
      */
-    sqlColumns(entityTypeOrColumns: Type | string[]): string;
+    sqlColumns<T = unknown>(entityTypeOrColumns: Type<T> | string[], options?: {
+        /**
+         * If `entityTypeOrColumns` is a type, only the columns for the given properties will be included.
+         */
+        forProperties?: T extends object ? (keyof T & string)[] : never;
+        /**
+         * The alias with which to prefix each column.
+         */
+        alias?: string;
+    }): string;
     /**
      * Fetches a single row from the database using its key (either primary or for a secondary index).
      *

package/dist/spanner/entity-manager.js

@@ -73,11 +73,23 @@ let SpannerEntityManager = class SpannerEntityManager {
     /**
      * Returns the (quoted) name of the table for the given entity type.
      *
+     * @deprecated Use {@link sqlTable} instead.
+     *
      * @param entityTypeOrTable The type of entity, or the unquoted table name.
      * @param options Options when constructing the table name (e.g. the index to use).
      * @returns The name of the table, quoted with backticks.
      */
     sqlTableName(entityTypeOrTable, options = {}) {
+        return this.sqlTable(entityTypeOrTable, options);
+    }
+    /**
+     * Returns the (quoted) name of the table for the given entity type.
+     *
+     * @param entityTypeOrTable The type of entity, or the unquoted table name.
+     * @param options Options when constructing the table name (e.g. the index to use).
+     * @returns The name of the table, quoted with backticks.
+     */
+    sqlTable(entityTypeOrTable, options = {}) {
         const tableHints = {};
         if (options.index) {
             tableHints.FORCE_INDEX = `\`${options.index}\``;
@@ -89,9 +101,10 @@ let SpannerEntityManager = class SpannerEntityManager {
         const tableHintsString = Object.entries(tableHints)
             .map(([k, v]) => `${k}=${v}`)
             .join(',');
-        const quotedTableName = typeof entityTypeOrTable === 'string'
-            ? `\`${entityTypeOrTable}\``
-            : this.tableCache.getMetadata(entityTypeOrTable).quotedTableName;
+        const tableName = typeof entityTypeOrTable === 'string'
+            ? entityTypeOrTable
+            : this.tableCache.getMetadata(entityTypeOrTable).tableName;
+        const quotedTableName = `\`${tableName}\``;
         return tableHintsString.length > 0
             ? `${quotedTableName}@{${tableHintsString}}`
             : quotedTableName;
@@ -105,11 +118,22 @@ let SpannerEntityManager = class SpannerEntityManager {
      * @param entityTypeOrColumns The type of entity, or the unquoted list of columns.
      * @returns The list of columns, quoted with backticks and joined.
      */
-    sqlColumns(entityTypeOrColumns) {
+    sqlColumns(entityTypeOrColumns, options = {}) {
+        let columns;
         if (Array.isArray(entityTypeOrColumns)) {
-            return entityTypeOrColumns.map((c) => `\`${c}\``).join(', ');
+            columns = entityTypeOrColumns;
         }
-        return this.tableCache.getMetadata(entityTypeOrColumns).quotedColumns;
+        else {
+            const { columnNames } = this.tableCache.getMetadata(entityTypeOrColumns);
+            columns = options.forProperties
+                ? options.forProperties.map((p) => columnNames[p])
+                : Object.values(columnNames);
+        }
+        columns = columns.map((c) => `\`${c}\``);
+        if (options.alias) {
+            columns = columns.map((c) => `\`${options.alias}\`.${c}`);
+        }
+        return columns.join(', ');
     }
     /**
      * Fetches a single row from the database using its key (either primary or for a secondary index).
@@ -131,8 +155,9 @@ let SpannerEntityManager = class SpannerEntityManager {
         if (!Array.isArray(key)) {
             key = [key];
         }
-        const { tableName, columns: allColumns, primaryKeyColumns, softDeleteColumn, } = this.tableCache.getMetadata(entityType);
-        const columns = options.columns ?? (options.index ? primaryKeyColumns : allColumns);
+        const { tableName, columnNames, primaryKeyColumns, softDeleteColumn } = this.tableCache.getMetadata(entityType);
+        const columns = options.columns ??
+            (options.index ? primaryKeyColumns : Object.values(columnNames));
         return await this.snapshot({ transaction: options.transaction }, async (transaction) => {
             const [rows] = await transaction.read(tableName, {
                 keys: [key],
@@ -266,10 +291,8 @@ let SpannerEntityManager = class SpannerEntityManager {
      * @param options The options to use when running the operation.
      */
     async clear(entityType, options = {}) {
-        const { quotedTableName } = this.tableCache.getMetadata(entityType);
-        await this.transaction(options, (transaction) => transaction.runUpdate({
-            sql: `DELETE FROM ${quotedTableName} WHERE TRUE`,
-        }));
+        const { tableName } = this.tableCache.getMetadata(entityType);
+        await this.transaction(options, (transaction) => transaction.runUpdate(`DELETE FROM \`${tableName}\` WHERE TRUE`));
     }
     async query(optionsOrStatement, statement) {
         const options = statement

package/dist/spanner/index.d.ts

@@ -1,7 +1,7 @@
 export { SpannerColumn } from './column.decorator.js';
-export { SPANNER_SESSION_POOL_OPTIONS_FOR_CLOUD_FUNCTIONS, SPANNER_SESSION_POOL_OPTIONS_FOR_SERVICE, catchSpannerDatabaseErrors, getDefaultSpannerDatabaseForCloudFunction, } from './database.js';
+export { catchSpannerDatabaseErrors, getDefaultSpannerDatabaseForCloudFunction, SPANNER_SESSION_POOL_OPTIONS_FOR_CLOUD_FUNCTIONS, SPANNER_SESSION_POOL_OPTIONS_FOR_SERVICE, } from './database.js';
 export { SpannerEntityManager } from './entity-manager.js';
-export type { SpannerKey, SpannerReadOnlyTransaction, SpannerReadWriteTransaction, } from './entity-manager.js';
+export type { SpannerKey, SpannerReadOnlyTransaction, SpannerReadWriteTransaction, SqlStatement, } from './entity-manager.js';
 export * from './errors.js';
 export { SpannerHealthIndicator } from './healthcheck.js';
 export { SpannerModule } from './module.js';

package/dist/spanner/index.js

@@ -1,5 +1,5 @@
 export { SpannerColumn } from './column.decorator.js';
-export { SPANNER_SESSION_POOL_OPTIONS_FOR_CLOUD_FUNCTIONS, SPANNER_SESSION_POOL_OPTIONS_FOR_SERVICE, catchSpannerDatabaseErrors, getDefaultSpannerDatabaseForCloudFunction, } from './database.js';
+export { catchSpannerDatabaseErrors, getDefaultSpannerDatabaseForCloudFunction, SPANNER_SESSION_POOL_OPTIONS_FOR_CLOUD_FUNCTIONS, SPANNER_SESSION_POOL_OPTIONS_FOR_SERVICE, } from './database.js';
 export { SpannerEntityManager } from './entity-manager.js';
 export * from './errors.js';
 export { SpannerHealthIndicator } from './healthcheck.js';

package/dist/spanner/table-cache.d.ts

@@ -7,22 +7,14 @@ export type CachedSpannerTableMetadata = {
      * The name of the table.
      */
     tableName: string;
-    /**
-     * The name of the table, quoted with backticks for use in queries.
-     */
-    quotedTableName: string;
     /**
      * The (ordered) list of columns that are part of the primary key.
      */
     primaryKeyColumns: string[];
     /**
-     * The list of all columns in the table.
-     */
-    columns: string[];
-    /**
-     * The list of all columns in the table, quoted with backticks and joined for use in queries.
+     * A map from class property names to Spanner column names.
      */
-    quotedColumns: string;
+    columnNames: Record<string, string>;
     /**
      * The name of the column used to mark soft deletes, if any.
      */

package/dist/spanner/table-cache.js

@@ -1,4 +1,4 @@
-import { getSpannerColumns, getSpannerColumnsMetadata, } from './column.decorator.js';
+import { getSpannerColumnsMetadata } from './column.decorator.js';
 import { InvalidEntityDefinitionError } from './errors.js';
 import { getSpannerTableMetadataFromType } from './table.decorator.js';
 /**
@@ -21,7 +21,6 @@ export class SpannerTableCache {
             throw new InvalidEntityDefinitionError(entityType);
         }
         const tableName = tableMetadata.name;
-        const quotedTableName = `\`${tableName}\``;
         const primaryKeyColumns = tableMetadata.primaryKey;
         const columnsMetadata = getSpannerColumnsMetadata(entityType);
         const softDeleteColumns = Object.values(columnsMetadata).filter((metadata) => metadata.softDelete);
@@ -29,15 +28,12 @@ export class SpannerTableCache {
             throw new InvalidEntityDefinitionError(entityType, `Only one column can be marked as soft delete.`);
         }
         const softDeleteColumn = softDeleteColumns[0]?.name ?? null;
-        const columns = getSpannerColumns(entityType);
-        const quotedColumns = columns.map((c) => `\`${c}\``).join(', ');
+        const columnNames = Object.fromEntries(Object.entries(columnsMetadata).map(([prop, { name }]) => [prop, name]));
         return {
             tableName,
-            quotedTableName,
             primaryKeyColumns,
-            columns,
-            quotedColumns,
             softDeleteColumn,
+            columnNames,
         };
     }
     /**

package/dist/transaction/firestore-pubsub/readonly-state-transaction.d.ts

@@ -1,11 +1,21 @@
 import type { ReadOnlyStateTransaction, ReadOnlyTransactionOption } from '@causa/runtime';
 import type { Type } from '@nestjs/common';
 import { Transaction } from 'firebase-admin/firestore';
+import { type SoftDeletedFirestoreCollectionMetadata } from './soft-deleted-collection.decorator.js';
 import type { FirestoreCollectionResolver } from './types.js';
 /**
  * Option for a function that accepts a {@link FirestoreReadOnlyStateTransaction}.
  */
 export type FirestoreReadOnlyStateTransactionOption = ReadOnlyTransactionOption<FirestoreReadOnlyStateTransaction>;
+/**
+ * Information about soft-deletion for a given document.
+ */
+export type SoftDeleteInfo<T extends object> = Omit<SoftDeletedFirestoreCollectionMetadata, 'deletedDocumentsCollectionSuffix'> & {
+    /**
+     * The reference to the soft-deleted document.
+     */
+    ref: FirebaseFirestore.DocumentReference<T>;
+};
 /**
  * A {@link ReadOnlyStateTransaction} that uses Firestore for state storage.
  *
@@ -33,5 +43,14 @@ export declare class FirestoreReadOnlyStateTransaction implements ReadOnlyStateT
      * The resolver that provides the Firestore collections for a given document type.
      */
     collectionResolver: FirestoreCollectionResolver);
+    /**
+     * Returns the soft-delete information for a given document, if the document type supports soft-deletion.
+     *
+     * @param activeDocRef The reference to the active document.
+     * @param type The type of the document.
+     * @returns The soft-delete information for the document, or `null` if the document type does not support
+     *   soft-deletion.
+     */
+    protected getSoftDeleteInfo<T extends object>(activeDocRef: FirebaseFirestore.DocumentReference<T>, type: Type<T>): SoftDeleteInfo<T> | null;
     get<T extends object>(type: Type<T>, entity: Partial<T>): Promise<T | null>;
 }

package/dist/transaction/firestore-pubsub/readonly-state-transaction.js

@@ -1,5 +1,6 @@
 import { Transaction } from 'firebase-admin/firestore';
-import { getReferenceForFirestoreDocument } from '../../firestore/index.js';
+import { getReferenceForFirestoreDocument, makeFirestoreDataConverter, } from '../../firestore/index.js';
+import { getSoftDeletedFirestoreCollectionMetadataForType, } from './soft-deleted-collection.decorator.js';
 /**
  * A {@link ReadOnlyStateTransaction} that uses Firestore for state storage.
  *
@@ -24,24 +25,44 @@ export class FirestoreReadOnlyStateTransaction {
         this.firestoreTransaction = firestoreTransaction;
         this.collectionResolver = collectionResolver;
     }
+    /**
+     * Returns the soft-delete information for a given document, if the document type supports soft-deletion.
+     *
+     * @param activeDocRef The reference to the active document.
+     * @param type The type of the document.
+     * @returns The soft-delete information for the document, or `null` if the document type does not support
+     *   soft-deletion.
+     */
+    getSoftDeleteInfo(activeDocRef, type) {
+        const softDeleteMetadata = getSoftDeletedFirestoreCollectionMetadataForType(type);
+        if (!softDeleteMetadata) {
+            return null;
+        }
+        const { deletedDocumentsCollectionSuffix: suffix, ...info } = softDeleteMetadata;
+        const softDeleteCollection = activeDocRef.firestore
+            .collection(`${activeDocRef.parent.path}${suffix}`)
+            .withConverter(makeFirestoreDataConverter(type));
+        const ref = softDeleteCollection.doc(activeDocRef.id);
+        return { ...info, ref };
+    }
     async get(type, entity) {
-        const { activeCollection, softDelete } = this.collectionResolver.getCollectionsForType(type);
+        const { activeCollection } = this.collectionResolver.getCollectionsForType(type);
         const activeDocRef = getReferenceForFirestoreDocument(activeCollection, entity, type);
         const activeSnapshot = await this.firestoreTransaction.get(activeDocRef);
         const activeDocument = activeSnapshot.data();
         if (activeDocument) {
             return activeDocument;
         }
-        if (!softDelete) {
+        const softDeleteInfo = this.getSoftDeleteInfo(activeDocRef, type);
+        if (!softDeleteInfo) {
             return null;
         }
-        const deletedDocRef = getReferenceForFirestoreDocument(softDelete.collection, entity, type);
-        const deletedSnapshot = await this.firestoreTransaction.get(deletedDocRef);
+        const deletedSnapshot = await this.firestoreTransaction.get(softDeleteInfo.ref);
         const deletedDocument = deletedSnapshot.data();
         if (!deletedDocument) {
             return null;
         }
-        delete deletedDocument[softDelete.expirationField];
+        delete deletedDocument[softDeleteInfo.expirationField];
         return deletedDocument;
     }
 }

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

@@ -22,26 +22,26 @@ export class FirestoreStateTransaction extends FirestoreReadOnlyStateTransaction
     async delete(typeOrEntity, key) {
         const type = (key === undefined ? typeOrEntity.constructor : typeOrEntity);
         key ??= typeOrEntity;
-        const { activeCollection, softDelete } = this.collectionResolver.getCollectionsForType(type);
+        const { activeCollection } = this.collectionResolver.getCollectionsForType(type);
         const activeDocRef = getReferenceForFirestoreDocument(activeCollection, key, type);
         this.firestoreTransaction.delete(activeDocRef);
-        if (!softDelete) {
+        const softDeleteInfo = this.getSoftDeleteInfo(activeDocRef, type);
+        if (!softDeleteInfo) {
             return;
         }
-        const deletedDocRef = getReferenceForFirestoreDocument(softDelete.collection, key, type);
-        this.firestoreTransaction.delete(deletedDocRef);
+        this.firestoreTransaction.delete(softDeleteInfo.ref);
     }
     async set(entity) {
         const documentType = entity.constructor;
-        const { activeCollection, softDelete } = this.collectionResolver.getCollectionsForType(documentType);
+        const { activeCollection } = this.collectionResolver.getCollectionsForType(documentType);
         const activeDocRef = getReferenceForFirestoreDocument(activeCollection, entity);
-        if (!softDelete) {
+        const softDeleteInfo = this.getSoftDeleteInfo(activeDocRef, documentType);
+        if (!softDeleteInfo) {
             this.firestoreTransaction.set(activeDocRef, entity);
             return;
         }
-        const deletedDocRef = getReferenceForFirestoreDocument(softDelete.collection, entity);
+        const { ref: deletedDocRef, expirationDelay, expirationField, } = softDeleteInfo;
         if ('deletedAt' in entity && entity.deletedAt instanceof Date) {
-            const { expirationDelay, expirationField } = softDelete;
             const expiresAt = new Date(entity.deletedAt.getTime() + expirationDelay);
             const deletedDoc = plainToInstance(documentType, {
                 ...entity,

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

@@ -12,6 +12,8 @@ export type FirestoreCollectionsForDocumentType<T> = {
     /**
      * Configuration about the soft-delete collection, where documents are stored when their `deletedAt` field is not
      * `null`. This can be `null` if the document type does not declare a soft-delete collection.
+     *
+     * @deprecated Use `SoftDeleteInfo` in `FirestoreReadOnlyStateTransaction.getSoftDeleteInfo` instead.
      */
     readonly softDelete: ({
         /**

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

@@ -99,8 +99,10 @@ export class SpannerOutboxSender extends OutboxEventSender {
      * @returns The SQL queries used to fetch and update events in the outbox.
      */
     buildSql() {
-        const table = this.entityManager.sqlTableName(this.outboxEventType);
-        const tableWithIndex = this.entityManager.sqlTableName(this.outboxEventType, { index: this.index });
+        const table = this.entityManager.sqlTable(this.outboxEventType);
+        const tableWithIndex = this.entityManager.sqlTable(this.outboxEventType, {
+            index: this.index,
+        });
         const noLeaseFilter = `\`${this.leaseExpirationColumn}\` IS NULL OR \`${this.leaseExpirationColumn}\` < @currentTime`;
         let fetchFilter = noLeaseFilter;
         if (this.sharding) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@causa/runtime-google",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "An extension to the Causa runtime SDK (`@causa/runtime`), providing Google-specific features.",
   "repository": {
     "type": "git",
@@ -32,48 +32,48 @@
     "test:cov": "npm run test -- --coverage"
   },
   "dependencies": {
-    "@causa/runtime": "^1.0.0",
+    "@causa/runtime": "^1.3.0",
     "@google-cloud/precise-date": "^5.0.0",
-    "@google-cloud/pubsub": "^5.1.0",
-    "@google-cloud/spanner": "^8.1.0",
-    "@google-cloud/tasks": "^6.2.0",
-    "@grpc/grpc-js": "^1.13.4",
-    "@nestjs/common": "^11.1.5",
+    "@google-cloud/pubsub": "^5.2.0",
+    "@google-cloud/spanner": "^8.2.2",
+    "@google-cloud/tasks": "^6.2.1",
+    "@grpc/grpc-js": "^1.14.0",
+    "@nestjs/common": "^11.1.6",
     "@nestjs/config": "^4.0.2",
-    "@nestjs/core": "^11.1.5",
+    "@nestjs/core": "^11.1.6",
     "@nestjs/passport": "^11.0.5",
     "@nestjs/terminus": "^11.0.0",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.2",
     "express": "^5.1.0",
-    "firebase-admin": "^13.4.0",
+    "firebase-admin": "^13.5.0",
     "jsonwebtoken": "^9.0.2",
     "passport-http-bearer": "^1.0.1",
-    "pino": "^9.7.0",
+    "pino": "^9.13.1",
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
-    "@nestjs/testing": "^11.1.5",
-    "@swc/core": "^1.13.3",
+    "@nestjs/testing": "^11.1.6",
+    "@swc/core": "^1.13.5",
     "@swc/jest": "^0.2.39",
     "@tsconfig/node22": "^22.0.2",
     "@types/jest": "^30.0.0",
     "@types/jsonwebtoken": "^9.0.10",
-    "@types/node": "^22.17.0",
-    "@types/passport-http-bearer": "^1.0.41",
+    "@types/node": "^22.18.11",
+    "@types/passport-http-bearer": "^1.0.42",
     "@types/supertest": "^6.0.3",
-    "@types/uuid": "^10.0.0",
-    "dotenv": "^17.2.1",
-    "eslint": "^9.32.0",
+    "@types/uuid": "^11.0.0",
+    "dotenv": "^17.2.3",
+    "eslint": "^9.38.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.3",
-    "jest": "^30.0.5",
+    "eslint-plugin-prettier": "^5.5.4",
+    "jest": "^30.2.0",
     "jest-extended": "^6.0.0",
-    "pino-pretty": "^13.1.1",
+    "pino-pretty": "^13.1.2",
     "rimraf": "^6.0.1",
     "supertest": "^7.1.4",
-    "typescript": "^5.9.2",
-    "typescript-eslint": "^8.39.0",
-    "uuid": "^11.1.0"
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.1",
+    "uuid": "^13.0.0"
   }
 }