@govish/shared-services 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Version 1.6.0
+
+### Added
+- **Rolling cache utilities** (`createRollingCache`): list/item pattern with `buildKey`, `get`, `set`, `getOrSet`, `invalidate`, `invalidateByPrefix`, `recordAccess` (Redis `ZINCRBY` for hot-key telemetry), and default TTL helpers from `CACHE_DAYS_LIST` / `CACHE_DAYS_ITEM`. Opt-in via `ROLLING_CACHE_ENABLED` / `CACHE_ENABLED`. Uses the host `redisClient` for `setEx`, `del`, `scan`, and sorted sets.
+
+---
+
 ## Version 1.5.1
 
 ### Fixed

package/README.md

@@ -37,6 +37,7 @@ const authenticateDeviceOrOfficer = createAuthenticateDeviceOrOfficer(dependenci
 
 ## Utilities Included
 
+- **createRollingCache**: List/item rolling cache (`buildKey`, `get`, `set`, `getOrSet`, `invalidate`, `invalidateByPrefix`, `recordAccess`) with day-based TTL from `CACHE_DAYS_LIST` / `CACHE_DAYS_ITEM`; enable with `ROLLING_CACHE_ENABLED=true`
 - **createSafeRedisGet**: Factory function to create a safe Redis GET operation with automatic reconnection
 - **createSafeRedisSet**: Factory function to create a safe Redis SET operation with automatic reconnection
 - **createSafeRedisUtils**: Factory function that creates both safeRedisGet and safeRedisSet functions
@@ -65,7 +66,7 @@ import {
   ApiKeyService,
   createAuthenticateDeviceOrOfficer,
   SharedServicesDependencies 
-} from '@ob-main/shared-services';
+} from '@govish/shared-services';
 import { redisClient } from './app';
 import { logger } from './utils/logger';
 // ... other dependencies

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export { AuditEventType } from './services/auditService';
 export type { AuditEventPayload } from './services/auditService';
 export { createAuthenticateDeviceOrOfficer } from './middleware/authenticateDevice';
 export { createSafeRedisGet, createSafeRedisSet, createSafeRedisUtils } from './utils/redis';
+export { createRollingCache, ROLLING_CACHE_SEP, } from './utils/rollingCache';
+export type { RollingCacheInstance, RollingCacheOptions, RollingCacheTtl, } from './utils/rollingCache';
 export { getEnvironmentMode, isDevelopmentMode, isProductionMode, devLog, devError, devWarn, devDebug } from './utils/logMode';
 export type { EnvironmentMode } from './utils/logMode';
 export type { SharedServicesDependencies } from './types/dependencies';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.devDebug = exports.devWarn = exports.devError = exports.devLog = exports.isProductionMode = exports.isDevelopmentMode = exports.getEnvironmentMode = exports.createSafeRedisUtils = exports.createSafeRedisSet = exports.createSafeRedisGet = exports.createAuthenticateDeviceOrOfficer = exports.AuditEventType = exports.AuditService = exports.ApiKeyService = exports.RankLeaveDaysCacheService = exports.StationDutyBlockCacheService = exports.StationCacheService = exports.DeviceService = exports.DeviceCacheService = exports.PenalCodeCacheService = exports.OfficerService = exports.OfficerCacheService = void 0;
+exports.devDebug = exports.devWarn = exports.devError = exports.devLog = exports.isProductionMode = exports.isDevelopmentMode = exports.getEnvironmentMode = exports.ROLLING_CACHE_SEP = exports.createRollingCache = exports.createSafeRedisUtils = exports.createSafeRedisSet = exports.createSafeRedisGet = exports.createAuthenticateDeviceOrOfficer = exports.AuditEventType = exports.AuditService = exports.ApiKeyService = exports.RankLeaveDaysCacheService = exports.StationDutyBlockCacheService = exports.StationCacheService = exports.DeviceService = exports.DeviceCacheService = exports.PenalCodeCacheService = exports.OfficerService = exports.OfficerCacheService = void 0;
 // Export services
 var officerCacheService_1 = require("./services/officerCacheService");
 Object.defineProperty(exports, "OfficerCacheService", { enumerable: true, get: function () { return officerCacheService_1.OfficerCacheService; } });
@@ -32,6 +32,9 @@ var redis_1 = require("./utils/redis");
 Object.defineProperty(exports, "createSafeRedisGet", { enumerable: true, get: function () { return redis_1.createSafeRedisGet; } });
 Object.defineProperty(exports, "createSafeRedisSet", { enumerable: true, get: function () { return redis_1.createSafeRedisSet; } });
 Object.defineProperty(exports, "createSafeRedisUtils", { enumerable: true, get: function () { return redis_1.createSafeRedisUtils; } });
+var rollingCache_1 = require("./utils/rollingCache");
+Object.defineProperty(exports, "createRollingCache", { enumerable: true, get: function () { return rollingCache_1.createRollingCache; } });
+Object.defineProperty(exports, "ROLLING_CACHE_SEP", { enumerable: true, get: function () { return rollingCache_1.ROLLING_CACHE_SEP; } });
 var logMode_1 = require("./utils/logMode");
 Object.defineProperty(exports, "getEnvironmentMode", { enumerable: true, get: function () { return logMode_1.getEnvironmentMode; } });
 Object.defineProperty(exports, "isDevelopmentMode", { enumerable: true, get: function () { return logMode_1.isDevelopmentMode; } });

package/dist/utils/rollingCache.d.ts

@@ -0,0 +1,34 @@
+export type RollingCacheTtl = number | {
+    days: number;
+};
+export type RollingCacheOptions = {
+    redisClient: any;
+    /** If omitted, uses createSafeRedisGet(redisClient). */
+    safeRedisGet?: (key: string) => Promise<string | null>;
+    /** Env var name for enable flag; default ROLLING_CACHE_ENABLED. Also reads CACHE_ENABLED if unset. */
+    enableEnvKey?: string;
+    logWarn?: (message: string, meta?: Record<string, unknown>) => void;
+};
+export type RollingCacheInstance = {
+    buildKey: (entity: string, ...parts: (string | number)[]) => string;
+    isCacheEnabled: () => boolean;
+    get: <T = unknown>(key: string) => Promise<T | null>;
+    set: (key: string, value: unknown, ttl?: RollingCacheTtl) => Promise<boolean>;
+    getOrSet: <T>(key: string, ttl: RollingCacheTtl | undefined, loader: () => Promise<T>) => Promise<T>;
+    invalidate: (key: string) => Promise<void>;
+    invalidateByPrefix: (prefix: string) => Promise<number>;
+    recordAccess: (zsetKey: string, member: string, incrementBy?: number) => Promise<void>;
+    getDefaultListTtl: () => {
+        days: number;
+    };
+    getDefaultItemTtl: () => {
+        days: number;
+    };
+};
+/**
+ * Factory for list/item rolling cache (Redis string keys + JSON values).
+ * Pass the same redis client used by the host app. Optional safeRedisGet for custom wiring.
+ */
+export declare function createRollingCache(options: RollingCacheOptions): RollingCacheInstance;
+/** Key segment separator used by buildKey (exported for invalidation helpers). */
+export declare const ROLLING_CACHE_SEP = "|";

package/dist/utils/rollingCache.js

@@ -0,0 +1,203 @@
+"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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLLING_CACHE_SEP = void 0;
+exports.createRollingCache = createRollingCache;
+const redis_1 = require("./redis");
+const SEP = '|';
+const DEFAULT_LIST_DAYS = 7;
+const DEFAULT_ITEM_DAYS = 30;
+const DEFAULT_ENABLE_ENV = 'ROLLING_CACHE_ENABLED';
+function ensureConnected(redisClient) {
+    return new Promise((resolve) => {
+        var _a;
+        if (redisClient === null || redisClient === void 0 ? void 0 : redisClient.isOpen) {
+            resolve(true);
+            return;
+        }
+        (_a = redisClient === null || redisClient === void 0 ? void 0 : redisClient.connect) === null || _a === void 0 ? void 0 : _a.call(redisClient).then(() => resolve(true)).catch(() => resolve(false));
+    });
+}
+function normalizePart(part) {
+    if (part === null || part === undefined)
+        return '';
+    const s = String(part).trim();
+    return s.replace(/\|/g, '_').replace(/:/g, '_');
+}
+function ttlSeconds(ttl) {
+    if (ttl == null)
+        return undefined;
+    if (typeof ttl === 'number')
+        return ttl > 0 ? ttl : undefined;
+    if (ttl.days > 0)
+        return ttl.days * 86400;
+    return undefined;
+}
+function getCacheDaysList() {
+    const v = process.env.CACHE_DAYS_LIST;
+    if (v != null && v !== '') {
+        const n = parseInt(v, 10);
+        if (!Number.isNaN(n) && n > 0)
+            return n;
+    }
+    return DEFAULT_LIST_DAYS;
+}
+function getCacheDaysItem() {
+    const v = process.env.CACHE_DAYS_ITEM;
+    if (v != null && v !== '') {
+        const n = parseInt(v, 10);
+        if (!Number.isNaN(n) && n > 0)
+            return n;
+    }
+    return DEFAULT_ITEM_DAYS;
+}
+const SCAN_COUNT = 100;
+/**
+ * Factory for list/item rolling cache (Redis string keys + JSON values).
+ * Pass the same redis client used by the host app. Optional safeRedisGet for custom wiring.
+ */
+function createRollingCache(options) {
+    var _a;
+    const { redisClient, enableEnvKey = DEFAULT_ENABLE_ENV, logWarn } = options;
+    const safeRedisGet = (_a = options.safeRedisGet) !== null && _a !== void 0 ? _a : (0, redis_1.createSafeRedisGet)(redisClient);
+    const warn = (message, meta) => {
+        if (logWarn)
+            logWarn(message, meta);
+        else
+            console.warn(`[RollingCache] ${message}`, meta !== null && meta !== void 0 ? meta : '');
+    };
+    const isCacheEnabled = () => {
+        var _a, _b;
+        const v = (_b = (_a = process.env[enableEnvKey]) !== null && _a !== void 0 ? _a : process.env.CACHE_ENABLED) !== null && _b !== void 0 ? _b : '';
+        const s = String(v).trim().toLowerCase();
+        return s === '1' || s === 'true' || s === 'yes';
+    };
+    const buildKey = (entity, ...parts) => {
+        const normalized = parts.map(normalizePart);
+        return [entity, ...normalized].join(SEP);
+    };
+    const get = (key) => __awaiter(this, void 0, void 0, function* () {
+        if (!isCacheEnabled())
+            return null;
+        try {
+            const raw = yield safeRedisGet(key);
+            if (raw == null)
+                return null;
+            return JSON.parse(raw);
+        }
+        catch (e) {
+            warn('get parse error', { key, error: e instanceof Error ? e.message : String(e) });
+            return null;
+        }
+    });
+    const set = (key, value, ttl) => __awaiter(this, void 0, void 0, function* () {
+        if (!isCacheEnabled())
+            return true;
+        try {
+            const str = JSON.stringify(value);
+            const sec = ttlSeconds(ttl);
+            const ok = yield ensureConnected(redisClient);
+            if (!ok)
+                return false;
+            if (sec != null) {
+                yield redisClient.setEx(key, sec, str);
+            }
+            else {
+                yield redisClient.set(key, str);
+            }
+            return true;
+        }
+        catch (e) {
+            warn('set error', { key, error: e instanceof Error ? e.message : String(e) });
+            return false;
+        }
+    });
+    const getOrSet = (key, ttl, loader) => __awaiter(this, void 0, void 0, function* () {
+        const hit = yield get(key);
+        if (hit !== null && hit !== undefined) {
+            return hit;
+        }
+        const v = yield loader();
+        yield set(key, v, ttl);
+        return v;
+    });
+    const invalidate = (key) => __awaiter(this, void 0, void 0, function* () {
+        if (!isCacheEnabled())
+            return;
+        try {
+            const ok = yield ensureConnected(redisClient);
+            if (!ok)
+                return;
+            yield redisClient.del(key);
+        }
+        catch (e) {
+            warn('invalidate error', { key, error: e instanceof Error ? e.message : String(e) });
+        }
+    });
+    const invalidateByPrefix = (prefix) => __awaiter(this, void 0, void 0, function* () {
+        if (!isCacheEnabled())
+            return 0;
+        let deleted = 0;
+        try {
+            const ok = yield ensureConnected(redisClient);
+            if (!ok)
+                return 0;
+            let cursor = 0;
+            for (;;) {
+                const scanResult = yield redisClient.scan(cursor, {
+                    MATCH: `${prefix}*`,
+                    COUNT: SCAN_COUNT,
+                });
+                const nextCursor = scanResult.cursor;
+                const keys = scanResult.keys;
+                if (keys.length > 0) {
+                    yield redisClient.del(keys);
+                    deleted += keys.length;
+                }
+                const c = typeof nextCursor === 'bigint' ? Number(nextCursor) : Number(nextCursor);
+                if (c === 0)
+                    break;
+                cursor = nextCursor;
+            }
+        }
+        catch (e) {
+            warn('invalidateByPrefix error', { prefix, error: e instanceof Error ? e.message : String(e) });
+        }
+        return deleted;
+    });
+    const recordAccess = (zsetKey_1, member_1, ...args_1) => __awaiter(this, [zsetKey_1, member_1, ...args_1], void 0, function* (zsetKey, member, incrementBy = 1) {
+        if (!isCacheEnabled())
+            return;
+        try {
+            const ok = yield ensureConnected(redisClient);
+            if (!ok)
+                return;
+            yield redisClient.zIncrBy(zsetKey, incrementBy, member);
+        }
+        catch (e) {
+            warn('recordAccess error', { zsetKey, error: e instanceof Error ? e.message : String(e) });
+        }
+    });
+    return {
+        buildKey,
+        isCacheEnabled,
+        get,
+        set,
+        getOrSet,
+        invalidate,
+        invalidateByPrefix,
+        recordAccess,
+        getDefaultListTtl: () => ({ days: getCacheDaysList() }),
+        getDefaultItemTtl: () => ({ days: getCacheDaysItem() }),
+    };
+}
+/** Key segment separator used by buildKey (exported for invalidation helpers). */
+exports.ROLLING_CACHE_SEP = SEP;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@govish/shared-services",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Govish shared services package - officer, device, station, penal code, station-duty block, and rank leave days cache services; API key service; audit logging; authentication middleware with support for API key + officer combined authentication",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",