@flusys/nestjs-shared 6.0.2 → 6.1.0

package/fesm/modules/cache/cache.module.spec.js

@@ -0,0 +1,44 @@
+const mockHybridCacheCtor = jest.fn();
+jest.mock('../../classes/hybrid-cache.class', ()=>({
+        HybridCache: class {
+            constructor(...args){
+                mockHybridCacheCtor(...args);
+            }
+        }
+    }));
+import { CacheModule } from './cache.module';
+import { CACHE_INSTANCE } from '../../constants';
+describe('CacheModule', ()=>{
+    beforeEach(()=>{
+        mockHybridCacheCtor.mockClear();
+    });
+    it('should default to a global module when isGlobal is not specified', ()=>{
+        const dynamicModule = CacheModule.forRoot();
+        expect(dynamicModule.module).toBe(CacheModule);
+        expect(dynamicModule.global).toBe(true);
+    });
+    it('should respect isGlobal=false', ()=>{
+        const dynamicModule = CacheModule.forRoot(false);
+        expect(dynamicModule.global).toBe(false);
+    });
+    it('should provide and export CACHE_INSTANCE', ()=>{
+        const dynamicModule = CacheModule.forRoot();
+        expect(dynamicModule.exports).toEqual([
+            CACHE_INSTANCE
+        ]);
+        expect(dynamicModule.providers).toHaveLength(1);
+        expect(dynamicModule.providers[0].provide).toBe(CACHE_INSTANCE);
+    });
+    it('should build the HybridCache with default ttl/size when the factory runs with no args', ()=>{
+        const dynamicModule = CacheModule.forRoot();
+        const factory = dynamicModule.providers[0].useFactory;
+        factory();
+        expect(mockHybridCacheCtor).toHaveBeenCalledWith(60_000, 5000);
+    });
+    it('should forward custom memoryTtl and memorySize to the HybridCache factory', ()=>{
+        const dynamicModule = CacheModule.forRoot(true, 30_000, 1000);
+        const factory = dynamicModule.providers[0].useFactory;
+        factory();
+        expect(mockHybridCacheCtor).toHaveBeenCalledWith(30_000, 1000);
+    });
+});

package/fesm/modules/datasource/multi-tenant-datasource.service.spec.js

@@ -0,0 +1,377 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+const mockInitialize = jest.fn();
+const mockDestroy = jest.fn();
+const mockGetRepository = jest.fn();
+let FakeDataSource = class FakeDataSource {
+    constructor(options){
+        _define_property(this, "isInitialized", false);
+        _define_property(this, "options", void 0);
+        _define_property(this, "initialize", jest.fn(async ()=>{
+            this.isInitialized = true;
+            await mockInitialize(this.options);
+            return this;
+        }));
+        _define_property(this, "destroy", jest.fn(async ()=>{
+            this.isInitialized = false;
+            await mockDestroy();
+        }));
+        _define_property(this, "getRepository", (entity)=>mockGetRepository(entity));
+        this.options = options;
+    }
+};
+jest.mock('typeorm', ()=>({
+        ...jest.requireActual('typeorm'),
+        DataSource: FakeDataSource
+    }));
+import { BadRequestException, InternalServerErrorException } from '@nestjs/common';
+import { MultiTenantDataSourceService } from './multi-tenant-datasource.service';
+import { SYSTEM_MESSAGES } from '../../constants';
+function resetStatics() {
+    const cls = MultiTenantDataSourceService;
+    cls.tenantConnections = new Map();
+    cls.singleDataSource = null;
+    cls.tenantsRegistry = new Map();
+    cls.initialized = false;
+    cls.connectionLocks = new Map();
+    cls.singleConnectionLock = null;
+}
+describe('MultiTenantDataSourceService', ()=>{
+    const defaultDatabaseConfig = {
+        type: 'postgres',
+        host: 'localhost',
+        port: 5432,
+        username: 'root',
+        password: 'pw',
+        database: 'flusys_default'
+    };
+    beforeEach(()=>{
+        jest.clearAllMocks();
+        resetStatics();
+    });
+    function makeOptions(overrides = {}) {
+        return {
+            defaultDatabaseConfig,
+            bootstrapAppConfig: {
+                databaseMode: 'single'
+            },
+            ...overrides
+        };
+    }
+    function makeRequest(headers = {}) {
+        return {
+            headers
+        };
+    }
+    describe('database mode', ()=>{
+        it('should default to single mode when no options are provided', ()=>{
+            const service = new MultiTenantDataSourceService();
+            expect(service.getDatabaseMode()).toBe('single');
+            expect(service.isMultiTenant()).toBe(false);
+        });
+        it('should report multi-tenant mode from bootstrap config', ()=>{
+            const service = new MultiTenantDataSourceService(makeOptions({
+                bootstrapAppConfig: {
+                    databaseMode: 'multi-tenant'
+                }
+            }));
+            expect(service.isMultiTenant()).toBe(true);
+        });
+    });
+    describe('tenant registration', ()=>{
+        it('should register tenants from options exactly once across instances', ()=>{
+            const tenants = [
+                {
+                    id: 'tenant-a',
+                    database: 'db_a'
+                },
+                {
+                    id: 'tenant-b',
+                    database: 'db_b'
+                }
+            ];
+            const options = makeOptions({
+                tenants
+            });
+            const service1 = new MultiTenantDataSourceService(options);
+            const service2 = new MultiTenantDataSourceService(options);
+            expect(service1.getTenant('tenant-a')?.database).toBe('db_a');
+            expect(service2.getTenant('tenant-b')?.database).toBe('db_b');
+        });
+        it('should return null for an unregistered tenant', ()=>{
+            const service = new MultiTenantDataSourceService(makeOptions());
+            expect(service.getTenant('unknown')).toBeNull();
+        });
+        it('should be a no-op when constructed without options', ()=>{
+            expect(()=>new MultiTenantDataSourceService()).not.toThrow();
+        });
+    });
+    describe('getCurrentTenantId', ()=>{
+        it('should return null when there is no request (e.g. background job)', ()=>{
+            const service = new MultiTenantDataSourceService(makeOptions());
+            expect(service.getCurrentTenantId()).toBeNull();
+        });
+        it('should return null when the tenant header is missing', ()=>{
+            const service = new MultiTenantDataSourceService(makeOptions(), makeRequest());
+            expect(service.getCurrentTenantId()).toBeNull();
+        });
+        it('should return the tenant id from the header when valid', ()=>{
+            const service = new MultiTenantDataSourceService(makeOptions(), makeRequest({
+                'x-tenant-id': 'tenant-a'
+            }));
+            expect(service.getCurrentTenantId()).toBe('tenant-a');
+        });
+        it('should reject tenant ids with invalid characters', ()=>{
+            const service = new MultiTenantDataSourceService(makeOptions(), makeRequest({
+                'x-tenant-id': 'tenant a; DROP TABLE users;'
+            }));
+            expect(()=>service.getCurrentTenantId()).toThrow(BadRequestException);
+            try {
+                service.getCurrentTenantId();
+            } catch (e) {
+                expect(e.getResponse().messageKey).toBe(SYSTEM_MESSAGES.INVALID_TENANT_ID);
+            }
+        });
+        it('should accept tenant ids with letters, numbers, underscores and dashes', ()=>{
+            const service = new MultiTenantDataSourceService(makeOptions(), makeRequest({
+                'x-tenant-id': 'Tenant_123-ABC'
+            }));
+            expect(service.getCurrentTenantId()).toBe('Tenant_123-ABC');
+        });
+    });
+    describe('getCurrentTenant', ()=>{
+        it('should resolve the registered tenant config for the current request', ()=>{
+            const tenants = [
+                {
+                    id: 'tenant-a',
+                    database: 'db_a'
+                }
+            ];
+            const service = new MultiTenantDataSourceService(makeOptions({
+                tenants
+            }), makeRequest({
+                'x-tenant-id': 'tenant-a'
+            }));
+            expect(service.getCurrentTenant()?.database).toBe('db_a');
+        });
+        it('should return null when there is no current tenant id', ()=>{
+            const service = new MultiTenantDataSourceService(makeOptions(), makeRequest());
+            expect(service.getCurrentTenant()).toBeNull();
+        });
+    });
+    describe('getSingleDataSource / getDataSource (single mode)', ()=>{
+        it('should create and initialize a datasource from the default config', async ()=>{
+            const service = new MultiTenantDataSourceService(makeOptions());
+            const ds = await service.getDataSource();
+            expect(ds.isInitialized).toBe(true);
+            expect(mockInitialize).toHaveBeenCalledWith(expect.objectContaining({
+                database: 'flusys_default'
+            }));
+        });
+        it('should reuse the cached datasource on subsequent calls', async ()=>{
+            const service = new MultiTenantDataSourceService(makeOptions());
+            const ds1 = await service.getDataSource();
+            const ds2 = await service.getDataSource();
+            expect(ds1).toBe(ds2);
+            expect(mockInitialize).toHaveBeenCalledTimes(1);
+        });
+        it('should dedupe concurrent creation attempts into a single connection', async ()=>{
+            const service = new MultiTenantDataSourceService(makeOptions());
+            const [ds1, ds2] = await Promise.all([
+                service.getDataSource(),
+                service.getDataSource()
+            ]);
+            expect(ds1).toBe(ds2);
+            expect(mockInitialize).toHaveBeenCalledTimes(1);
+        });
+        it('should throw InternalServerErrorException when no database config is available', async ()=>{
+            const service = new MultiTenantDataSourceService(makeOptions({
+                defaultDatabaseConfig: undefined
+            }));
+            await expect(service.getDataSource()).rejects.toThrow(InternalServerErrorException);
+        });
+        it('should fall back to tenantDefaultDatabaseConfig when defaultDatabaseConfig is absent', async ()=>{
+            const service = new MultiTenantDataSourceService(makeOptions({
+                defaultDatabaseConfig: undefined,
+                tenantDefaultDatabaseConfig: defaultDatabaseConfig
+            }));
+            const ds = await service.getDataSource();
+            expect(ds.isInitialized).toBe(true);
+        });
+        it('getRepository should resolve the datasource then delegate to it', async ()=>{
+            const service = new MultiTenantDataSourceService(makeOptions());
+            let Product = class Product {
+            };
+            mockGetRepository.mockReturnValue('the-repo');
+            const repo = await service.getRepository(Product);
+            expect(mockGetRepository).toHaveBeenCalledWith(Product);
+            expect(repo).toBe('the-repo');
+        });
+    });
+    describe('getTenantDataSource / getDataSource (multi-tenant mode)', ()=>{
+        function multiTenantOptions(tenants) {
+            return makeOptions({
+                bootstrapAppConfig: {
+                    databaseMode: 'multi-tenant'
+                },
+                tenants
+            });
+        }
+        it('should throw BadRequestException when no tenant header is present', async ()=>{
+            const service = new MultiTenantDataSourceService(multiTenantOptions([
+                {
+                    id: 'tenant-a',
+                    database: 'db_a'
+                }
+            ]), makeRequest());
+            await expect(service.getDataSource()).rejects.toThrow(BadRequestException);
+        });
+        it('should throw BadRequestException when the tenant is not registered', async ()=>{
+            const service = new MultiTenantDataSourceService(multiTenantOptions([]), makeRequest({
+                'x-tenant-id': 'ghost-tenant'
+            }));
+            await expect(service.getDataSource()).rejects.toThrow(BadRequestException);
+        });
+        it('should create a tenant-specific connection merging tenant overrides onto the default config', async ()=>{
+            const service = new MultiTenantDataSourceService(multiTenantOptions([
+                {
+                    id: 'tenant-a',
+                    database: 'db_a',
+                    host: 'tenant-a-host'
+                }
+            ]), makeRequest({
+                'x-tenant-id': 'tenant-a'
+            }));
+            const ds = await service.getDataSource();
+            expect(ds.isInitialized).toBe(true);
+            expect(mockInitialize).toHaveBeenCalledWith(expect.objectContaining({
+                database: 'db_a',
+                host: 'tenant-a-host',
+                username: defaultDatabaseConfig.username
+            }));
+        });
+        it('should cache the tenant connection and reuse it for subsequent requests to the same tenant', async ()=>{
+            const tenants = [
+                {
+                    id: 'tenant-a',
+                    database: 'db_a'
+                }
+            ];
+            const service1 = new MultiTenantDataSourceService(multiTenantOptions(tenants), makeRequest({
+                'x-tenant-id': 'tenant-a'
+            }));
+            const service2 = new MultiTenantDataSourceService(multiTenantOptions(tenants), makeRequest({
+                'x-tenant-id': 'tenant-a'
+            }));
+            const ds1 = await service1.getDataSource();
+            const ds2 = await service2.getDataSource();
+            expect(ds1).toBe(ds2);
+            expect(mockInitialize).toHaveBeenCalledTimes(1);
+        });
+        it('should maintain separate connections per tenant', async ()=>{
+            const tenants = [
+                {
+                    id: 'tenant-a',
+                    database: 'db_a'
+                },
+                {
+                    id: 'tenant-b',
+                    database: 'db_b'
+                }
+            ];
+            const serviceA = new MultiTenantDataSourceService(multiTenantOptions(tenants), makeRequest({
+                'x-tenant-id': 'tenant-a'
+            }));
+            const serviceB = new MultiTenantDataSourceService(multiTenantOptions(tenants), makeRequest({
+                'x-tenant-id': 'tenant-b'
+            }));
+            const dsA = await serviceA.getDataSource();
+            const dsB = await serviceB.getDataSource();
+            expect(dsA).not.toBe(dsB);
+            expect(mockInitialize).toHaveBeenCalledTimes(2);
+        });
+        it('should throw InternalServerErrorException when no default config exists to base tenant configs on', async ()=>{
+            const service = new MultiTenantDataSourceService({
+                ...multiTenantOptions([
+                    {
+                        id: 'tenant-a',
+                        database: 'db_a'
+                    }
+                ]),
+                defaultDatabaseConfig: undefined,
+                tenantDefaultDatabaseConfig: undefined
+            }, makeRequest({
+                'x-tenant-id': 'tenant-a'
+            }));
+            await expect(service.getDataSource()).rejects.toThrow(InternalServerErrorException);
+        });
+    });
+    describe('closeTenantConnection', ()=>{
+        it('should destroy and remove an initialized tenant connection', async ()=>{
+            const tenants = [
+                {
+                    id: 'tenant-a',
+                    database: 'db_a'
+                }
+            ];
+            const service = new MultiTenantDataSourceService(makeOptions({
+                bootstrapAppConfig: {
+                    databaseMode: 'multi-tenant'
+                },
+                tenants
+            }), makeRequest({
+                'x-tenant-id': 'tenant-a'
+            }));
+            await service.getDataSource();
+            await service.closeTenantConnection('tenant-a');
+            expect(mockDestroy).toHaveBeenCalledTimes(1);
+            expect(MultiTenantDataSourceService.tenantConnections.has('tenant-a')).toBe(false);
+        });
+        it('should be a no-op for a tenant with no active connection', async ()=>{
+            const service = new MultiTenantDataSourceService(makeOptions());
+            await expect(service.closeTenantConnection('never-connected')).resolves.toBeUndefined();
+            expect(mockDestroy).not.toHaveBeenCalled();
+        });
+    });
+    describe('onModuleDestroy', ()=>{
+        it('should close every tracked tenant connection', async ()=>{
+            const tenants = [
+                {
+                    id: 'tenant-a',
+                    database: 'db_a'
+                },
+                {
+                    id: 'tenant-b',
+                    database: 'db_b'
+                }
+            ];
+            const options = makeOptions({
+                bootstrapAppConfig: {
+                    databaseMode: 'multi-tenant'
+                },
+                tenants
+            });
+            const serviceA = new MultiTenantDataSourceService(options, makeRequest({
+                'x-tenant-id': 'tenant-a'
+            }));
+            const serviceB = new MultiTenantDataSourceService(options, makeRequest({
+                'x-tenant-id': 'tenant-b'
+            }));
+            await serviceA.getDataSource();
+            await serviceB.getDataSource();
+            await serviceA.onModuleDestroy();
+            expect(mockDestroy).toHaveBeenCalledTimes(2);
+        });
+    });
+});

package/fesm/modules/utils/utils.service.spec.js

@@ -0,0 +1,165 @@
+import { UtilsService } from './utils.service';
+describe('UtilsService', ()=>{
+    let service;
+    let mockCache;
+    beforeEach(()=>{
+        service = new UtilsService();
+        mockCache = {
+            get: jest.fn(),
+            set: jest.fn(),
+            del: jest.fn()
+        };
+    });
+    describe('getCacheKey', ()=>{
+        it('should build an "all" key from the entity name and params when no id is given', ()=>{
+            const key = service.getCacheKey('product', {
+                page: 1
+            });
+            expect(key).toBe('entity_product_all_{"page":1}');
+        });
+        it('should build a per-id key with a select suffix when params are given', ()=>{
+            const key = service.getCacheKey('product', {
+                fields: [
+                    'name'
+                ]
+            }, 'prod-1');
+            expect(key).toBe('entity_product_id_prod-1_select_{"fields":["name"]}');
+        });
+        it('should build a per-id key without a select suffix when params are falsy', ()=>{
+            const key = service.getCacheKey('product', null, 'prod-1');
+            expect(key).toBe('entity_product_id_prod-1');
+        });
+        it('should prefix the key with the tenant id when provided', ()=>{
+            const key = service.getCacheKey('product', {
+                page: 1
+            }, undefined, 'tenant-a');
+            expect(key).toBe('tenant_tenant-a_entity_product_all_{"page":1}');
+        });
+        it('should prefix a per-id key with the tenant id too', ()=>{
+            const key = service.getCacheKey('product', undefined, 'prod-1', 'tenant-a');
+            expect(key).toBe('tenant_tenant-a_entity_product_id_prod-1');
+        });
+    });
+    describe('trackCacheKey', ()=>{
+        it('should create a new tracking list when none exists yet', async ()=>{
+            mockCache.get.mockResolvedValue(undefined);
+            await service.trackCacheKey('cache-key-1', 'product', mockCache);
+            expect(mockCache.set).toHaveBeenCalledWith('entity_product_keys', [
+                'cache-key-1'
+            ]);
+        });
+        it('should append to an existing tracking list without duplicating entries', async ()=>{
+            mockCache.get.mockResolvedValue([
+                'cache-key-1'
+            ]);
+            await service.trackCacheKey('cache-key-1', 'product', mockCache);
+            expect(mockCache.set).toHaveBeenCalledWith('entity_product_keys', [
+                'cache-key-1'
+            ]);
+        });
+        it('should append a new key alongside existing ones', async ()=>{
+            mockCache.get.mockResolvedValue([
+                'cache-key-1'
+            ]);
+            await service.trackCacheKey('cache-key-2', 'product', mockCache);
+            expect(mockCache.set).toHaveBeenCalledWith('entity_product_keys', [
+                'cache-key-1',
+                'cache-key-2'
+            ]);
+        });
+        it('should scope the tracking key by entity id and tenant', async ()=>{
+            mockCache.get.mockResolvedValue(undefined);
+            await service.trackCacheKey('cache-key-1', 'product', mockCache, 'prod-1', 'tenant-a');
+            expect(mockCache.get).toHaveBeenCalledWith('tenant_tenant-a_entity_product_id_prod-1_keys');
+            expect(mockCache.set).toHaveBeenCalledWith('tenant_tenant-a_entity_product_id_prod-1_keys', [
+                'cache-key-1'
+            ]);
+        });
+        it('should swallow cache read errors without throwing', async ()=>{
+            mockCache.get.mockRejectedValue(new Error('cache down'));
+            await expect(service.trackCacheKey('k', 'product', mockCache)).resolves.toBeUndefined();
+            expect(mockCache.set).not.toHaveBeenCalled();
+        });
+        it('should swallow cache write errors without throwing', async ()=>{
+            mockCache.get.mockResolvedValue([]);
+            mockCache.set.mockRejectedValue(new Error('cache down'));
+            await expect(service.trackCacheKey('k', 'product', mockCache)).resolves.toBeUndefined();
+        });
+    });
+    describe('clearCache', ()=>{
+        it('should delete every tracked key plus the tracking key itself', async ()=>{
+            mockCache.get.mockResolvedValue([
+                'k1',
+                'k2'
+            ]);
+            await service.clearCache('product', mockCache);
+            expect(mockCache.del).toHaveBeenCalledWith('k1');
+            expect(mockCache.del).toHaveBeenCalledWith('k2');
+            expect(mockCache.del).toHaveBeenCalledWith('entity_product_keys');
+            expect(mockCache.del).toHaveBeenCalledTimes(3);
+        });
+        it('should only delete the tracking key when no keys were tracked', async ()=>{
+            mockCache.get.mockResolvedValue(undefined);
+            await service.clearCache('product', mockCache);
+            expect(mockCache.del).toHaveBeenCalledTimes(1);
+            expect(mockCache.del).toHaveBeenCalledWith('entity_product_keys');
+        });
+        it('should continue deleting remaining keys even if one deletion rejects', async ()=>{
+            mockCache.get.mockResolvedValue([
+                'k1',
+                'k2'
+            ]);
+            mockCache.del.mockImplementation((key)=>key === 'k1' ? Promise.reject(new Error('fail')) : Promise.resolve());
+            await service.clearCache('product', mockCache);
+            expect(mockCache.del).toHaveBeenCalledWith('k2');
+            expect(mockCache.del).toHaveBeenCalledWith('entity_product_keys');
+        });
+        it('should scope deletion by entity id and tenant', async ()=>{
+            mockCache.get.mockResolvedValue([
+                'k1'
+            ]);
+            await service.clearCache('product', mockCache, 'prod-1', 'tenant-a');
+            expect(mockCache.get).toHaveBeenCalledWith('tenant_tenant-a_entity_product_id_prod-1_keys');
+        });
+        it('should swallow errors from the initial cache read', async ()=>{
+            mockCache.get.mockRejectedValue(new Error('cache down'));
+            await expect(service.clearCache('product', mockCache)).resolves.toBeUndefined();
+            expect(mockCache.del).not.toHaveBeenCalled();
+        });
+    });
+    describe('transformToSlug', ()=>{
+        it('should lowercase and dash-separate a normal string', ()=>{
+            expect(service.transformToSlug('Hello World')).toBe('hello-world');
+        });
+        it('should collapse runs of non-alphanumeric characters into a single dash', ()=>{
+            expect(service.transformToSlug('Hello   World!!!')).toBe('hello-world-');
+        });
+        it('should trim leading/trailing whitespace before slugging', ()=>{
+            expect(service.transformToSlug('  Hello World  ')).toBe('hello-world');
+        });
+        it('should append a random numeric salt when requested', ()=>{
+            const randomSpy = jest.spyOn(service, 'getRandomInt').mockReturnValue(42);
+            expect(service.transformToSlug('Hello World', true)).toBe('hello-world-42');
+            randomSpy.mockRestore();
+        });
+        it('should handle an empty string', ()=>{
+            expect(service.transformToSlug('')).toBe('');
+        });
+        it('should handle strings that are entirely non-alphanumeric', ()=>{
+            expect(service.transformToSlug('!!!')).toBe('-');
+        });
+    });
+    describe('getRandomInt', ()=>{
+        it('should return the exact bound when min equals max', ()=>{
+            expect(service.getRandomInt(5, 5)).toBe(5);
+        });
+        it('should stay within an inclusive [min, max] range across many samples', ()=>{
+            for(let i = 0; i < 200; i++){
+                const value = service.getRandomInt(1, 10);
+                expect(value).toBeGreaterThanOrEqual(1);
+                expect(value).toBeLessThanOrEqual(10);
+                expect(Number.isInteger(value)).toBe(true);
+            }
+        });
+    });
+});

package/fesm/utils/date-time.util.spec.js

@@ -0,0 +1,80 @@
+import { formatInTimezone, getTodayInTimezone, localToUtc, utcToLocal } from './date-time.util';
+describe('date-time.util', ()=>{
+    describe('localToUtc', ()=>{
+        it('should convert a local date/time in a fixed-offset timezone to UTC', ()=>{
+            // Asia/Dhaka is UTC+6, no DST
+            const result = localToUtc('2026-01-15', '10:00', 'Asia/Dhaka');
+            expect(result.toISOString()).toBe('2026-01-15T04:00:00.000Z');
+        });
+        it('should convert local time in UTC timezone unchanged', ()=>{
+            const result = localToUtc('2026-06-01', '12:30', 'UTC');
+            expect(result.toISOString()).toBe('2026-06-01T12:30:00.000Z');
+        });
+        it('should handle a negative UTC offset timezone (America/New_York in winter, no DST)', ()=>{
+            // America/New_York is UTC-5 in January (standard time, no DST)
+            const result = localToUtc('2026-01-15', '09:00', 'America/New_York');
+            expect(result.toISOString()).toBe('2026-01-15T14:00:00.000Z');
+        });
+        it('should account for DST when converting a summer date in America/New_York (UTC-4)', ()=>{
+            const result = localToUtc('2026-07-15', '09:00', 'America/New_York');
+            expect(result.toISOString()).toBe('2026-07-15T13:00:00.000Z');
+        });
+    });
+    describe('utcToLocal', ()=>{
+        it('should convert a UTC Date to local date/time/display parts', ()=>{
+            const result = utcToLocal(new Date('2026-01-15T04:00:00.000Z'), 'Asia/Dhaka');
+            expect(result.date).toBe('2026-01-15');
+            expect(result.time).toBe('10:00');
+            expect(result.display).toEqual(expect.any(String));
+        });
+        it('should accept a UTC date string as input', ()=>{
+            const result = utcToLocal('2026-01-15T04:00:00.000Z', 'Asia/Dhaka');
+            expect(result.date).toBe('2026-01-15');
+            expect(result.time).toBe('10:00');
+        });
+        it('should normalize midnight (en-CA "24") to "00"', ()=>{
+            // 00:00 Dhaka time == 18:00 UTC the previous day
+            const result = utcToLocal('2026-01-14T18:00:00.000Z', 'Asia/Dhaka');
+            expect(result.date).toBe('2026-01-15');
+            expect(result.time).toBe('00:00');
+        });
+    });
+    describe('formatInTimezone', ()=>{
+        it('should format a date in the given timezone with default options', ()=>{
+            const result = formatInTimezone('2026-01-15T04:00:00.000Z', 'Asia/Dhaka');
+            expect(typeof result).toBe('string');
+            expect(result.length).toBeGreaterThan(0);
+        });
+        it('should respect custom Intl.DateTimeFormatOptions', ()=>{
+            const result = formatInTimezone('2026-01-15T04:00:00.000Z', 'UTC', {
+                year: 'numeric'
+            });
+            expect(result).toBe('2026');
+        });
+        it('should accept a Date object as input', ()=>{
+            const result = formatInTimezone(new Date('2026-01-15T04:00:00.000Z'), 'UTC', {
+                year: 'numeric'
+            });
+            expect(result).toBe('2026');
+        });
+    });
+    describe('getTodayInTimezone', ()=>{
+        it('should return a date string in YYYY-MM-DD format', ()=>{
+            const result = getTodayInTimezone('UTC');
+            expect(result).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+        });
+        it('should match utcToLocal(now, timezone).date', ()=>{
+            const now = new Date();
+            const expected = utcToLocal(now, 'Asia/Dhaka').date;
+            expect(getTodayInTimezone('Asia/Dhaka')).toBe(expected);
+        });
+    });
+    describe('round-trip', ()=>{
+        it('should round-trip localToUtc -> utcToLocal for a fixed-offset zone', ()=>{
+            const utc = localToUtc('2026-03-10', '08:15', 'Asia/Dhaka');
+            const back = utcToLocal(utc, 'Asia/Dhaka');
+            expect(back.date).toBe('2026-03-10');
+            expect(back.time).toBe('08:15');
+        });
+    });
+});