@proteinjs/db-driver-spanner 1.10.20 → 1.11.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.11.0](https://github.com/proteinjs/db/compare/@proteinjs/db-driver-spanner@1.10.21...@proteinjs/db-driver-spanner@1.11.0) (2026-07-23)
+
+
+### Features
+
+* **spanner:** SpannerEmulatorProvisioner — shared test-harness emulator provisioning ([b9e634a](https://github.com/proteinjs/db/commit/b9e634ab74580a66e589ce277985aca21e13a518))
+
+
+
+
+
 ## [1.10.20](https://github.com/proteinjs/db/compare/@proteinjs/db-driver-spanner@1.10.19...@proteinjs/db-driver-spanner@1.10.20) (2026-07-21)
 
 

package/dist/test/index.d.ts

@@ -1,2 +1,3 @@
 export * from './util/getDropTestTable';
+export * from './util/SpannerEmulatorProvisioner';
 //# sourceMappingURL=index.d.ts.map

package/dist/test/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../test/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../test/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,mCAAmC,CAAC"}

package/dist/test/index.js

@@ -15,4 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./util/getDropTestTable"), exports);
+__exportStar(require("./util/SpannerEmulatorProvisioner"), exports);
 //# sourceMappingURL=index.js.map

package/dist/test/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../test/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0DAAwC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../test/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0DAAwC;AACxC,oEAAkD"}

package/dist/test/util/SpannerEmulatorProvisioner.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared test-harness provisioning for the Spanner emulator.
+ *
+ * The emulator holds instances IN MEMORY — any container restart (Docker updates, host reboots,
+ * fresh CI service containers) silently wipes them, and every suite then fast-fails with a
+ * cryptic gRPC "Instance not found" until someone re-provisions by hand. Harnesses call
+ * `ensureProvisioned` in beforeAll; it is idempotent (ALREADY_EXISTS answers are success) and
+ * gated on `SPANNER_EMULATOR_HOST`, so it can never touch real GCP.
+ *
+ * Provisioning uses the ADMIN API over gRPC on the SAME address the suites' data client uses —
+ * no second endpoint to derive or configure, any docker port mapping works (the emulator's REST
+ * port doesn't even need publishing), and it shares the data client's exact fate: if the address
+ * is wrong, no suite could pass anyway.
+ *
+ * @internal This class is intended to be used only in tests. Do not use it in production code.
+ */
+export declare class SpannerEmulatorProvisioner {
+    /** Kept until release(): closing right after the create-operations races their trailing LRO
+     *  callbacks into an unhandled "client has already been closed" that fails the suite. */
+    private static client;
+    /** Ensure the instance + database exist on the emulator. No-op without SPANNER_EMULATOR_HOST. */
+    static ensureProvisioned(config: {
+        projectId: string;
+        instanceName: string;
+        databaseName: string;
+    }): Promise<void>;
+    /** Close the admin client — call from afterAll so jest's event loop can drain. */
+    static release(): void;
+    private static swallowAlreadyExists;
+}
+//# sourceMappingURL=SpannerEmulatorProvisioner.d.ts.map

package/dist/test/util/SpannerEmulatorProvisioner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpannerEmulatorProvisioner.d.ts","sourceRoot":"","sources":["../../../test/util/SpannerEmulatorProvisioner.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,0BAA0B;IACrC;6FACyF;IACzF,OAAO,CAAC,MAAM,CAAC,MAAM,CAAsB;IAE3C,iGAAiG;WACpF,iBAAiB,CAAC,MAAM,EAAE;QACrC,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBjB,kFAAkF;IAClF,MAAM,CAAC,OAAO,IAAI,IAAI;IAQtB,OAAO,CAAC,MAAM,CAAC,oBAAoB;CAKpC"}

package/dist/test/util/SpannerEmulatorProvisioner.js

@@ -0,0 +1,128 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpannerEmulatorProvisioner = void 0;
+var spanner_1 = require("@google-cloud/spanner");
+/**
+ * Shared test-harness provisioning for the Spanner emulator.
+ *
+ * The emulator holds instances IN MEMORY — any container restart (Docker updates, host reboots,
+ * fresh CI service containers) silently wipes them, and every suite then fast-fails with a
+ * cryptic gRPC "Instance not found" until someone re-provisions by hand. Harnesses call
+ * `ensureProvisioned` in beforeAll; it is idempotent (ALREADY_EXISTS answers are success) and
+ * gated on `SPANNER_EMULATOR_HOST`, so it can never touch real GCP.
+ *
+ * Provisioning uses the ADMIN API over gRPC on the SAME address the suites' data client uses —
+ * no second endpoint to derive or configure, any docker port mapping works (the emulator's REST
+ * port doesn't even need publishing), and it shares the data client's exact fate: if the address
+ * is wrong, no suite could pass anyway.
+ *
+ * @internal This class is intended to be used only in tests. Do not use it in production code.
+ */
+var SpannerEmulatorProvisioner = /** @class */ (function () {
+    function SpannerEmulatorProvisioner() {
+    }
+    /** Ensure the instance + database exist on the emulator. No-op without SPANNER_EMULATOR_HOST. */
+    SpannerEmulatorProvisioner.ensureProvisioned = function (config) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function () {
+            var spanner, instance, _b, operation, error_1, _c, operation, error_2;
+            return __generator(this, function (_d) {
+                switch (_d.label) {
+                    case 0:
+                        if (!process.env.SPANNER_EMULATOR_HOST) {
+                            return [2 /*return*/];
+                        }
+                        spanner = (_a = SpannerEmulatorProvisioner.client) !== null && _a !== void 0 ? _a : new spanner_1.Spanner({ projectId: config.projectId });
+                        SpannerEmulatorProvisioner.client = spanner;
+                        instance = spanner.instance(config.instanceName);
+                        _d.label = 1;
+                    case 1:
+                        _d.trys.push([1, 4, , 5]);
+                        return [4 /*yield*/, instance.create({
+                                config: 'emulator-config',
+                                displayName: "".concat(config.instanceName, " (test)"),
+                                nodes: 1,
+                            })];
+                    case 2:
+                        _b = _d.sent(), operation = _b[1];
+                        return [4 /*yield*/, operation.promise()];
+                    case 3:
+                        _d.sent();
+                        return [3 /*break*/, 5];
+                    case 4:
+                        error_1 = _d.sent();
+                        SpannerEmulatorProvisioner.swallowAlreadyExists(error_1);
+                        return [3 /*break*/, 5];
+                    case 5:
+                        _d.trys.push([5, 8, , 9]);
+                        return [4 /*yield*/, instance.createDatabase(config.databaseName)];
+                    case 6:
+                        _c = _d.sent(), operation = _c[1];
+                        return [4 /*yield*/, operation.promise()];
+                    case 7:
+                        _d.sent();
+                        return [3 /*break*/, 9];
+                    case 8:
+                        error_2 = _d.sent();
+                        SpannerEmulatorProvisioner.swallowAlreadyExists(error_2);
+                        return [3 /*break*/, 9];
+                    case 9: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /** Close the admin client — call from afterAll so jest's event loop can drain. */
+    SpannerEmulatorProvisioner.release = function () {
+        var _a;
+        try {
+            (_a = SpannerEmulatorProvisioner.client) === null || _a === void 0 ? void 0 : _a.close();
+        }
+        finally {
+            SpannerEmulatorProvisioner.client = undefined;
+        }
+    };
+    SpannerEmulatorProvisioner.swallowAlreadyExists = function (error) {
+        if (error.code !== 6 /* gRPC ALREADY_EXISTS */) {
+            throw error;
+        }
+    };
+    return SpannerEmulatorProvisioner;
+}());
+exports.SpannerEmulatorProvisioner = SpannerEmulatorProvisioner;
+//# sourceMappingURL=SpannerEmulatorProvisioner.js.map

package/dist/test/util/SpannerEmulatorProvisioner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpannerEmulatorProvisioner.js","sourceRoot":"","sources":["../../../test/util/SpannerEmulatorProvisioner.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,iDAAgD;AAEhD;;;;;;;;;;;;;;;GAeG;AACH;IAAA;IAiDA,CAAC;IA5CC,iGAAiG;IACpF,4CAAiB,GAA9B,UAA+B,MAI9B;;;;;;;wBACC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,EAAE;4BACtC,sBAAO;yBACR;wBACK,OAAO,GAAG,MAAA,0BAA0B,CAAC,MAAM,mCAAI,IAAI,iBAAO,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;wBAClG,0BAA0B,CAAC,MAAM,GAAG,OAAO,CAAC;wBACtC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;;;;wBAE/B,qBAAM,QAAQ,CAAC,MAAM,CAAC;gCAC1C,MAAM,EAAE,iBAAiB;gCACzB,WAAW,EAAE,UAAG,MAAM,CAAC,YAAY,YAAS;gCAC5C,KAAK,EAAE,CAAC;6BACT,CAAC,EAAA;;wBAJI,KAAgB,SAIpB,EAJO,SAAS,QAAA;wBAKlB,qBAAM,SAAS,CAAC,OAAO,EAAE,EAAA;;wBAAzB,SAAyB,CAAC;;;;wBAE1B,0BAA0B,CAAC,oBAAoB,CAAC,OAAK,CAAC,CAAC;;;;wBAGjC,qBAAM,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,YAAY,CAAC,EAAA;;wBAAlE,KAAgB,SAAkD,EAA/D,SAAS,QAAA;wBAClB,qBAAM,SAAS,CAAC,OAAO,EAAE,EAAA;;wBAAzB,SAAyB,CAAC;;;;wBAE1B,0BAA0B,CAAC,oBAAoB,CAAC,OAAK,CAAC,CAAC;;;;;;KAE1D;IAED,kFAAkF;IAC3E,kCAAO,GAAd;;QACE,IAAI;YACF,MAAA,0BAA0B,CAAC,MAAM,0CAAE,KAAK,EAAE,CAAC;SAC5C;gBAAS;YACR,0BAA0B,CAAC,MAAM,GAAG,SAAS,CAAC;SAC/C;IACH,CAAC;IAEc,+CAAoB,GAAnC,UAAoC,KAAc;QAChD,IAAK,KAA2B,CAAC,IAAI,KAAK,CAAC,CAAC,yBAAyB,EAAE;YACrE,MAAM,KAAK,CAAC;SACb;IACH,CAAC;IACH,iCAAC;AAAD,CAAC,AAjDD,IAiDC;AAjDY,gEAA0B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db-driver-spanner",
-  "version": "1.10.20",
+  "version": "1.11.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -42,16 +42,16 @@
   },
   "dependencies": {
     "@google-cloud/spanner": "7.5.0",
-    "@proteinjs/db": "^1.22.1",
-    "@proteinjs/db-query": "^1.4.8",
-    "@proteinjs/db-spanner-common": "^1.1.34",
-    "@proteinjs/db-transaction-context": "^0.2.33",
-    "@proteinjs/logger": "^1.0.19",
+    "@proteinjs/db": "^1.22.2",
+    "@proteinjs/db-query": "^1.4.9",
+    "@proteinjs/db-spanner-common": "^1.1.35",
+    "@proteinjs/db-transaction-context": "^0.2.34",
+    "@proteinjs/logger": "^1.0.20",
     "@proteinjs/reflection": "^1.1.11",
     "@proteinjs/util": "^1.6.0"
   },
   "devDependencies": {
-    "@proteinjs/reflection-build": "^1.4.7",
+    "@proteinjs/reflection-build": "^1.4.8",
     "@types/jest": "29.5.5",
     "@types/node": "14.0.27",
     "@typescript-eslint/eslint-plugin": "7.8.0",
@@ -63,5 +63,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "ae0911591d51c066ccf1f42526788401c8f153c6"
+  "gitHead": "fd394c848fa43ee594de4c84c827a607cddca3db"
 }

package/test/index.ts

@@ -1 +1,2 @@
 export * from './util/getDropTestTable';
+export * from './util/SpannerEmulatorProvisioner';

package/test/util/SpannerEmulatorProvisioner.ts

@@ -0,0 +1,68 @@
+import { Spanner } from '@google-cloud/spanner';
+
+/**
+ * Shared test-harness provisioning for the Spanner emulator.
+ *
+ * The emulator holds instances IN MEMORY — any container restart (Docker updates, host reboots,
+ * fresh CI service containers) silently wipes them, and every suite then fast-fails with a
+ * cryptic gRPC "Instance not found" until someone re-provisions by hand. Harnesses call
+ * `ensureProvisioned` in beforeAll; it is idempotent (ALREADY_EXISTS answers are success) and
+ * gated on `SPANNER_EMULATOR_HOST`, so it can never touch real GCP.
+ *
+ * Provisioning uses the ADMIN API over gRPC on the SAME address the suites' data client uses —
+ * no second endpoint to derive or configure, any docker port mapping works (the emulator's REST
+ * port doesn't even need publishing), and it shares the data client's exact fate: if the address
+ * is wrong, no suite could pass anyway.
+ *
+ * @internal This class is intended to be used only in tests. Do not use it in production code.
+ */
+export class SpannerEmulatorProvisioner {
+  /** Kept until release(): closing right after the create-operations races their trailing LRO
+   *  callbacks into an unhandled "client has already been closed" that fails the suite. */
+  private static client: Spanner | undefined;
+
+  /** Ensure the instance + database exist on the emulator. No-op without SPANNER_EMULATOR_HOST. */
+  static async ensureProvisioned(config: {
+    projectId: string;
+    instanceName: string;
+    databaseName: string;
+  }): Promise<void> {
+    if (!process.env.SPANNER_EMULATOR_HOST) {
+      return;
+    }
+    const spanner = SpannerEmulatorProvisioner.client ?? new Spanner({ projectId: config.projectId });
+    SpannerEmulatorProvisioner.client = spanner;
+    const instance = spanner.instance(config.instanceName);
+    try {
+      const [, operation] = await instance.create({
+        config: 'emulator-config',
+        displayName: `${config.instanceName} (test)`,
+        nodes: 1,
+      });
+      await operation.promise();
+    } catch (error) {
+      SpannerEmulatorProvisioner.swallowAlreadyExists(error);
+    }
+    try {
+      const [, operation] = await instance.createDatabase(config.databaseName);
+      await operation.promise();
+    } catch (error) {
+      SpannerEmulatorProvisioner.swallowAlreadyExists(error);
+    }
+  }
+
+  /** Close the admin client — call from afterAll so jest's event loop can drain. */
+  static release(): void {
+    try {
+      SpannerEmulatorProvisioner.client?.close();
+    } finally {
+      SpannerEmulatorProvisioner.client = undefined;
+    }
+  }
+
+  private static swallowAlreadyExists(error: unknown): void {
+    if ((error as { code?: number }).code !== 6 /* gRPC ALREADY_EXISTS */) {
+      throw error;
+    }
+  }
+}