@causa/workspace-google 0.18.0-beta.1 → 0.18.0-beta.3

package/dist/functions/emulator/start-spanner.call.js

@@ -5,7 +5,7 @@ import { Instance, Spanner } from '@google-cloud/spanner';
 // version can be loaded.
 import { grpc } from 'google-gax';
 import { getLocalGcpProject, } from '../../configurations/index.js';
-import { SPANNER_EMULATOR_NAME, SPANNER_GRPC_PORT, SPANNER_HTTP_PORT, SPANNER_IMAGE, getSpannerContainerName, } from '../../emulators/index.js';
+import { SPANNER_EMULATOR_NAME, SPANNER_GRPC_PORT, SPANNER_HTTP_PORT, SPANNER_IMAGE, getSpannerContainerName, getSpannerEmulatorGrpcPort, getSpannerEmulatorHttpPort, } from '../../emulators/index.js';
 import { GoogleSpannerListDatabases } from '../google-spanner/index.js';
 export default async function call() {
     const configuration = await startSpanner(this, this._context);
@@ -15,12 +15,14 @@ async function startSpanner(self, context) {
     if (self.dryRun) {
         return {};
     }
-    const emulatorConf = await startSpannerEmulator(context);
-    const instanceAndDatabaseConf = await initializeEmulator(context);
+    const grpcHostPort = getSpannerEmulatorGrpcPort(context);
+    const httpHostPort = getSpannerEmulatorHttpPort(context);
+    const emulatorConf = await startSpannerEmulator(context, grpcHostPort, httpHostPort);
+    const instanceAndDatabaseConf = await initializeEmulator(context, grpcHostPort);
     context.logger.info('🗃️ Successfully initialized Spanner emulator.');
     return { ...emulatorConf, ...instanceAndDatabaseConf };
 }
-async function startSpannerEmulator(context) {
+async function startSpannerEmulator(context, grpcHostPort, httpHostPort) {
     context.logger.info('🗃️ Starting Spanner emulator.');
     const gcpProject = getLocalGcpProject(context);
     const containerName = getSpannerContainerName(context);
@@ -28,23 +30,22 @@ async function startSpannerEmulator(context) {
         .asConfiguration()
         .get('google.spanner.emulator.version') ?? 'latest';
     const dockerEmulatorService = context.service(DockerEmulatorService);
-    await dockerEmulatorService.start(`${SPANNER_IMAGE}:${imageVersion}`, containerName, [SPANNER_GRPC_PORT, SPANNER_HTTP_PORT].map((p) => ({
-        host: '127.0.0.1',
-        local: p,
-        container: p,
-    })));
-    await dockerEmulatorService.waitForAvailability(containerName, `http://127.0.0.1:${SPANNER_HTTP_PORT}/v1/projects/${gcpProject}/instances`);
+    await dockerEmulatorService.start(`${SPANNER_IMAGE}:${imageVersion}`, containerName, [
+        { host: '127.0.0.1', local: grpcHostPort, container: SPANNER_GRPC_PORT },
+        { host: '127.0.0.1', local: httpHostPort, container: SPANNER_HTTP_PORT },
+    ]);
+    await dockerEmulatorService.waitForAvailability(containerName, `http://127.0.0.1:${httpHostPort}/v1/projects/${gcpProject}/instances`);
     return {
-        SPANNER_EMULATOR_HOST: `127.0.0.1:${SPANNER_GRPC_PORT}`,
+        SPANNER_EMULATOR_HOST: `127.0.0.1:${grpcHostPort}`,
         GOOGLE_CLOUD_PROJECT: gcpProject,
         GCP_PROJECT: gcpProject,
         GCLOUD_PROJECT: gcpProject,
     };
 }
-async function initializeEmulator(context) {
+async function initializeEmulator(context, port) {
     const spanner = new Spanner({
         servicePath: '127.0.0.1',
-        port: SPANNER_GRPC_PORT,
+        port,
         projectId: getLocalGcpProject(context),
         sslCreds: grpc.credentials.createInsecure(),
     });

package/dist/functions/event-topic/broker-delete-trigger-resource-pubsub-subscription.js

@@ -1,5 +1,6 @@
 import { callDeferred } from '@causa/workspace';
 import { EventTopicBrokerDeleteTriggerResource, } from '@causa/workspace-core';
+import { PUBSUB_SUBSCRIPTION_ID_REGEX } from '../../services/pubsub.utils.js';
 /**
  * Implements {@link EventTopicBrokerDeleteTriggerResource} for Pub/Sub subscriptions.
  * Pub/Sub subscriptions are for example used when creating Cloud Run triggers.
@@ -9,7 +10,7 @@ export class EventTopicBrokerDeleteTriggerResourceForPubSubSubscription extends
         return await callDeferred(this, import.meta.url);
     }
     _supports() {
-        return (this.id.match(/^projects\/[\w-]+\/subscriptions\/[\w-]+$/) != null &&
+        return (PUBSUB_SUBSCRIPTION_ID_REGEX.test(this.id) &&
             this._context
                 .asConfiguration()
                 .get('events.broker') === 'google.pubSub');

package/dist/functions/event-topic/broker-wait-for-processing-pubsub.call.d.ts

@@ -0,0 +1,2 @@
+import type { EventTopicBrokerWaitForProcessingForPubSub } from './broker-wait-for-processing-pubsub.js';
+export default function call(this: EventTopicBrokerWaitForProcessingForPubSub): Promise<void>;

package/dist/functions/event-topic/broker-wait-for-processing-pubsub.call.js

@@ -0,0 +1,119 @@
+import { setTimeout } from 'timers/promises';
+import { CloudMonitoringService, } from '../../services/cloud-monitoring.js';
+import { PUBSUB_SUBSCRIPTION_ID_REGEX, shortSubscriptionId, } from '../../services/index.js';
+/**
+ * The interval between two consecutive polls of the Cloud Monitoring API, in milliseconds.
+ */
+const POLL_INTERVAL = 30 * 1000;
+/**
+ * The duration of the trailing window of points fetched on each poll, in milliseconds.
+ * It must be greater than `QUIET_WINDOW` plus a margin for the Cloud Monitoring export lag.
+ */
+const TRAILING_WINDOW = 10 * 60 * 1000;
+/**
+ * The minimum duration (server-time, derived from point timestamps) over which all three monitored metrics must
+ * continuously report zero before a subscription is considered drained, in milliseconds.
+ */
+const QUIET_WINDOW = 3 * 60 * 1000;
+/**
+ * The alignment period used when querying the cumulative `ack_message_count` metric so that points represent the
+ * number of acks within each bucket (delta), rather than the absolute cumulative value, in seconds.
+ */
+const ALIGNMENT_PERIOD = 60;
+/**
+ * The overall timeout for waiting on a single subscription, in milliseconds.
+ * On timeout the function throws so that the backfill file is preserved for manual cleanup.
+ */
+const TIMEOUT = 60 * 60 * 1000;
+/**
+ * Returns the Cloud Monitoring filter for the given metric on the given subscription.
+ */
+function buildFilter(metricType, subscriptionId) {
+    return [
+        `metric.type = "${metricType}"`,
+        `resource.type = "pubsub_subscription"`,
+        `resource.labels.subscription_id = "${subscriptionId}"`,
+    ].join(' AND ');
+}
+/**
+ * Checks whether a gauge metric has been quiet (zero-valued) for at least {@link QUIET_WINDOW}.
+ *
+ * The check is purely server-side: the latest zero-valued point's timestamp must be at least `QUIET_WINDOW` after the
+ * latest non-zero point's timestamp. When no non-zero point exists in the trailing window, the metric is considered
+ * quiet (the outer liftoff gate is responsible for distinguishing "cold start" from "already drained").
+ */
+function isGaugeQuiet(points) {
+    const lastNonZeroTimestamp = points.filter(({ value }) => value > 0).at(-1)?.timestamp ?? -Infinity;
+    const latestZeroTimestamp = points.filter(({ value }) => value === 0).at(-1)?.timestamp ?? -Infinity;
+    return latestZeroTimestamp - lastNonZeroTimestamp >= QUIET_WINDOW;
+}
+/**
+ * Checks whether a cumulative metric (queried with `ALIGN_DELTA`) has had no non-zero activity in the trailing
+ * `QUIET_WINDOW` before the given reference time.
+ *
+ * Unlike a gauge, Pub/Sub stops writing samples for a cumulative metric while there is no activity. The server-side
+ * "still has zero points" anchor used by {@link isGaugeQuiet} therefore does not apply: the absence of points must be
+ * interpreted against an external time reference (the query end).
+ */
+function isCumulativeQuiet(points, referenceTime) {
+    const lastNonZeroTimestamp = points.filter(({ value }) => value > 0).at(-1)?.timestamp ?? -Infinity;
+    return referenceTime.getTime() - lastNonZeroTimestamp >= QUIET_WINDOW;
+}
+/**
+ * Observes a single subscription by fetching its three metrics over the configured trailing window and evaluating the
+ * liftoff and quiet conditions.
+ */
+async function observeSubscription(context, subscriptionId) {
+    const cms = context.service(CloudMonitoringService);
+    const end = new Date();
+    const start = new Date(end.getTime() - TRAILING_WINDOW);
+    const ackFilter = buildFilter('pubsub.googleapis.com/subscription/ack_message_count', subscriptionId);
+    const backlogFilter = buildFilter('pubsub.googleapis.com/subscription/num_undelivered_messages', subscriptionId);
+    const ageFilter = buildFilter('pubsub.googleapis.com/subscription/oldest_unacked_message_age', subscriptionId);
+    const [ackPoints, backlogPoints, agePoints] = await Promise.all([
+        cms.listPoints(ackFilter, start, end, {
+            aligner: 'ALIGN_DELTA',
+            alignmentPeriod: ALIGNMENT_PERIOD,
+        }),
+        cms.listPoints(backlogFilter, start, end),
+        cms.listPoints(ageFilter, start, end),
+    ]);
+    const liftoff = ackPoints.some(({ value }) => value > 0);
+    const backlog = backlogPoints.at(-1)?.value ?? null;
+    const drained = liftoff &&
+        isCumulativeQuiet(ackPoints, end) &&
+        isGaugeQuiet(backlogPoints) &&
+        isGaugeQuiet(agePoints);
+    return { liftoff, backlog, drained };
+}
+/**
+ * Waits for a single subscription to be drained, polling Cloud Monitoring until either the drained state is reached
+ * or the overall timeout elapses.
+ */
+async function waitForSubscription(context, subscriptionId) {
+    const deadline = Date.now() + TIMEOUT;
+    while (true) {
+        const { drained, backlog, liftoff } = await observeSubscription(context, subscriptionId);
+        if (drained) {
+            context.logger.debug(`✅ Subscription '${subscriptionId}' drained: backlog is empty and metrics have been quiet for at least ${QUIET_WINDOW / 1000}s.`);
+            return;
+        }
+        const backlogLabel = backlog === null ? 'no data yet' : `backlog=${backlog}`;
+        context.logger.debug(`⏳ Subscription '${subscriptionId}' not drained yet (liftoff=${liftoff}, ${backlogLabel}).`);
+        if (Date.now() >= deadline) {
+            throw new Error(`Timed out after ${Math.round(TIMEOUT / 60_000)} minute(s) waiting for subscription '${subscriptionId}' to drain.`);
+        }
+        await setTimeout(POLL_INTERVAL);
+    }
+}
+export default async function call() {
+    const subscriptionIds = this.temporaryData.temporaryTriggerResourceIds
+        .filter((id) => PUBSUB_SUBSCRIPTION_ID_REGEX.test(id))
+        .map(shortSubscriptionId);
+    if (subscriptionIds.length === 0) {
+        throw new Error(`Cannot wait for processing of backfill on event topic '${this.eventTopic}': no temporary Pub/Sub subscription was created. Only backfills with temporary triggers are supported.`);
+    }
+    this._context.logger.info(`⏳ Waiting for processing of ${subscriptionIds.length} temporary Pub/Sub subscription(s) for event topic '${this.eventTopic}'.`);
+    await Promise.all(subscriptionIds.map((id) => waitForSubscription(this._context, id)));
+    this._context.logger.info(`✅ All temporary Pub/Sub subscriptions for event topic '${this.eventTopic}' have been drained.`);
+}

package/dist/functions/event-topic/broker-wait-for-processing-pubsub.d.ts

@@ -0,0 +1,16 @@
+import { EventTopicBrokerWaitForProcessing } from '@causa/workspace-core';
+/**
+ * Implements {@link EventTopicBrokerWaitForProcessing} for Pub/Sub temporary subscriptions.
+ *
+ * Only backfills that created temporary push subscriptions are supported: at least one entry of
+ * {@link BackfillTemporaryData.temporaryTriggerResourceIds} must match a subscription ID. If none does, the function
+ * throws — there is no observable signal for backfills that publish into existing topics with existing subscriptions.
+ *
+ * Completion is decided per-subscription from Cloud Monitoring time series (`subscription/ack_message_count`,
+ * `subscription/num_undelivered_messages`, `subscription/oldest_unacked_message_age`). See the call file for the exact
+ * decision logic.
+ */
+export declare class EventTopicBrokerWaitForProcessingForPubSub extends EventTopicBrokerWaitForProcessing {
+    _call(): Promise<void>;
+    _supports(): boolean;
+}

package/dist/functions/event-topic/broker-wait-for-processing-pubsub.js

@@ -0,0 +1,23 @@
+import { callDeferred } from '@causa/workspace';
+import { EventTopicBrokerWaitForProcessing, } from '@causa/workspace-core';
+/**
+ * Implements {@link EventTopicBrokerWaitForProcessing} for Pub/Sub temporary subscriptions.
+ *
+ * Only backfills that created temporary push subscriptions are supported: at least one entry of
+ * {@link BackfillTemporaryData.temporaryTriggerResourceIds} must match a subscription ID. If none does, the function
+ * throws — there is no observable signal for backfills that publish into existing topics with existing subscriptions.
+ *
+ * Completion is decided per-subscription from Cloud Monitoring time series (`subscription/ack_message_count`,
+ * `subscription/num_undelivered_messages`, `subscription/oldest_unacked_message_age`). See the call file for the exact
+ * decision logic.
+ */
+export class EventTopicBrokerWaitForProcessingForPubSub extends EventTopicBrokerWaitForProcessing {
+    async _call() {
+        return await callDeferred(this, import.meta.url);
+    }
+    _supports() {
+        return (this._context
+            .asConfiguration()
+            .get('events.broker') === 'google.pubSub');
+    }
+}

package/dist/functions/event-topic/index.d.ts

@@ -6,5 +6,6 @@ export { EventTopicBrokerDeleteTriggerResourceForPubSubSubscription } from './br
 export { EventTopicBrokerDeleteTriggerResourceForServiceAccount } from './broker-delete-trigger-resource-service-account.js';
 export { EventTopicBrokerGetTopicIdForPubSub } from './broker-get-topic-id-pubsub.js';
 export { EventTopicBrokerPublishEventsForGoogle } from './broker-publish-events-google.js';
+export { EventTopicBrokerWaitForProcessingForPubSub } from './broker-wait-for-processing-pubsub.js';
 export { EventTopicCreateBackfillSourceForBigQuery } from './create-backfill-source-bigquery.js';
 export { EventTopicQueryEventsForBigQuery } from './query-events-bigquery.js';

package/dist/functions/event-topic/index.js

@@ -6,5 +6,6 @@ export { EventTopicBrokerDeleteTriggerResourceForPubSubSubscription } from './br
 export { EventTopicBrokerDeleteTriggerResourceForServiceAccount } from './broker-delete-trigger-resource-service-account.js';
 export { EventTopicBrokerGetTopicIdForPubSub } from './broker-get-topic-id-pubsub.js';
 export { EventTopicBrokerPublishEventsForGoogle } from './broker-publish-events-google.js';
+export { EventTopicBrokerWaitForProcessingForPubSub } from './broker-wait-for-processing-pubsub.js';
 export { EventTopicCreateBackfillSourceForBigQuery } from './create-backfill-source-bigquery.js';
 export { EventTopicQueryEventsForBigQuery } from './query-events-bigquery.js';

package/dist/functions/google-firestore/generate-typescript-decorators.d.ts

@@ -0,0 +1,13 @@
+import { ModelGenerateTypeScriptDecorators } from '@causa/workspace-typescript';
+import { type TypeScriptDecorator } from '@causa/workspace-typescript/code-generation';
+/**
+ * Implements {@link ModelGenerateTypeScriptDecorators} to add Google Firestore decorators from the Causa Google runtime.
+ *
+ * If an object schema is marked with the `googleFirestoreCollection` extension, the `@FirestoreCollection` decorator is
+ * added to the class. If the `hasSoftDelete` property is `true`, the `@SoftDeletedFirestoreCollection` decorator is also
+ * added.
+ */
+export declare class ModelGenerateTypeScriptDecoratorsForGoogleFirestore extends ModelGenerateTypeScriptDecorators {
+    _call(): TypeScriptDecorator[];
+    _supports(): boolean;
+}

package/dist/functions/google-firestore/generate-typescript-decorators.js

@@ -0,0 +1,78 @@
+import { ModelGenerateTypeScriptDecorators } from '@causa/workspace-typescript';
+import { addDecoratorToList, } from '@causa/workspace-typescript/code-generation';
+import micromatch from 'micromatch';
+import { join } from 'path';
+/**
+ * The name of the Causa extension marking an object schema as a Google Firestore collection.
+ */
+const GOOGLE_FIRESTORE_COLLECTION_EXTENSION = 'googleFirestoreCollection';
+/**
+ * The name of the Causa module for the TypeScript Google runtime.
+ */
+const CAUSA_GOOGLE_MODULE = '@causa/runtime-google';
+/**
+ * Implements {@link ModelGenerateTypeScriptDecorators} to add Google Firestore decorators from the Causa Google runtime.
+ *
+ * If an object schema is marked with the `googleFirestoreCollection` extension, the `@FirestoreCollection` decorator is
+ * added to the class. If the `hasSoftDelete` property is `true`, the `@SoftDeletedFirestoreCollection` decorator is also
+ * added.
+ */
+export class ModelGenerateTypeScriptDecoratorsForGoogleFirestore extends ModelGenerateTypeScriptDecorators {
+    _call() {
+        if (this.property) {
+            return [];
+        }
+        const attribute = this.schema.extensions[GOOGLE_FIRESTORE_COLLECTION_EXTENSION];
+        if (!attribute) {
+            return [];
+        }
+        const globs = this.configuration?.google?.firestore?.globs;
+        if (Array.isArray(globs)) {
+            const projectPath = this._context.getProjectPathOrThrow();
+            const absoluteGlobs = globs.map((g) => join(projectPath, g));
+            const schemaPath = this.schema.path.split('#')[0];
+            if (!micromatch.isMatch(schemaPath, absoluteGlobs)) {
+                return [];
+            }
+        }
+        const debugName = this.schema.name;
+        if (typeof attribute !== 'object') {
+            throw new Error(`Invalid '${GOOGLE_FIRESTORE_COLLECTION_EXTENSION}' attribute on '${debugName}'. Expected an object.`);
+        }
+        const { name, path, hasSoftDelete } = attribute;
+        if (typeof name !== 'string') {
+            throw new Error(`Invalid '${GOOGLE_FIRESTORE_COLLECTION_EXTENSION}' attribute on '${debugName}'. Expected an object with a 'name' string property.`);
+        }
+        if (!Array.isArray(path)) {
+            throw new Error(`Invalid '${GOOGLE_FIRESTORE_COLLECTION_EXTENSION}' attribute on '${debugName}'. Expected an object with a 'path' array property.`);
+        }
+        const propertyNames = new Set(this.schema.properties.map((p) => p.name));
+        const elements = path.map((element) => {
+            if (typeof element === 'string') {
+                return JSON.stringify(element);
+            }
+            if (typeof element === 'object' &&
+                element !== null &&
+                'property' in element &&
+                typeof element.property === 'string') {
+                const propertyName = element.property;
+                if (!propertyNames.has(propertyName)) {
+                    throw new Error(`Property '${propertyName}' referenced in 'path' not found in '${debugName}'.`);
+                }
+                return `doc.${propertyName}`;
+            }
+            throw new Error(`Invalid path element in '${GOOGLE_FIRESTORE_COLLECTION_EXTENSION}' attribute on '${debugName}'.`);
+        });
+        const pathExpression = path.length === 1 ? elements[0] : `[${elements.join(', ')}].join("/")`;
+        const decorators = [];
+        addDecoratorToList(decorators, { schema: this.schema }, 'FirestoreCollection', CAUSA_GOOGLE_MODULE, `@FirestoreCollection({ name: ${JSON.stringify(name)}, path: (doc) => ${pathExpression} })`);
+        if (hasSoftDelete === true) {
+            addDecoratorToList(decorators, { schema: this.schema }, 'SoftDeletedFirestoreCollection', CAUSA_GOOGLE_MODULE, '@SoftDeletedFirestoreCollection()');
+        }
+        return decorators;
+    }
+    _supports() {
+        return (this._context.get('project.language') === 'typescript' &&
+            this.generator === 'typescriptModelClass');
+    }
+}

package/dist/functions/google-firestore/index.d.ts

@@ -1,3 +1,4 @@
 export { ModelSchemaExtractDatabaseForGoogleFirestore } from './extract-database.js';
+export { ModelGenerateTypeScriptDecoratorsForGoogleFirestore } from './generate-typescript-decorators.js';
 export { DatabaseQueryRecordsForFirestore } from './query-records.js';
 export { GoogleFirestoreMergeRules } from './merge-rules.js';

package/dist/functions/google-firestore/index.js

@@ -1,3 +1,4 @@
 export { ModelSchemaExtractDatabaseForGoogleFirestore } from './extract-database.js';
+export { ModelGenerateTypeScriptDecoratorsForGoogleFirestore } from './generate-typescript-decorators.js';
 export { DatabaseQueryRecordsForFirestore } from './query-records.js';
 export { GoogleFirestoreMergeRules } from './merge-rules.js';

package/dist/functions/google-spanner/generate-typescript-decorators.d.ts

@@ -0,0 +1,14 @@
+import { ModelGenerateTypeScriptDecorators } from '@causa/workspace-typescript';
+import { type TypeScriptDecorator } from '@causa/workspace-typescript/code-generation';
+/**
+ * Implements {@link ModelGenerateTypeScriptDecorators} to add Google Spanner decorators from the Causa Google runtime.
+ *
+ * If an object schema is marked with the `googleSpannerTable` extension, the `@SpannerTable` decorator is added to the
+ * class, and `@SpannerColumn` decorators are added to all its properties.
+ */
+export declare class ModelGenerateTypeScriptDecoratorsForGoogleSpanner extends ModelGenerateTypeScriptDecorators {
+    _call(): TypeScriptDecorator[];
+    _supports(): boolean;
+    private decoratorsForClass;
+    private decoratorsForProperty;
+}

package/dist/functions/google-spanner/generate-typescript-decorators.js

@@ -0,0 +1,120 @@
+import { ModelGenerateTypeScriptDecorators } from '@causa/workspace-typescript';
+import { addDecoratorToList, } from '@causa/workspace-typescript/code-generation';
+import micromatch from 'micromatch';
+import { join } from 'path';
+/**
+ * The name of the Causa extension marking an object schema as a Google Spanner table.
+ */
+const GOOGLE_SPANNER_TABLE_EXTENSION = 'googleSpannerTable';
+/**
+ * The name of the optional Causa extension that can be present on an object property schema to specify options for the
+ * `@SpannerColumn` decorator.
+ */
+const GOOGLE_SPANNER_COLUMN_EXTENSION = 'googleSpannerColumn';
+/**
+ * The name of the Causa module for the TypeScript Google runtime.
+ */
+const CAUSA_GOOGLE_MODULE = '@causa/runtime-google';
+/**
+ * The list of options that can be passed to the `@SpannerColumn` decorator and that indicates that the schema specifies
+ * the type of the column. In this case, the renderer should not infer any type information.
+ */
+const TYPE_INFO_COLUMN_ATTRIBUTE_NAMES = [
+    'isBigInt',
+    'isInt',
+    'isPreciseDate',
+    'isJson',
+];
+/**
+ * Implements {@link ModelGenerateTypeScriptDecorators} to add Google Spanner decorators from the Causa Google runtime.
+ *
+ * If an object schema is marked with the `googleSpannerTable` extension, the `@SpannerTable` decorator is added to the
+ * class, and `@SpannerColumn` decorators are added to all its properties.
+ */
+export class ModelGenerateTypeScriptDecoratorsForGoogleSpanner extends ModelGenerateTypeScriptDecorators {
+    _call() {
+        const tableAttribute = this.schema.extensions[GOOGLE_SPANNER_TABLE_EXTENSION];
+        if (!tableAttribute) {
+            return [];
+        }
+        const globs = this.configuration?.google?.spanner?.globs;
+        if (Array.isArray(globs)) {
+            const projectPath = this._context.getProjectPathOrThrow();
+            const absoluteGlobs = globs.map((g) => join(projectPath, g));
+            const schemaPath = this.schema.path.split('#')[0];
+            if (!micromatch.isMatch(schemaPath, absoluteGlobs)) {
+                return [];
+            }
+        }
+        return this.property
+            ? this.decoratorsForProperty()
+            : this.decoratorsForClass(tableAttribute);
+    }
+    _supports() {
+        return (this._context.get('project.language') === 'typescript' &&
+            this.generator === 'typescriptModelClass');
+    }
+    decoratorsForClass(tableAttribute) {
+        const debugName = this.schema.name;
+        if (typeof tableAttribute !== 'object' ||
+            tableAttribute === null ||
+            !('primaryKey' in tableAttribute) ||
+            !Array.isArray(tableAttribute.primaryKey) ||
+            tableAttribute.primaryKey.length === 0 ||
+            tableAttribute.primaryKey.some((k) => typeof k !== 'string')) {
+            throw new Error(`Invalid '${GOOGLE_SPANNER_TABLE_EXTENSION}' attribute on '${debugName}'. Expected an object with a 'primaryKey' array.`);
+        }
+        const { primaryKey, name } = tableAttribute;
+        if (name !== undefined && typeof name !== 'string') {
+            throw new Error(`Invalid 'name' in '${GOOGLE_SPANNER_TABLE_EXTENSION}' attribute on '${debugName}'. Expected a string.`);
+        }
+        const decorators = [];
+        addDecoratorToList(decorators, { schema: this.schema }, 'SpannerTable', CAUSA_GOOGLE_MODULE, `@SpannerTable(${JSON.stringify({ primaryKey, name })})`);
+        return decorators;
+    }
+    decoratorsForProperty() {
+        const property = this.property;
+        const rawAttributes = property.extensions[GOOGLE_SPANNER_COLUMN_EXTENSION] ?? {};
+        if (typeof rawAttributes !== 'object' || rawAttributes === null) {
+            throw new Error(`Invalid '${GOOGLE_SPANNER_COLUMN_EXTENSION}' attribute on '${this.schema.name}.${property.name}'. Expected an object.`);
+        }
+        const { name: overriddenName, tsOptions } = rawAttributes;
+        if (tsOptions !== undefined &&
+            (typeof tsOptions !== 'object' || tsOptions === null)) {
+            throw new Error(`Invalid 'tsOptions' in '${GOOGLE_SPANNER_COLUMN_EXTENSION}' attribute. Expected an object.`);
+        }
+        const columnAttributes = {
+            ...(tsOptions ?? {}),
+        };
+        if (overriddenName !== undefined) {
+            if (typeof overriddenName !== 'string') {
+                throw new Error(`Invalid 'name' in '${GOOGLE_SPANNER_COLUMN_EXTENSION}' attribute. Expected a string.`);
+            }
+            columnAttributes.name = overriddenName;
+        }
+        const softDeletionColumn = this.configuration?.google?.spanner
+            ?.softDeletionColumn;
+        const columnName = typeof overriddenName === 'string' ? overriddenName : property.name;
+        if (columnName === softDeletionColumn) {
+            columnAttributes.softDelete = true;
+        }
+        const schemaOverridesTypeInfo = TYPE_INFO_COLUMN_ATTRIBUTE_NAMES.some((n) => n in columnAttributes);
+        if (!schemaOverridesTypeInfo) {
+            const type = property.type.kind === 'array' ? property.type.items : property.type;
+            const resolved = type.kind === 'ref' ? this.schemas[type.ref] : undefined;
+            if (type.kind === 'primitive' && type.type === 'integer') {
+                columnAttributes.isInt = true;
+            }
+            else if (type.kind === 'map' || resolved?.kind === 'object') {
+                columnAttributes.isJson = true;
+            }
+        }
+        const hasOptions = Object.keys(columnAttributes).length > 0;
+        const source = hasOptions
+            ? `@SpannerColumn(${JSON.stringify(columnAttributes)})`
+            : '@SpannerColumn()';
+        const decorators = [];
+        addDecoratorToList(decorators, { schema: this.schema, property }, 'SpannerColumn', CAUSA_GOOGLE_MODULE, source);
+        return decorators;
+    }
+}

package/dist/functions/google-spanner/index.d.ts

@@ -1,4 +1,5 @@
 export { ModelSchemaExtractDatabaseForGoogleSpanner } from './extract-database.js';
+export { ModelGenerateTypeScriptDecoratorsForGoogleSpanner } from './generate-typescript-decorators.js';
 export { GoogleSpannerListDatabases } from './list-databases.js';
 export { DatabaseQueryRecordsForSpanner } from './query-records.js';
 export { GoogleSpannerWriteDatabases } from './write-databases.js';

package/dist/functions/google-spanner/index.js

@@ -1,4 +1,5 @@
 export { ModelSchemaExtractDatabaseForGoogleSpanner } from './extract-database.js';
+export { ModelGenerateTypeScriptDecoratorsForGoogleSpanner } from './generate-typescript-decorators.js';
 export { GoogleSpannerListDatabases } from './list-databases.js';
 export { DatabaseQueryRecordsForSpanner } from './query-records.js';
 export { GoogleSpannerWriteDatabases } from './write-databases.js';

package/dist/functions/index.js

@@ -1,17 +1,16 @@
 import { CausaListConfigurationSchemasForGoogle } from './causa/index.js';
 import { EmulatorStartForFirebaseStorage, EmulatorStartForFirestore, EmulatorStartForIdentityPlatform, EmulatorStartForPubSub, EmulatorStartForSpanner, EmulatorStopForFirebaseStorage, EmulatorStopForFirestore, EmulatorStopForIdentityPlatform, EmulatorStopForPubSub, EmulatorStopForSpanner, } from './emulator/index.js';
-import { EventTopicBrokerCreateTopicForPubSub, EventTopicBrokerCreateTriggerForCloudRun, EventTopicBrokerDeleteTopicForPubSub, EventTopicBrokerDeleteTriggerResourceForCloudRunInvokerRole, EventTopicBrokerDeleteTriggerResourceForPubSubSubscription, EventTopicBrokerDeleteTriggerResourceForServiceAccount, EventTopicBrokerGetTopicIdForPubSub, EventTopicBrokerPublishEventsForGoogle, EventTopicCreateBackfillSourceForBigQuery, EventTopicQueryEventsForBigQuery, } from './event-topic/index.js';
+import { EventTopicBrokerCreateTopicForPubSub, EventTopicBrokerCreateTriggerForCloudRun, EventTopicBrokerDeleteTopicForPubSub, EventTopicBrokerDeleteTriggerResourceForCloudRunInvokerRole, EventTopicBrokerDeleteTriggerResourceForPubSubSubscription, EventTopicBrokerDeleteTriggerResourceForServiceAccount, EventTopicBrokerGetTopicIdForPubSub, EventTopicBrokerPublishEventsForGoogle, EventTopicBrokerWaitForProcessingForPubSub, EventTopicCreateBackfillSourceForBigQuery, EventTopicQueryEventsForBigQuery, } from './event-topic/index.js';
 import { GoogleAppCheckGenerateToken } from './google-app-check/index.js';
 import { GoogleFirebaseStorageMergeRules } from './google-firebase-storage/index.js';
-import { DatabaseQueryRecordsForFirestore, GoogleFirestoreMergeRules, ModelSchemaExtractDatabaseForGoogleFirestore, } from './google-firestore/index.js';
+import { DatabaseQueryRecordsForFirestore, GoogleFirestoreMergeRules, ModelGenerateTypeScriptDecoratorsForGoogleFirestore, ModelSchemaExtractDatabaseForGoogleFirestore, } from './google-firestore/index.js';
 import { GoogleIdentityPlatformGenerateCustomToken, GoogleIdentityPlatformGenerateToken, } from './google-identity-platform/index.js';
 import { GooglePubSubWriteTopics } from './google-pubsub/index.js';
 import { GoogleServicesEnable } from './google-services/index.js';
-import { DatabaseQueryRecordsForSpanner, GoogleSpannerListDatabases, GoogleSpannerWriteDatabases, ModelSchemaExtractDatabaseForGoogleSpanner, } from './google-spanner/index.js';
+import { DatabaseQueryRecordsForSpanner, GoogleSpannerListDatabases, GoogleSpannerWriteDatabases, ModelGenerateTypeScriptDecoratorsForGoogleSpanner, ModelSchemaExtractDatabaseForGoogleSpanner, } from './google-spanner/index.js';
 import { ProjectGetArtefactDestinationForCloudFunctions, ProjectGetArtefactDestinationForCloudRun, ProjectPushArtefactForCloudFunctions, } from './project/index.js';
 import { SecretFetchForGoogleAccessToken, SecretFetchForGoogleSecretManager, } from './secret/index.js';
 import { ServiceContainerQueryLogsForCloudRun } from './service-container/index.js';
-import { TypeScriptGetDecoratorRendererForGoogleFirestore, TypeScriptGetDecoratorRendererForGoogleSpanner, } from './typescript/index.js';
 export function registerFunctions(context) {
-    context.registerFunctionImplementations(CausaListConfigurationSchemasForGoogle, DatabaseQueryRecordsForFirestore, DatabaseQueryRecordsForSpanner, EmulatorStartForFirebaseStorage, EmulatorStartForFirestore, EmulatorStartForIdentityPlatform, EmulatorStartForPubSub, EmulatorStartForSpanner, EmulatorStopForFirebaseStorage, EmulatorStopForFirestore, EmulatorStopForIdentityPlatform, EmulatorStopForPubSub, EmulatorStopForSpanner, EventTopicBrokerCreateTopicForPubSub, EventTopicBrokerCreateTriggerForCloudRun, EventTopicBrokerDeleteTopicForPubSub, EventTopicBrokerDeleteTriggerResourceForCloudRunInvokerRole, EventTopicBrokerDeleteTriggerResourceForPubSubSubscription, EventTopicBrokerDeleteTriggerResourceForServiceAccount, EventTopicBrokerGetTopicIdForPubSub, EventTopicBrokerPublishEventsForGoogle, EventTopicCreateBackfillSourceForBigQuery, EventTopicQueryEventsForBigQuery, GoogleAppCheckGenerateToken, GoogleFirebaseStorageMergeRules, GoogleFirestoreMergeRules, GoogleIdentityPlatformGenerateCustomToken, GoogleIdentityPlatformGenerateToken, GooglePubSubWriteTopics, GoogleServicesEnable, GoogleSpannerListDatabases, GoogleSpannerWriteDatabases, ModelSchemaExtractDatabaseForGoogleFirestore, ModelSchemaExtractDatabaseForGoogleSpanner, ProjectGetArtefactDestinationForCloudFunctions, ProjectGetArtefactDestinationForCloudRun, ProjectPushArtefactForCloudFunctions, SecretFetchForGoogleAccessToken, SecretFetchForGoogleSecretManager, ServiceContainerQueryLogsForCloudRun, TypeScriptGetDecoratorRendererForGoogleFirestore, TypeScriptGetDecoratorRendererForGoogleSpanner);
+    context.registerFunctionImplementations(CausaListConfigurationSchemasForGoogle, DatabaseQueryRecordsForFirestore, DatabaseQueryRecordsForSpanner, EmulatorStartForFirebaseStorage, EmulatorStartForFirestore, EmulatorStartForIdentityPlatform, EmulatorStartForPubSub, EmulatorStartForSpanner, EmulatorStopForFirebaseStorage, EmulatorStopForFirestore, EmulatorStopForIdentityPlatform, EmulatorStopForPubSub, EmulatorStopForSpanner, EventTopicBrokerCreateTopicForPubSub, EventTopicBrokerCreateTriggerForCloudRun, EventTopicBrokerDeleteTopicForPubSub, EventTopicBrokerDeleteTriggerResourceForCloudRunInvokerRole, EventTopicBrokerDeleteTriggerResourceForPubSubSubscription, EventTopicBrokerDeleteTriggerResourceForServiceAccount, EventTopicBrokerGetTopicIdForPubSub, EventTopicBrokerPublishEventsForGoogle, EventTopicBrokerWaitForProcessingForPubSub, EventTopicCreateBackfillSourceForBigQuery, EventTopicQueryEventsForBigQuery, GoogleAppCheckGenerateToken, GoogleFirebaseStorageMergeRules, GoogleFirestoreMergeRules, GoogleIdentityPlatformGenerateCustomToken, GoogleIdentityPlatformGenerateToken, GooglePubSubWriteTopics, GoogleServicesEnable, GoogleSpannerListDatabases, GoogleSpannerWriteDatabases, ModelGenerateTypeScriptDecoratorsForGoogleFirestore, ModelGenerateTypeScriptDecoratorsForGoogleSpanner, ModelSchemaExtractDatabaseForGoogleFirestore, ModelSchemaExtractDatabaseForGoogleSpanner, ProjectGetArtefactDestinationForCloudFunctions, ProjectGetArtefactDestinationForCloudRun, ProjectPushArtefactForCloudFunctions, SecretFetchForGoogleAccessToken, SecretFetchForGoogleSecretManager, ServiceContainerQueryLogsForCloudRun);
 }

package/dist/services/cloud-monitoring.d.ts

@@ -0,0 +1,44 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { MetricServiceClient } from '@google-cloud/monitoring';
+/**
+ * A single metric point with its server-side end timestamp (as milliseconds since epoch) and numeric value.
+ */
+export type MetricPoint = {
+    /**
+     * The end timestamp of the point's interval, as milliseconds since epoch.
+     */
+    readonly timestamp: number;
+    /**
+     * The numeric value of the point.
+     */
+    readonly value: number;
+};
+/**
+ * A service exposing a thin wrapper around the Cloud Monitoring API.
+ */
+export declare class CloudMonitoringService {
+    /**
+     * The underlying Cloud Monitoring client.
+     */
+    readonly client: MetricServiceClient;
+    /**
+     * The ID of the GCP project from which metrics are read.
+     */
+    readonly projectId: string;
+    constructor(context: WorkspaceContext);
+    /**
+     * Fetches the data points for a single time series over the given time interval.
+     * Returns the points sorted in ascending timestamp order. Each point's timestamp is the end of the corresponding
+     * interval, in milliseconds since epoch. An empty array is returned when no series matches the filter.
+     *
+     * @param filter The Cloud Monitoring metric filter expression (e.g. `metric.type = "..."`).
+     * @param start The inclusive lower bound of the interval to fetch.
+     * @param end The exclusive upper bound of the interval to fetch.
+     * @param options Optional aggregation options.
+     * @returns The list of points, ordered by ascending timestamp.
+     */
+    listPoints(filter: string, start: Date, end: Date, options?: {
+        readonly alignmentPeriod?: number;
+        readonly aligner?: 'ALIGN_NONE' | 'ALIGN_DELTA' | 'ALIGN_RATE' | 'ALIGN_MEAN' | 'ALIGN_MAX';
+    }): Promise<MetricPoint[]>;
+}