@aurostack/stacks 0.1.0

package/templates/nest-api/files/src/common/__tests__/cache.service.spec.ts

@@ -0,0 +1,214 @@
+import { TestBed } from '@suites/unit';
+import { vi } from 'vitest';
+import { User } from '@db/client';
+import { Entity } from '@test/factory/entity';
+import { CacheService } from 'common/services';
+
+vi.mock('ioredis');
+
+describe('CacheService', () => {
+	let service: CacheService;
+	const on = vi.spyOn;
+
+	beforeAll(async () => {
+		const { unit } = await TestBed.solitary(CacheService).compile();
+		service = unit;
+	});
+
+	afterAll(async () => {
+		await service.disconnect();
+		vi.restoreAllMocks();
+	});
+
+	it('should be defined', () => {
+		expect(service).toBeDefined();
+	});
+
+	describe('store', () => {
+		describe('when EXP is undefined', () => {
+			it('should store string data with default expiry of 24hrs', async () => {
+				const key = 'example-key';
+				const data = 'exampleData';
+				on(service.db, 'setex');
+
+				await service.store(key, data);
+				expect(service.db.setex).toHaveBeenCalled();
+				expect(service.db.setex).toHaveBeenCalledWith(
+					key,
+					service.DEFAULT_EXPIRY,
+					data
+				);
+			});
+
+			it('should store object data with default expiry of 24hrs', async () => {
+				const key = 'testKey';
+				const testData = { id: 1, name: 'Test' };
+				on(service.db, 'setex');
+
+				await service.store(key, testData);
+				expect(service.db.setex).toHaveBeenCalled();
+				expect(service.db.setex).toHaveBeenCalledWith(
+					key,
+					service.DEFAULT_EXPIRY,
+					JSON.stringify(testData)
+				);
+			});
+		});
+
+		describe('otherwise', () => {
+			const EXP = 86400 * 3;
+
+			it('should store string data with specified EXP', async () => {
+				const key = 'example-key';
+				const data = 'exampleData';
+				on(service.db, 'setex');
+
+				await service.store(key, data, EXP);
+				expect(service.db.setex).toHaveBeenCalled();
+				expect(service.db.setex).toHaveBeenCalledWith(key, EXP, data);
+			});
+
+			it('should store object data with specified EXP', async () => {
+				const key = 'testKey';
+				const testData = { id: 1, name: 'Test' };
+				on(service.db, 'setex');
+
+				await service.store(key, testData, EXP);
+				expect(service.db.setex).toHaveBeenCalled();
+				expect(service.db.setex).toHaveBeenCalledWith(
+					key,
+					EXP,
+					JSON.stringify(testData)
+				);
+			});
+		});
+	});
+
+	describe('hashStore', () => {
+		it('should call hset with correct arguments', async () => {
+			const user = Entity.user.build();
+			on(service.db, 'hset');
+
+			await service.hashStore('Users', user);
+			expect(service.db.hset).toHaveBeenCalled();
+			expect(service.db.hset).toHaveBeenCalledWith(
+				'users',
+				`uid:${user.id}`,
+				JSON.stringify(user)
+			);
+		});
+	});
+
+	describe('fetch', () => {
+		describe('when data is not available', () => {
+			it('should return null', async () => {
+				on(service.db, 'get').mockResolvedValue(null);
+
+				const response = await service.fetch('example-key');
+				expect(service.db.get).toHaveBeenCalled();
+				expect(service.db.get).toHaveBeenCalledWith('example-key');
+				expect(response).toBeNull();
+			});
+		});
+
+		describe('otherwise', () => {
+			it('should return string data', async () => {
+				const data = 'example-data';
+				on(service.db, 'get').mockResolvedValue(data);
+
+				const response = await service.fetch('example-key');
+				expect(service.db.get).toHaveBeenCalled();
+				expect(service.db.get).toHaveBeenCalledWith('example-key');
+				expect(response).not.toBe(null);
+				expect(typeof response).toBe('string');
+				expect(response).toEqual(data);
+			});
+
+			it('should return object data', async () => {
+				const data = Entity.user.build();
+				on(service.db, 'get').mockResolvedValue(JSON.stringify(data));
+
+				const response = await service.fetch<User>('example-key');
+				expect(service.db.get).toHaveBeenCalled();
+				expect(service.db.get).toHaveBeenCalledWith('example-key');
+				expect(response).not.toBe(null);
+				expect(typeof response).not.toBe('string');
+				expect(response?.name).toEqual(data.name);
+			});
+		});
+	});
+
+	describe('hashFetch', () => {
+		describe('when data is not available', () => {
+			it('should return null', async () => {
+				on(service.db, 'hget').mockResolvedValue(null);
+
+				const response = await service.hashFetch('Users', 25);
+				expect(service.db.hget).toHaveBeenCalled();
+				expect(service.db.hget).toHaveBeenCalledWith('users', 'uid:25');
+				expect(response).toBe(null);
+			});
+		});
+
+		describe('otherwise', () => {
+			it('should return object', async () => {
+				const data = Entity.user.build({ id: '25' });
+				on(service.db, 'hget').mockResolvedValue(JSON.stringify(data));
+
+				const response = await service.hashFetch('Users', 25);
+				expect(service.db.hget).toHaveBeenCalled();
+				expect(service.db.hget).toHaveBeenCalledWith('users', 'uid:25');
+				expect(response).not.toBe(null);
+				// User ids are strings; the cached JSON round-trips them unchanged.
+				expect(response?.id).toBe('25');
+			});
+		});
+	});
+
+	describe('hashFetchAll', () => {
+		describe('when data is not available', () => {
+			it('should return []', async () => {
+				on(service.db, 'hvals').mockResolvedValue([]);
+
+				const response = await service.hashFetchAll('Users');
+				expect(service.db.hvals).toHaveBeenCalled();
+				expect(service.db.hvals).toHaveBeenCalledWith('users');
+				expect(response).toHaveLength(0);
+			});
+		});
+
+		describe('otherwise', () => {
+			it('should return list of objects', async () => {
+				const data = Entity.user.buildList(10);
+				on(service.db, 'hvals').mockResolvedValue(
+					data.map((item) => JSON.stringify(item))
+				);
+
+				const response = await service.hashFetchAll('Users');
+				expect(service.db.hvals).toHaveBeenCalled();
+				expect(service.db.hvals).toHaveBeenCalledWith('users');
+				expect(response).toHaveLength(10);
+			});
+		});
+	});
+
+	describe('hashDelete', () => {
+		it('should delete data with specified key', async () => {
+			on(service.db, 'hdel');
+
+			await service.hashDelete('Users', 25);
+			expect(service.db.hdel).toHaveBeenCalled();
+			expect(service.db.hdel).toHaveBeenCalledWith('users', 'uid:25');
+		});
+	});
+
+	describe('deleteKey', () => {
+		it('should delete data with specified key', async () => {
+			on(service.db, 'del');
+
+			await service.deleteKey('Users');
+			expect(service.db.del).toHaveBeenCalled();
+			expect(service.db.del).toHaveBeenCalledWith('users');
+		});
+	});
+});

package/templates/nest-api/files/src/common/__tests__/config.service.spec.ts

@@ -0,0 +1,56 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import Config from 'common/services/config.service';
+import { CustomConfigService } from 'common/services';
+
+describe('ConfigService', () => {
+	/*
+	 * Keys only — do NOT compare against this snapshot.
+	 *
+	 * `ConfigModule.forRoot()` defaults to reading `.env`, so a test run (which
+	 * `dotenv -e .env.test` has already loaded) picks up any dev-only variable
+	 * `.env.test` doesn't define — dotenv won't overwrite what's already set, but
+	 * it will add what's missing. This snapshot is taken before that happens, so
+	 * comparing against it fails on exactly those variables. It surfaced as
+	 * `cookiePrefix: '' !== 'zorinwess'` once BETTER_AUTH_COOKIE_PREFIX landed in
+	 * `.env` alone.
+	 *
+	 * Both env files are gitignored, so the fix can't live in them: read the
+	 * config again at assertion time instead, when both sides see one process.env.
+	 */
+	const values = Config.getVariables();
+	let service: CustomConfigService;
+
+	beforeAll(async () => {
+		const module: TestingModule = await Test.createTestingModule({
+			imports: [
+				ConfigModule.forRoot({
+					load: [Config.getVariables],
+					validationSchema: Config.schema
+				})
+			],
+			providers: [CustomConfigService, ConfigService]
+		}).compile();
+		service = module.get(CustomConfigService);
+	});
+
+	it('should be defined', () => {
+		expect(service).toBeDefined();
+	});
+
+	describe.each(Object.keys(values))('%s', (key) => {
+		if (['app', 'cloudinary'].includes(key)) {
+			it('should be defined', () => {
+				expect(service[key]).toBeDefined();
+			});
+		} else {
+			it('should be defined', () => {
+				expect(service[key]).toBeDefined();
+			});
+			it('should return the correct environment values', () => {
+				// Re-read rather than using the module-scope snapshot — see above.
+				expect(service[key]).toStrictEqual(Config.getVariables()[key]);
+			});
+		}
+	});
+});

package/templates/nest-api/files/src/common/__tests__/generator.service.spec.ts

@@ -0,0 +1,114 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { faker as F } from '@faker-js/faker';
+import moment from 'moment';
+import { GeneratorService } from 'common/services';
+
+describe('GeneratorService', () => {
+	let service: GeneratorService;
+
+	beforeAll(async () => {
+		const module: TestingModule = await Test.createTestingModule({
+			providers: [GeneratorService]
+		}).compile();
+
+		service = module.get(GeneratorService);
+	});
+
+	it('should be defined', () => {
+		expect(service).toBeDefined();
+	});
+
+	describe('avatar', () => {
+		it('should return avatar url based on name', () => {
+			const name = `${F.person.firstName()} ${F.person.lastName()}`;
+			const expectedSeed = name.toLowerCase().replace(' ', '+');
+			const avatar = service.avatar(name);
+			expect(avatar).toBe(
+				`https://api.dicebear.com/7.x/initials/png?seed=${expectedSeed}%size=500`
+			);
+		});
+	});
+
+	describe('numeric', () => {
+		it('should return an integer string of specified length', () => {
+			const six = service.numeric(6);
+			const ten = service.numeric(10);
+			expect(six).toMatch(/^\d{6}$/);
+			expect(ten).toMatch(/^\d{10}$/);
+		});
+	});
+
+	describe('currentDate', () => {
+		it('should return the current UTC date as YYYY-MM-DD', () => {
+			vi.useFakeTimers();
+			vi.setSystemTime(new Date('2026-06-08T15:30:45.000Z'));
+			expect(service.currentDate()).toBe('2026-06-08');
+			vi.useRealTimers();
+		});
+	});
+
+	describe('currentHour', () => {
+		it('should return the current UTC hour bucket as YYYY-MM-DDTHH', () => {
+			vi.useFakeTimers();
+			vi.setSystemTime(new Date('2026-06-08T15:30:45.000Z'));
+			expect(service.currentHour()).toBe('2026-06-08T15');
+			vi.useRealTimers();
+		});
+	});
+
+	describe('addPrefix', () => {
+		it('should join prefix and text with the default delimiter', () => {
+			expect(service.addPrefix('sync', '2026-06-08T15')).toBe(
+				'sync:2026-06-08T15'
+			);
+		});
+
+		it('should honour a custom delimiter', () => {
+			expect(service.addPrefix('sync', 'today', '/')).toBe('sync/today');
+		});
+	});
+
+	describe('alphabet', () => {
+		describe('when SIZE not provided', () => {
+			it('should return a 128 character hex string (64 bytes)', () => {
+				expect(service.alphabet()).toEqual(expect.any(String));
+				expect(service.alphabet().length).toBe(128);
+			});
+		});
+
+		describe('otherwise', () => {
+			it('should return string of length [2 * SIZE]', () => {
+				expect(service.alphabet(8).length).toBe(16);
+				expect(service.alphabet(16).length).toBe(32);
+				expect(service.alphabet(32).length).toBe(64);
+			});
+		});
+
+		describe('uuid', () => {
+			it('should return a valid UUID v4 string', () => {
+				const id = service.uuid();
+				const uuidV4Regex =
+					/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+				expect(id).toMatch(uuidV4Regex);
+			});
+		});
+
+		describe('now', () => {
+			it('should return current UTC moment instance', () => {
+				const now = service.now();
+				expect(moment.isMoment(now)).toBe(true);
+				expect(now.isUTC()).toBe(true);
+			});
+		});
+
+		describe('expiry', () => {
+			it('should return moment with added duration', () => {
+				const base = service.now();
+				const expiry = service.expiry(10, 'minutes');
+				expect(moment.isMoment(expiry)).toBe(true);
+				const diff = expiry.diff(base, 'minutes');
+				expect(diff).toBe(10);
+			});
+		});
+	});
+});

package/templates/nest-api/files/src/common/__tests__/health.controller.spec.ts

@@ -0,0 +1,72 @@
+import { TestBed, type Mocked } from '@suites/unit';
+import {
+	HealthCheckService,
+	HttpHealthIndicator,
+	DiskHealthIndicator,
+	MemoryHealthIndicator
+} from '@nestjs/terminus';
+import { HealthController } from 'common/controllers/health.controller';
+import { PrismaHealthIndicator } from 'common/misc/prisma.indicator';
+import { CustomConfigService } from 'common/services';
+
+describe('HealthController', () => {
+	let controller: HealthController;
+	let health: Mocked<HealthCheckService>;
+	let http: Mocked<HttpHealthIndicator>;
+	let prisma: Mocked<PrismaHealthIndicator>;
+	let disk: Mocked<DiskHealthIndicator>;
+	let memory: Mocked<MemoryHealthIndicator>;
+	let config: Mocked<CustomConfigService>;
+
+	beforeAll(async () => {
+		const { unit, unitRef } =
+			await TestBed.solitary(HealthController).compile();
+		controller = unit;
+		health = unitRef.get(HealthCheckService);
+		http = unitRef.get(HttpHealthIndicator);
+		prisma = unitRef.get(PrismaHealthIndicator);
+		disk = unitRef.get(DiskHealthIndicator);
+		memory = unitRef.get(MemoryHealthIndicator);
+		config = unitRef.get(CustomConfigService);
+	});
+
+	it('should be defined', () => {
+		expect(controller).toBeDefined();
+	});
+
+	it('should delegate to HealthCheckService.check with proper indicators', async () => {
+		config.app = { host: 'http://localhost:5000' } as any;
+		// Non-default values, so the assertions prove config reaches the checks.
+		config.health = {
+			heapMaxMb: 512,
+			rssMaxMb: 768,
+			diskThreshold: 0.9,
+			diskPath: '/data'
+		};
+		health.check.mockImplementation(async (fns) => {
+			for (const fn of fns) {
+				if (typeof fn === 'function') await fn();
+			}
+			return { status: 'ok' } as any;
+		});
+		http.pingCheck.mockResolvedValue({} as any);
+		prisma.isHealthy.mockResolvedValue({} as any);
+		memory.checkHeap.mockResolvedValue({} as any);
+		memory.checkRSS.mockResolvedValue({} as any);
+		disk.checkStorage.mockResolvedValue({} as any);
+
+		const result = await controller.check();
+
+		expect(health.check).toHaveBeenCalled();
+		expect(http.pingCheck).toHaveBeenCalledWith('http', config.app.host);
+		expect(prisma.isHealthy).toHaveBeenCalledWith('database');
+		const MB = 1024 * 1024;
+		expect(memory.checkHeap).toHaveBeenCalledWith('memory_heap', 512 * MB);
+		expect(memory.checkRSS).toHaveBeenCalledWith('memory_rss', 768 * MB);
+		expect(disk.checkStorage).toHaveBeenCalledWith('disk_storage', {
+			thresholdPercent: 0.9,
+			path: '/data'
+		});
+		expect(result).toEqual({ status: 'ok' });
+	});
+});

package/templates/nest-api/files/src/common/__tests__/helpers.spec.ts

@@ -0,0 +1,124 @@
+import { Gen } from '@test/factory/gen';
+import * as helper from 'common/utils';
+
+describe('Helpers', () => {
+	describe('getRandomArrayItem', () => {
+		it('should return an array item', () => {
+			const arr = [35, 55, 78, 854, 784, 885, 4415];
+			const item = helper.getRandomArrayItem(arr);
+			expect(item).not.toBeUndefined();
+			expect(arr).toContain(item);
+		});
+	});
+
+	describe('parseBoolean', () => {
+		it('should return true', () => {
+			expect(helper.parseBoolean('true')).toBe(true);
+			expect(helper.parseBoolean('   true   ')).toBe(true);
+			expect(helper.parseBoolean('1')).toBe(true);
+			expect(helper.parseBoolean(1)).toBe(true);
+			expect(helper.parseBoolean('yes')).toBe(true);
+		});
+
+		it('should return false', () => {
+			expect(helper.parseBoolean('false')).toBe(false);
+			expect(helper.parseBoolean('   false   ')).toBe(false);
+			expect(helper.parseBoolean('0')).toBe(false);
+			expect(helper.parseBoolean(0)).toBe(false);
+			expect(helper.parseBoolean('no')).toBe(false);
+		});
+	});
+
+	describe('getPaginationInfo', () => {
+		it('should return default object', () => {
+			const info = helper.getPaginationInfo({});
+			expect(info.skip).toBe(0);
+			expect(info.take).toBe(10);
+			expect(info.page).toBe(1);
+		});
+
+		it('should return object with page size of 5', () => {
+			const info = helper.getPaginationInfo({ limit: 5 });
+			expect(info.skip).toBe(0);
+			expect(info.take).toBe(5);
+			expect(info.page).toBe(1);
+		});
+
+		it('should return object specified current page and page size', () => {
+			const info = helper.getPaginationInfo({ limit: 4, page: 10 });
+			expect(info.skip).toBe(36);
+			expect(info.take).toBe(4);
+			expect(info.page).toBe(10);
+		});
+	});
+
+	describe('lowercase', () => {
+		it('should return trimmed string', () => {
+			expect(helper.lowercase('  Hello World  ')).toBe('hello world');
+		});
+
+		it('should return lowercase string', () => {
+			expect(helper.lowercase('Hello World')).toBe('hello world');
+		});
+
+		it('should return capitalized (only first letter) string', () => {
+			expect(helper.lowercase('Hello World', true)).toBe('Hello world');
+		});
+	});
+
+	describe('isValidUUID', () => {
+		it('should return TRUE for valid UUID v4 string', () => {
+			expect(helper.isValidUUID(Gen.uuid())).toBe(true);
+		});
+
+		it('should return FALSE for invalid UUID v4 string', () => {
+			expect(helper.isValidUUID('not_a_valid_uuid')).toBe(false);
+		});
+	});
+
+	describe('isInEnum', () => {
+		it('should return TRUE when value exists in enum', () => {
+			// Using UploadFolder enum from helper.Enum
+			const { Enum } = helper;
+			expect(
+				helper.isInEnum(
+					[Enum.UploadFolder.AVATARS, Enum.UploadFolder.UPLOAD],
+					Enum.UploadFolder.AVATARS as any
+				)
+			).toBe(true);
+		});
+
+		it('should return FALSE when value does not exist in enum', () => {
+			const { Enum } = helper;
+			expect(
+				helper.isInEnum(
+					[Enum.UploadFolder.AVATARS, Enum.UploadFolder.UPLOAD],
+					'invalid' as any
+				)
+			).toBe(false);
+		});
+	});
+
+	describe('createSortObject', () => {
+		it('should create sort objects from simple sort string', () => {
+			const sort = 'name,-createdAt';
+			const result = helper.createSortObject(sort);
+
+			expect(result).toEqual([{ name: 'asc' }, { createdAt: 'desc' }]);
+		});
+
+		it('should create nested sort objects when nesting is provided', () => {
+			const result = helper.createSortObject({
+				sort: 'name,-posts',
+				nesting: [
+					{
+						key: 'user',
+						values: ['posts']
+					}
+				]
+			});
+
+			expect(result).toEqual([{ name: 'asc' }, { user: { posts: 'desc' } }]);
+		});
+	});
+});

package/templates/nest-api/files/src/common/__tests__/mail.service.spec.ts

@@ -0,0 +1,75 @@
+import { TestBed } from '@suites/unit';
+import type { Mock } from 'vitest';
+import { getQueueToken } from '@nestjs/bullmq';
+import { Queue } from 'bullmq';
+import { MailService } from 'common/services';
+import {
+	MailJob,
+	ActivationData,
+	ActivationTwoFaData,
+	WelcomeData,
+	ForgotPasswordData,
+	SetPasswordData
+} from 'common/types';
+
+describe('MailService', () => {
+	let service: MailService;
+	// Only `add` is exercised; Mocked<Queue> is too deep a type for tsc.
+	let queue: { add: Mock<Queue['add']> };
+
+	beforeAll(async () => {
+		const { unit, unitRef } = await TestBed.solitary(MailService).compile();
+		service = unit;
+		queue = unitRef.get(getQueueToken('mail'));
+	});
+
+	beforeEach(() => {
+		queue.add.mockReset();
+	});
+
+	it('should be defined', () => {
+		expect(service).toBeDefined();
+	});
+
+	it('should enqueue activation email', async () => {
+		const data = {} as ActivationData;
+		await service.activation(data);
+		expect(queue.add).toHaveBeenCalledWith(MailJob.Activation, data);
+	});
+
+	it('should enqueue activation twofa email', async () => {
+		const data = {} as ActivationTwoFaData;
+		await service.activationTwofa(data);
+		expect(queue.add).toHaveBeenCalledWith(MailJob.ActivationTwofa, data);
+	});
+
+	it('should enqueue welcome email', async () => {
+		const data = {} as WelcomeData;
+		await service.welcome(data);
+		expect(queue.add).toHaveBeenCalledWith(MailJob.Welcome, data);
+	});
+
+	it('should enqueue forgot password email', async () => {
+		const data = {} as ForgotPasswordData;
+		await service.forgotPassword(data);
+		expect(queue.add).toHaveBeenCalledWith(MailJob.ForgotPassword, data);
+	});
+
+	it('should enqueue reset password email', async () => {
+		const data = 'reset-token';
+		await service.resetPassword(data);
+		expect(queue.add).toHaveBeenCalledWith(MailJob.ResetPassword, data);
+	});
+
+	it('should enqueue password changed email', async () => {
+		const data = 'user-id';
+		await service.passwordChanged(data);
+		expect(queue.add).toHaveBeenCalledWith(MailJob.PasswordChanged, data);
+	});
+
+	it('should enqueue set password email', async () => {
+		const data = {} as SetPasswordData;
+		await service.setPassword(data);
+		expect(queue.add).toHaveBeenCalledWith(MailJob.SetPassword, data);
+	});
+});

package/templates/nest-api/files/src/common/__tests__/prisma.indicator.spec.ts

@@ -0,0 +1,39 @@
+import { TestBed, type Mocked } from '@suites/unit';
+import { HealthIndicatorService } from '@nestjs/terminus';
+import { PrismaHealthIndicator } from 'common/misc/prisma.indicator';
+import { PrismaService } from 'common/services';
+
+describe('PrismaHealthIndicator', () => {
+	let indicator: PrismaHealthIndicator;
+	let db: Mocked<PrismaService>;
+
+	beforeAll(async () => {
+		const { unit, unitRef } = await TestBed.sociable(PrismaHealthIndicator)
+			.expose(HealthIndicatorService)
+			.compile();
+		indicator = unit;
+		db = unitRef.get(PrismaService);
+	});
+
+	it('should be defined', () => {
+		expect(indicator).toBeDefined();
+	});
+
+	it('should return healthy status when query succeeds', async () => {
+		db.$queryRawUnsafe.mockResolvedValue(1);
+
+		const result = await indicator.isHealthy('database');
+		expect(db.$queryRawUnsafe).toHaveBeenCalledWith('SELECT 1');
+		expect(result).toBeDefined();
+		expect(result).toEqual({ database: { status: 'up' } });
+	});
+
+	it('should return down status when query fails', async () => {
+		db.$queryRawUnsafe.mockRejectedValue(new Error('fail'));
+
+		const result = await indicator.isHealthy('database');
+		expect(result).toEqual({
+			database: { status: 'down', message: 'Database check failed' }
+		});
+	});
+});