@tumbaland/backend-core 1.20.0 → 1.22.0

package/dist/database/connection.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Connects once and throws on failure. There is deliberately no retry loop here.
+ *
+ * MongoDB is Atlas (`mongodb+srv://`), not a sidecar container, so there is no
+ * boot race to ride out — and the driver already retries for us: `connect()`
+ * keeps doing server selection for `serverSelectionTimeoutMS` (30s by default)
+ * before it rejects, so a transient DNS or network blip is absorbed there.
+ * Anything that survives that is a real fault — bad credentials, an IP missing
+ * from the Atlas allowlist, a dead cluster — and no amount of retrying fixes it.
+ *
+ * Callers exit non-zero when this throws, which hands the problem to the
+ * container restart policy (`restart: unless-stopped`) that already supervises
+ * every service. One supervisor, and a service that can't reach its database
+ * shows up as a restarting container instead of a healthy one serving errors.
+ */
 export declare const connectDB: (serviceName?: string, uri?: string) => Promise<void>;
 export declare const disconnectDB: (serviceName?: string) => Promise<void>;
 //# sourceMappingURL=connection.d.ts.map

package/dist/database/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/database/connection.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,SAAS,GAAU,cAAc,MAAM,EAAE,MAAM,MAAM,KAAG,OAAO,CAAC,IAAI,CA6BhF,CAAC;AAEF,eAAO,MAAM,YAAY,GAAU,cAAc,MAAM,KAAG,OAAO,CAAC,IAAI,CASrE,CAAC"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/database/connection.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,SAAS,GAAU,cAAc,MAAM,EAAE,MAAM,MAAM,KAAG,OAAO,CAAC,IAAI,CAchF,CAAC;AAwCF,eAAO,MAAM,YAAY,GAAU,cAAc,MAAM,KAAG,OAAO,CAAC,IAAI,CASrE,CAAC"}

package/dist/database/connection.js

@@ -7,33 +7,76 @@ exports.disconnectDB = exports.connectDB = void 0;
 const mongoose_1 = __importDefault(require("mongoose"));
 const logger_1 = __importDefault(require("../logging/logger"));
 let connected = false;
+/**
+ * Set while a connection attempt is in flight so concurrent callers await that
+ * attempt instead of opening a second one against the same mongoose singleton.
+ */
+let pending = null;
+let listenersRegistered = false;
+/**
+ * Connects once and throws on failure. There is deliberately no retry loop here.
+ *
+ * MongoDB is Atlas (`mongodb+srv://`), not a sidecar container, so there is no
+ * boot race to ride out — and the driver already retries for us: `connect()`
+ * keeps doing server selection for `serverSelectionTimeoutMS` (30s by default)
+ * before it rejects, so a transient DNS or network blip is absorbed there.
+ * Anything that survives that is a real fault — bad credentials, an IP missing
+ * from the Atlas allowlist, a dead cluster — and no amount of retrying fixes it.
+ *
+ * Callers exit non-zero when this throws, which hands the problem to the
+ * container restart policy (`restart: unless-stopped`) that already supervises
+ * every service. One supervisor, and a service that can't reach its database
+ * shows up as a restarting container instead of a healthy one serving errors.
+ */
 const connectDB = async (serviceName, uri) => {
     if (connected)
         return;
+    if (pending)
+        return pending;
     const mongoUri = uri || process.env.MONGODB_URI;
     if (!mongoUri) {
         throw new Error('MONGODB_URI environment variable is not set');
     }
+    pending = connectOnce(mongoUri, serviceName).finally(() => {
+        pending = null;
+    });
+    return pending;
+};
+exports.connectDB = connectDB;
+async function connectOnce(mongoUri, serviceName) {
     try {
         await mongoose_1.default.connect(mongoUri);
         connected = true;
+        registerConnectionListeners(serviceName);
         logger_1.default.info('MongoDB connected', { service: serviceName });
-        mongoose_1.default.connection.on('error', (err) => {
-            logger_1.default.error('MongoDB connection error', { service: serviceName, error: err.message });
-        });
-        mongoose_1.default.connection.on('disconnected', () => {
-            logger_1.default.warn('MongoDB disconnected', { service: serviceName });
-        });
-        mongoose_1.default.connection.on('reconnected', () => {
-            logger_1.default.info('MongoDB reconnected', { service: serviceName });
-        });
     }
     catch (error) {
-        logger_1.default.error('Failed to connect to MongoDB', { service: serviceName, error: error.message });
+        logger_1.default.error('Failed to connect to MongoDB', {
+            service: serviceName,
+            error: error.message
+        });
         throw error;
     }
-};
-exports.connectDB = connectDB;
+}
+/**
+ * Mongoose reconnects on its own once an initial connection has succeeded, so
+ * these only report state — but without them a drop is silent and the only
+ * symptom is the health endpoint flipping to "disconnected".
+ */
+function registerConnectionListeners(serviceName) {
+    if (listenersRegistered)
+        return;
+    listenersRegistered = true;
+    mongoose_1.default.connection.on('error', (err) => {
+        logger_1.default.error('MongoDB connection error', { service: serviceName, error: err.message });
+    });
+    mongoose_1.default.connection.on('disconnected', () => {
+        logger_1.default.warn('MongoDB disconnected', { service: serviceName });
+    });
+    mongoose_1.default.connection.on('reconnected', () => {
+        logger_1.default.info('MongoDB reconnected', { service: serviceName });
+    });
+}
 const disconnectDB = async (serviceName) => {
     try {
         await mongoose_1.default.connection.close();

package/dist/database/connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/database/connection.ts"],"names":[],"mappings":";;;;;;AAAA,wDAAgC;AAChC,+DAAuC;AAEvC,IAAI,SAAS,GAAG,KAAK,CAAC;AAEf,MAAM,SAAS,GAAG,KAAK,EAAE,WAAoB,EAAE,GAAY,EAAiB,EAAE;IACnF,IAAI,SAAS;QAAE,OAAO;IAEtB,MAAM,QAAQ,GAAG,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IAChD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IAED,IAAI,CAAC;QACH,MAAM,kBAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjC,SAAS,GAAG,IAAI,CAAC;QAEjB,gBAAM,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;QAE3D,kBAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;YAC7C,gBAAM,CAAC,KAAK,CAAC,0BAA0B,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACzF,CAAC,CAAC,CAAC;QAEH,kBAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,cAAc,EAAE,GAAG,EAAE;YAC1C,gBAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;QAEH,kBAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,aAAa,EAAE,GAAG,EAAE;YACzC,gBAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;QAC/D,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gBAAM,CAAC,KAAK,CAAC,8BAA8B,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAG,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACxG,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC,CAAC;AA7BW,QAAA,SAAS,aA6BpB;AAEK,MAAM,YAAY,GAAG,KAAK,EAAE,WAAoB,EAAiB,EAAE;IACxE,IAAI,CAAC;QACH,MAAM,kBAAQ,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QAClC,SAAS,GAAG,KAAK,CAAC;QAClB,gBAAM,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;IACrE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gBAAM,CAAC,KAAK,CAAC,kCAAkC,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAG,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5G,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC,CAAC;AATW,QAAA,YAAY,gBASvB"}
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/database/connection.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tumbaland/backend-core",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "Core shared functionality for Tumbaland backend services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,7 @@
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run clean && npm run build",
-    "release": "commit-and-tag-version && npm run build && npm publish --access public",
+    "release": "commit-and-tag-version && npm run build && npm publish --access public && node ../../scripts/sync-lib-versions.mjs",
     "release:beta": "commit-and-tag-version --prerelease beta && npm run build && npm publish --access public --tag beta",
     "test": "jest",
     "test:coverage": "jest --coverage",

package/src/database/connection.test.ts

@@ -23,10 +23,15 @@ import logger from '../logging/logger';
 import { disconnectDB } from './connection';
 
 /**
- * `connection.ts` keeps a module-level `connected` flag, so each connectDB
- * scenario needs its own fresh copy of the module (and of its mongoose/logger
- * mocks) — isolateModulesAsync sandboxes that without leaking into other
- * tests in this file the way a blanket jest.resetModules() would.
+ * `connection.ts` keeps module-level `connected`/`pending` flags, so each
+ * connectDB scenario needs its own fresh copy of the module —
+ * isolateModulesAsync sandboxes that without leaking into other tests in this
+ * file the way a blanket jest.resetModules() would.
+ *
+ * Note that this does NOT re-create the mongoose/logger mocks: a jest.mock
+ * factory result is shared across isolated registries, so the objects returned
+ * here are the same instances every time. Resetting their implementations is
+ * beforeEach's job — see the comment there.
  */
 async function freshConnectDB() {
   let connectDBFn!: typeof import('./connection').connectDB;
@@ -49,6 +54,12 @@ describe('connectDB', () => {
     process.env = { ...ORIGINAL_ENV };
     delete process.env.MONGODB_URI;
     for (const key of Object.keys(connectionHandlers)) delete connectionHandlers[key];
+
+    // `clearMocks: true` only clears recorded calls, not implementations, so a
+    // mockRejectedValue set by one test stays installed for every test after
+    // it. Reset connect explicitly — but not connection.on, whose factory
+    // implementation is what records into connectionHandlers.
+    (mongoose.connect as jest.Mock).mockReset();
   });
 
   afterAll(() => {
@@ -101,6 +112,41 @@ describe('connectDB', () => {
     });
   });
 
+  /**
+   * The driver retries internally for serverSelectionTimeoutMS; anything that
+   * reaches us is a real fault, so one failure is one rejection. Callers exit
+   * non-zero and the container restart policy takes it from there.
+   */
+  it('does not retry a failed connection', async () => {
+    process.env.MONGODB_URI = 'mongodb://env-uri';
+    const { connectDB, mongoose } = await freshConnectDB();
+    (mongoose.connect as jest.Mock).mockRejectedValue(new Error('auth failed'));
+
+    await expect(connectDB('my-service')).rejects.toThrow('auth failed');
+
+    expect(mongoose.connect).toHaveBeenCalledTimes(1);
+  });
+
+  it('clears the in-flight promise so a later call can retry', async () => {
+    process.env.MONGODB_URI = 'mongodb://env-uri';
+    const { connectDB, mongoose } = await freshConnectDB();
+    (mongoose.connect as jest.Mock).mockRejectedValueOnce(new Error('not ready'));
+
+    await expect(connectDB('my-service')).rejects.toThrow('not ready');
+    await connectDB('my-service');
+
+    expect(mongoose.connect).toHaveBeenCalledTimes(2);
+  });
+
+  it('lets concurrent callers share one connection attempt', async () => {
+    process.env.MONGODB_URI = 'mongodb://env-uri';
+    const { connectDB, mongoose } = await freshConnectDB();
+
+    await Promise.all([connectDB('my-service'), connectDB('my-service')]);
+
+    expect(mongoose.connect).toHaveBeenCalledTimes(1);
+  });
+
   it('registers error/disconnected/reconnected handlers that log through the shared logger', async () => {
     process.env.MONGODB_URI = 'mongodb://env-uri';
     const { connectDB, logger } = await freshConnectDB();

package/src/database/connection.ts

@@ -2,37 +2,81 @@ import mongoose from 'mongoose';
 import logger from '../logging/logger';
 
 let connected = false;
+/**
+ * Set while a connection attempt is in flight so concurrent callers await that
+ * attempt instead of opening a second one against the same mongoose singleton.
+ */
+let pending: Promise<void> | null = null;
+let listenersRegistered = false;
 
+/**
+ * Connects once and throws on failure. There is deliberately no retry loop here.
+ *
+ * MongoDB is Atlas (`mongodb+srv://`), not a sidecar container, so there is no
+ * boot race to ride out — and the driver already retries for us: `connect()`
+ * keeps doing server selection for `serverSelectionTimeoutMS` (30s by default)
+ * before it rejects, so a transient DNS or network blip is absorbed there.
+ * Anything that survives that is a real fault — bad credentials, an IP missing
+ * from the Atlas allowlist, a dead cluster — and no amount of retrying fixes it.
+ *
+ * Callers exit non-zero when this throws, which hands the problem to the
+ * container restart policy (`restart: unless-stopped`) that already supervises
+ * every service. One supervisor, and a service that can't reach its database
+ * shows up as a restarting container instead of a healthy one serving errors.
+ */
 export const connectDB = async (serviceName?: string, uri?: string): Promise<void> => {
   if (connected) return;
+  if (pending) return pending;
 
   const mongoUri = uri || process.env.MONGODB_URI;
   if (!mongoUri) {
     throw new Error('MONGODB_URI environment variable is not set');
   }
 
+  pending = connectOnce(mongoUri, serviceName).finally(() => {
+    pending = null;
+  });
+
+  return pending;
+};
+
+async function connectOnce(mongoUri: string, serviceName: string | undefined): Promise<void> {
   try {
     await mongoose.connect(mongoUri);
     connected = true;
 
+    registerConnectionListeners(serviceName);
     logger.info('MongoDB connected', { service: serviceName });
-
-    mongoose.connection.on('error', (err: Error) => {
-      logger.error('MongoDB connection error', { service: serviceName, error: err.message });
-    });
-
-    mongoose.connection.on('disconnected', () => {
-      logger.warn('MongoDB disconnected', { service: serviceName });
-    });
-
-    mongoose.connection.on('reconnected', () => {
-      logger.info('MongoDB reconnected', { service: serviceName });
-    });
   } catch (error) {
-    logger.error('Failed to connect to MongoDB', { service: serviceName, error: (error as Error).message });
+    logger.error('Failed to connect to MongoDB', {
+      service: serviceName,
+      error: (error as Error).message
+    });
     throw error;
   }
-};
+}
+
+/**
+ * Mongoose reconnects on its own once an initial connection has succeeded, so
+ * these only report state — but without them a drop is silent and the only
+ * symptom is the health endpoint flipping to "disconnected".
+ */
+function registerConnectionListeners(serviceName?: string): void {
+  if (listenersRegistered) return;
+  listenersRegistered = true;
+
+  mongoose.connection.on('error', (err: Error) => {
+    logger.error('MongoDB connection error', { service: serviceName, error: err.message });
+  });
+
+  mongoose.connection.on('disconnected', () => {
+    logger.warn('MongoDB disconnected', { service: serviceName });
+  });
+
+  mongoose.connection.on('reconnected', () => {
+    logger.info('MongoDB reconnected', { service: serviceName });
+  });
+}
 
 export const disconnectDB = async (serviceName?: string): Promise<void> => {
   try {