@tumbaland/backend-core 1.16.0 → 1.17.0

package/README.md

@@ -120,54 +120,15 @@ This library is optimized for Docker deployments:
 
 ## 📦 Releases & Versioning
 
-This library uses [standard-version](https://github.com/conventional-changelog/standard-version) for automated versioning and follows [Conventional Commits](https://conventionalcommits.org/) specification.
-
-### Release Types
-
-- **PATCH** (`1.0.0` → `1.0.1`): Bug fixes
-- **MINOR** (`1.0.0` → `1.1.0`): New features (backward compatible)
-- **MAJOR** (`1.0.0` → `2.0.0`): Breaking changes
-
-### Commit Message Format
-
-```
-type(scope): description
-
-[optional body]
-
-[optional footer]
-```
-
-**Types:**
-- `feat`: New feature
-- `fix`: Bug fix
-- `docs`: Documentation
-- `style`: Code style changes
-- `refactor`: Code refactoring
-- `test`: Testing
-- `chore`: Maintenance
-
-**Examples:**
-```
-feat(auth): add JWT token refresh
-fix(logging): resolve memory leak in Winston transport
-docs(api): update health check endpoint documentation
-```
-
-### Release Process
-
-1. **Make changes** with conventional commit messages
-2. **Run release script**: `./release.sh`
-3. **Push changes**: `git push origin main`
-4. **Publish**: Automated via GitHub Actions
-
-### Changelog
-
-Changelogs are maintained at the project level in the root `CHANGELOG.md` file. Individual library changelogs are not generated to maintain consistency across the monorepo.
-
-### Beta Releases
-
-For beta releases: `npm run release:beta`
+This library is a real published npm package (`@tumbaland/backend-core`), versioned independently
+of the monorepo with [standard-version](https://github.com/conventional-changelog/standard-version)
+and [Conventional Commits](https://conventionalcommits.org/). See the root
+[README's "Commits & Releases" section](../../README.md#commits--releases) for the full process
+and the reasoning behind it — summary: commit with conventional messages, then from this directory
+run `npm run release` (never hand-edit `version` and `npm publish` directly, or the package,
+changelog, and tags drift out of sync with each other). Tags for this package are scoped as
+`backend-core-vX.Y.Z` so they can't collide with `frontend-core`'s, `components`', or the
+monorepo's own `app-vX.Y.Z` tags.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tumbaland/backend-core",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Core shared functionality for Tumbaland backend services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,6 +25,9 @@
   ],
   "author": "Tumbaland Team",
   "license": "MIT",
+  "standard-version": {
+    "tagPrefix": "backend-core-v"
+  },
   "devDependencies": {
     "@types/cookie-parser": "^1.4.10",
     "@types/cors": "^2.8.19",

package/src/app/createBaseApp.test.ts

@@ -54,6 +54,15 @@ describe('createBaseApp', () => {
     expect(second.status).toBe(429);
   });
 
+  it('uses the plain request logger (no metrics histogram) when metrics is false', async () => {
+    const app = createBaseApp({ metrics: false });
+    app.get('/ping', (_req, res) => res.json({ ok: true }));
+
+    const res = await request(app).get('/ping');
+
+    expect(res.status).toBe(200);
+  });
+
   it('mounts /health/live ahead of the rate limiter, so it never gets 429s a busy service would', async () => {
     const app = createBaseApp({ rateLimiter: (await import('../middleware/security')).createRateLimiter({ windowMs: 60_000, max: 1 }) });
     app.get('/ping', (_req, res) => res.json({ ok: true }));

package/src/health/healthController.test.ts

@@ -1,6 +1,6 @@
 import { Request, Response } from 'express';
 import mongoose from 'mongoose';
-import { healthCheck, healthLive } from './healthController';
+import { healthCheck, healthLive, metricsHandler } from './healthController';
 
 function mockRes(): Response {
   const res: Partial<Response> = {};
@@ -88,4 +88,26 @@ describe('healthCheck', () => {
     expect(res.status).toHaveBeenCalledWith(503);
     expect(res.json).toHaveBeenCalledWith(expect.objectContaining({ status: 'error', error: 'Health check failed' }));
   });
+
+  it('falls back to default service/version/description in the error body when env vars are unset', async () => {
+    delete process.env.SERVICE_NAME;
+    delete process.env.npm_package_version;
+    delete process.env.SERVICE_DESCRIPTION;
+    jest.spyOn(mongoose, 'connection', 'get').mockImplementation(() => {
+      throw new Error('boom');
+    });
+    const res = mockRes();
+
+    await healthCheck({} as Request, res);
+
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({ service: 'unknown-service', version: '1.0.0', description: 'Backend service' })
+    );
+  });
+});
+
+describe('metricsHandler re-export', () => {
+  it('re-exports the same metricsHandler function from ../metrics', () => {
+    expect(typeof metricsHandler).toBe('function');
+  });
 });

package/src/logging/logger.test.ts

@@ -35,6 +35,21 @@ describe('logger', () => {
     expect(logger.level).toBe('info');
   });
 
+  it('defaults to development (debug level) when NODE_ENV is unset', async () => {
+    const ORIGINAL_ENV = process.env;
+    const merged: Record<string, string | undefined> = { ...ORIGINAL_ENV };
+    delete merged.NODE_ENV;
+    process.env = merged as NodeJS.ProcessEnv;
+
+    let loggerModule!: typeof import('./logger').default;
+    await jest.isolateModulesAsync(async () => {
+      loggerModule = (await import('./logger')).default;
+    });
+
+    process.env = ORIGINAL_ENV;
+    expect(loggerModule.level).toBe('debug');
+  });
+
   it('does not create a file transport when LOG_TO_FILE is unset', async () => {
     const logger = await loadLogger({ NODE_ENV: 'development', LOG_TO_FILE: undefined });
     expect(namedTransports(logger, 'file')).toHaveLength(0);

package/src/metrics/index.test.ts

@@ -81,6 +81,31 @@ describe('metricsMiddleware', () => {
   });
 });
 
+describe('default labels', () => {
+  it('falls back to app "unknown-service" and version "1.0.0" when their env vars are unset', async () => {
+    const ORIGINAL_ENV = process.env;
+    const merged: Record<string, string | undefined> = { ...ORIGINAL_ENV };
+    delete merged.SERVICE_NAME;
+    delete merged.npm_package_version;
+    process.env = merged as NodeJS.ProcessEnv;
+
+    // isolateModulesAsync sandboxes the whole module registry, including
+    // prom-client itself — the spy must target the Registry class required
+    // *inside* the sandbox, not the one imported at the top of this file.
+    await jest.isolateModulesAsync(async () => {
+      const innerPromClient = (await import('prom-client')).default;
+      const setDefaultLabelsSpy = jest.spyOn(innerPromClient.Registry.prototype, 'setDefaultLabels');
+
+      await import('./index');
+
+      expect(setDefaultLabelsSpy).toHaveBeenCalledWith({ app: 'unknown-service', version: '1.0.0' });
+      setDefaultLabelsSpy.mockRestore();
+    });
+
+    process.env = ORIGINAL_ENV;
+  });
+});
+
 describe('businessMetrics', () => {
   it('exposes counters that can be incremented without throwing', () => {
     expect(() => businessMetrics.albumsCreated.inc()).not.toThrow();

package/src/middleware/validate.test.ts

@@ -57,4 +57,16 @@ describe('validate', () => {
     expect(res.status).toBe(200);
     expect(res.body.data).toEqual({ name: 'Carol' });
   });
+
+  it('omits the field prefix when the zod issue has no path (whole-body validation)', async () => {
+    const arraySchema = z.array(z.string());
+    const app = buildApp(arraySchema);
+    const rawResult = arraySchema.safeParse({ not: 'an array' });
+
+    const res = await request(app).post('/things').send({ not: 'an array' });
+
+    expect(res.status).toBe(400);
+    expect(rawResult.success).toBe(false);
+    expect(res.body.message).toBe(!rawResult.success ? rawResult.error.issues[0].message : undefined);
+  });
 });

package/src/tracing/index.test.ts

@@ -39,6 +39,7 @@ jest.mock('@opentelemetry/resources', () => ({
 }));
 
 import { context } from '@opentelemetry/api';
+import { ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
 
 async function loadTracing() {
   let tracing!: typeof import('./index');
@@ -92,6 +93,23 @@ describe('initTracer', () => {
     expect(exporterCtorMock).toHaveBeenCalledWith({ url: 'http://jaeger-endpoint/v1/traces' });
   });
 
+  it('falls back to version 1.0.0 and environment "development" when their env vars are unset', async () => {
+    const merged: Record<string, string | undefined> = { ...process.env };
+    delete merged.npm_package_version;
+    delete merged.NODE_ENV;
+    process.env = merged as NodeJS.ProcessEnv;
+
+    const { initTracer } = await loadTracing();
+    initTracer('album-service');
+
+    expect(resourceFromAttributesMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        [ATTR_SERVICE_VERSION]: '1.0.0',
+        'deployment.environment': 'development'
+      })
+    );
+  });
+
   it('registers the provider and returns a tracer scoped to the given service name', async () => {
     const { initTracer } = await loadTracing();
 

package/tsconfig.build.json

@@ -1,4 +1,7 @@
 {
   "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["node"]
+  },
   "exclude": ["node_modules", "dist", "**/*.test.ts"]
 }

package/tsconfig.json

@@ -2,13 +2,16 @@
   "compilerOptions": {
     "target": "es2023",
     "module": "commonjs",
-    "lib": ["ES2020"],
     "outDir": "./dist",
     "rootDir": "./src",
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
+    "moduleDetection": "force",
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
     "declaration": true,
     "declarationMap": true,
     "sourceMap": true,