@zintrust/core 0.1.1 → 0.1.3

package/src/runtime/adapters/NodeServerAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NodeServerAdapter.d.ts","sourceRoot":"","sources":["../../../../src/runtime/adapters/NodeServerAdapter.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,aAAa,EAGb,cAAc,EACf,MAAM,yBAAyB,CAAC;AAEjC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;OAEG;mBACY,aAAa,GAAG,cAAc,GAAG;QAC9C,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACzD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;KACvB;EAqED,CAAC"}
+{"version":3,"file":"NodeServerAdapter.d.ts","sourceRoot":"","sources":["../../../../src/runtime/adapters/NodeServerAdapter.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,aAAa,EAGb,cAAc,EACf,MAAM,yBAAyB,CAAC;AAEjC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;OAEG;mBACY,aAAa,GAAG,cAAc,GAAG;QAC9C,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACzD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;KACvB;EAoED,CAAC"}

package/src/runtime/adapters/NodeServerAdapter.js

@@ -16,8 +16,9 @@ export const NodeServerAdapter = Object.freeze({
         const state = {};
         return {
             platform: 'nodejs',
+            // eslint-disable-next-line @typescript-eslint/require-await
             async handle(_event, _context) {
-                return Promise.reject(ErrorFactory.createConfigError('Node.js adapter requires startServer() method. Use RuntimeDetector for automatic initialization.'));
+                throw ErrorFactory.createConfigError('Node.js adapter requires startServer() method. Use RuntimeDetector for automatic initialization.');
             },
             /**
              * Start HTTP server for Node.js environments

package/src/scheduler/ScheduleRunner.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ScheduleRunner
+ * Lightweight, zero-dependency schedule runner for long-running runtimes
+ */
+import type { ISchedule, IScheduleKernel } from './types';
+type ScheduleRunner = {
+    register: (schedule: ISchedule) => void;
+    start: (kernel?: IScheduleKernel) => void;
+    stop: (timeoutMs?: number) => Promise<void>;
+    list: () => ISchedule[];
+    runOnce: (name: string, kernel?: IScheduleKernel) => Promise<void>;
+};
+export declare const create: () => Readonly<ScheduleRunner>;
+declare const _default: {
+    create: () => Readonly<ScheduleRunner>;
+};
+export default _default;
+//# sourceMappingURL=ScheduleRunner.d.ts.map

package/src/scheduler/ScheduleRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleRunner.d.ts","sourceRoot":"","sources":["../../../src/scheduler/ScheduleRunner.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAgBnE,KAAK,cAAc,GAAG;IACpB,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,CAAC;IACxC,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;IAC1C,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,EAAE,MAAM,SAAS,EAAE,CAAC;IACxB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE,CAAC;AAoKF,eAAO,MAAM,MAAM,QAAO,QAAQ,CAAC,cAAc,CAuBhD,CAAC;;kBAvBwB,QAAQ,CAAC,cAAc,CAAC;;AAyBlD,wBAA0B"}

package/src/scheduler/ScheduleRunner.js

@@ -0,0 +1,155 @@
+/**
+ * ScheduleRunner
+ * Lightweight, zero-dependency schedule runner for long-running runtimes
+ */
+import { Logger } from '../config/logger';
+import { ErrorFactory } from '../exceptions/ZintrustError';
+const createRegister = (runner, invokeHandler) => (schedule) => {
+    if (runner.schedules.has(schedule.name)) {
+        Logger.warn(`Schedule replaced: ${schedule.name}`);
+    }
+    const state = {
+        schedule,
+        isRunning: false,
+    };
+    runner.schedules.set(schedule.name, state);
+    // If schedules are already started, register should take effect immediately.
+    if (runner.started && schedule.enabled !== false) {
+        if (schedule.runOnStart === true) {
+            void invokeHandler(state, runner.kernel);
+        }
+        if (typeof schedule.intervalMs === 'number' && schedule.intervalMs > 0) {
+            state.intervalId = globalThis.setInterval(() => {
+                void invokeHandler(state, runner.kernel);
+            }, schedule.intervalMs);
+        }
+    }
+};
+const createInvokeHandler = () => async (state, kernel) => {
+    if (state.isRunning) {
+        Logger.info(`Skipping overlapping run for schedule: ${state.schedule.name}`);
+        return;
+    }
+    state.isRunning = true;
+    try {
+        const handlerPromise = Promise.resolve()
+            .then(async () => state.schedule.handler(kernel))
+            .then(() => {
+            state.lastRunAt = Date.now();
+        })
+            .catch((error) => {
+            Logger.error(`Schedule '${state.schedule.name}' failed:`, error);
+        })
+            .then(() => undefined);
+        state.runningPromise = handlerPromise;
+        await handlerPromise;
+    }
+    finally {
+        state.isRunning = false;
+        state.runningPromise = undefined;
+    }
+};
+const createStart = (runner, invokeHandler) => (kernel) => {
+    if (runner.started)
+        return;
+    runner.started = true;
+    runner.kernel = kernel;
+    for (const [, state] of runner.schedules) {
+        const { schedule } = state;
+        if (schedule.enabled === false)
+            continue;
+        if (schedule.runOnStart === true) {
+            // fire-and-forget (handled by invokeHandler which logs errors)
+            void invokeHandler(state, kernel);
+        }
+        if (typeof schedule.intervalMs === 'number' && schedule.intervalMs > 0) {
+            const id = globalThis.setInterval(() => {
+                // fire and forget invocation; overlapping runs are protected inside
+                void invokeHandler(state, kernel);
+            }, schedule.intervalMs);
+            state.intervalId = id;
+        }
+    }
+};
+const createStop = (runner) => async () => {
+    if (!runner.started)
+        return;
+    runner.started = false;
+    runner.kernel = undefined;
+    // Clear intervals
+    for (const [, state] of runner.schedules) {
+        if (state.intervalId !== undefined) {
+            globalThis.clearInterval(state.intervalId);
+            state.intervalId = undefined;
+        }
+    }
+    // Await running handlers (runningPromise is guaranteed not to reject)
+    const running = [];
+    for (const [, state] of runner.schedules) {
+        if (state.isRunning && state.runningPromise !== undefined) {
+            running.push(state.runningPromise);
+        }
+    }
+    if (running.length > 0) {
+        await Promise.all(running);
+    }
+};
+const withTimeout = async (promise, timeoutMs) => {
+    const ms = typeof timeoutMs === 'number' ? timeoutMs : 0;
+    if (ms <= 0) {
+        await promise;
+        return;
+    }
+    let timeoutId;
+    try {
+        await Promise.race([
+            promise,
+            new Promise((resolve) => {
+                timeoutId = globalThis.setTimeout(() => {
+                    Logger.error('ScheduleRunner.stop() timed out; continuing shutdown', {
+                        timeoutMs: ms,
+                    });
+                    resolve();
+                }, ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutId !== undefined)
+            globalThis.clearTimeout(timeoutId);
+    }
+};
+const createStopWithTimeout = (stop) => async (timeoutMs) => {
+    await withTimeout(stop(), timeoutMs);
+};
+const createList = (runner) => () => Array.from(runner.schedules.values()).map((s) => s.schedule);
+const createRunOnce = (runner, invokeHandler) => async (name, kernel) => {
+    const state = runner.schedules.get(name);
+    if (state === undefined)
+        throw ErrorFactory.createNotFoundError(`Schedule not found: ${name}`);
+    if (state.schedule.enabled === false)
+        return;
+    await invokeHandler(state, kernel ?? runner.kernel);
+};
+export const create = () => {
+    const runner = {
+        schedules: new Map(),
+        started: false,
+        kernel: undefined,
+    };
+    const invokeHandler = createInvokeHandler();
+    const register = createRegister(runner, invokeHandler);
+    const start = createStart(runner, invokeHandler);
+    const stopRaw = createStop(runner);
+    const stop = createStopWithTimeout(stopRaw);
+    const list = createList(runner);
+    const runOnce = createRunOnce(runner, invokeHandler);
+    return Object.freeze({
+        register,
+        start,
+        stop,
+        list,
+        runOnce,
+    });
+};
+export default { create };

package/src/scheduler/index.d.ts

@@ -0,0 +1,3 @@
+export { create as createScheduleRunner } from './ScheduleRunner';
+export type { ISchedule } from './types';
+//# sourceMappingURL=index.d.ts.map

package/src/scheduler/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/scheduler/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAC3E,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC"}

package/src/scheduler/index.js

@@ -0,0 +1 @@
+export { create as createScheduleRunner } from './ScheduleRunner';

package/src/scheduler/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Scheduler types
+ */
+export type IScheduleKernel = Readonly<{
+    getContainer?: () => unknown;
+    getRouter?: () => unknown;
+}>;
+export type IScheduleHandler = (kernel?: IScheduleKernel) => Promise<void> | void;
+export type ISchedule = {
+    name: string;
+    intervalMs?: number;
+    handler: IScheduleHandler;
+    enabled?: boolean;
+    runOnStart?: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/src/scheduler/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/scheduler/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;CAC3B,CAAC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAElF,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC"}

package/src/scheduler/types.js

@@ -0,0 +1,4 @@
+/**
+ * Scheduler types
+ */
+export {};

package/src/schedules/index.d.ts

@@ -0,0 +1,2 @@
+export { default as logCleanup } from './log-cleanup';
+//# sourceMappingURL=index.d.ts.map

package/src/schedules/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/schedules/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,wBAAwB,CAAC"}

package/src/schedules/index.js

@@ -0,0 +1 @@
+export { default as logCleanup } from './log-cleanup';

package/src/schedules/log-cleanup.d.ts

@@ -0,0 +1,4 @@
+import type { ISchedule } from '../scheduler/types';
+declare const LogCleanupSchedule: ISchedule;
+export default LogCleanupSchedule;
+//# sourceMappingURL=log-cleanup.d.ts.map

package/src/schedules/log-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-cleanup.d.ts","sourceRoot":"","sources":["../../../src/schedules/log-cleanup.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAIlD,QAAA,MAAM,kBAAkB,EAAE,SAYzB,CAAC;AAEF,eAAe,kBAAkB,CAAC"}

package/src/schedules/log-cleanup.js

@@ -0,0 +1,18 @@
+import { Env } from '../config/env';
+import { Logger, cleanLogsOnce } from '../config/logger';
+const intervalMs = Env.getInt('LOG_CLEANUP_INTERVAL_MS', 3600000);
+const LogCleanupSchedule = {
+    name: 'log.cleanup',
+    intervalMs: intervalMs,
+    handler: async () => {
+        try {
+            await cleanLogsOnce();
+        }
+        catch (err) {
+            Logger.error('Log cleanup schedule failed', err);
+        }
+    },
+    enabled: Env.getBool('LOG_CLEANUP_ENABLED', Env.getBool('LOG_TO_FILE', false)),
+    runOnStart: false,
+};
+export default LogCleanupSchedule;

package/src/scripts/GenerateEnvArtifacts.d.ts

@@ -0,0 +1,13 @@
+/**
+ * GenerateEnvArtifacts
+ * - Generates env.d.ts and .env.example from the framework's Env usage.
+ *
+ * Goals:
+ * - Developer convenience (discoverable env keys)
+ * - Keep env.d.ts + .env.example in sync with src/config usage
+ *
+ * Usage:
+ *   tsx src/scripts/GenerateEnvArtifacts.ts
+ */
+export {};
+//# sourceMappingURL=GenerateEnvArtifacts.d.ts.map

package/src/scripts/GenerateEnvArtifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GenerateEnvArtifacts.d.ts","sourceRoot":"","sources":["../../../src/scripts/GenerateEnvArtifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/src/scripts/GenerateEnvArtifacts.js

@@ -0,0 +1,171 @@
+/**
+ * GenerateEnvArtifacts
+ * - Generates env.d.ts and .env.example from the framework's Env usage.
+ *
+ * Goals:
+ * - Developer convenience (discoverable env keys)
+ * - Keep env.d.ts + .env.example in sync with src/config usage
+ *
+ * Usage:
+ *   tsx src/scripts/GenerateEnvArtifacts.ts
+ */
+import { Logger } from '../config/logger';
+import { ErrorFactory } from '../exceptions/ZintrustError';
+import fs from '../node-singletons/fs';
+import * as path from '../node-singletons/path';
+const ROOT_DIR = path.resolve(process.cwd());
+const GENERATED_MARKER = 'Generated by src/scripts/GenerateEnvArtifacts.ts';
+const walkDir = (dirAbs) => {
+    const out = [];
+    const entries = fs.readdirSync(dirAbs, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'coverage')
+            continue;
+        const abs = path.join(dirAbs, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...walkDir(abs));
+            continue;
+        }
+        if (entry.isFile() && entry.name.endsWith('.ts'))
+            out.push(abs);
+    }
+    return out;
+};
+const readText = (fileAbs) => fs.readFileSync(fileAbs, 'utf8');
+const uniq = (arr) => Array.from(new Set(arr));
+const parseEnvUsages = (content) => {
+    const out = [];
+    // Avoid catastrophic backtracking by not using complex regexes to parse arbitrary JS.
+    // Instead scan for Env.<method>(...), handle quotes/escapes and balanced parentheses in linear time.
+    const extractArgs = (parenIdx) => {
+        let i = parenIdx;
+        if (content[i] !== '(')
+            return { args: '', endIdx: i + 1 };
+        i++; // move past '('
+        const start = i;
+        let depth = 1;
+        // Skip a quoted string starting at idx (idx points at the opening quote).
+        const skipQuoted = (idx) => {
+            let newIdx = idx;
+            const quote = content[newIdx];
+            newIdx++;
+            while (newIdx < content.length) {
+                if (content[newIdx] === '\\') {
+                    newIdx += 2;
+                    continue;
+                }
+                if (content[newIdx] === quote) {
+                    return newIdx + 1;
+                }
+                newIdx++;
+            }
+            return newIdx;
+        };
+        while (i < content.length && depth > 0) {
+            const ch = content[i];
+            if (ch === "'" || ch === '"') {
+                i = skipQuoted(i);
+                continue;
+            }
+            if (ch === '(') {
+                depth++;
+                i++;
+                continue;
+            }
+            if (ch === ')') {
+                depth--;
+                if (depth === 0) {
+                    return { args: content.slice(start, i), endIdx: i + 1 };
+                }
+                i++;
+                continue;
+            }
+            i++;
+        }
+        // unbalanced or EOF: return what we have
+        return { args: content.slice(start, i), endIdx: i };
+    };
+    const methods = ['get', 'getInt', 'getBool'];
+    for (const method of methods) {
+        const token = `Env.${method}(`;
+        let idx = content.indexOf(token, 0);
+        while (idx !== -1) {
+            const parenIdx = idx + token.length - 1; // position of '('
+            const { args, endIdx } = extractArgs(parenIdx);
+            // args looks like: ['KEY'[, defaultVal]]
+            const keyMatch = /^\s*['"]([A-Z0-9_]+)['"]/.exec(args);
+            if (keyMatch) {
+                const key = keyMatch[1];
+                const rest = args.slice(keyMatch[0].length);
+                const restTrimmed = rest.replace(/^\s*,\s*/, '').trim();
+                const defaultValue = restTrimmed.length > 0 ? restTrimmed : undefined;
+                out.push({ key, defaultValue });
+            }
+            idx = content.indexOf(token, endIdx);
+        }
+    }
+    return out;
+};
+const renderEnvDts = (keys) => {
+    const sortedKeys = keys.toSorted((a, b) => a.localeCompare(b));
+    const lines = sortedKeys.map((k) => `    ${k}?: string | undefined;`).join('\n');
+    return `declare namespace NodeJS {\n  interface ProcessEnv {\n    NODE_ENV: 'development' | 'production' | 'testing' | undefined;\n\n${lines}\n  }\n}\n`;
+};
+const renderEnvExample = (keys) => {
+    const header = `# Zintrust Framework - Environment Configuration\n# Generated by src/scripts/GenerateEnvArtifacts.ts\n# Copy this file to .env and configure for your environment\n\n`;
+    const sortedKeys = keys.toSorted((a, b) => a.localeCompare(b));
+    const body = sortedKeys
+        .filter((k) => k !== 'NODE_ENV')
+        .map((k) => `${k}=`)
+        .join('\n');
+    return header + `NODE_ENV=development\n` + body + `\n`;
+};
+const renderEnvKeys = (keys) => {
+    const sortedKeys = keys.toSorted((a, b) => a.localeCompare(b));
+    return sortedKeys.join('\n') + '\n';
+};
+const writeIfChanged = (fileAbs, next) => {
+    const prev = fs.existsSync(fileAbs) ? fs.readFileSync(fileAbs, 'utf8') : '';
+    if (prev === next)
+        return;
+    fs.writeFileSync(fileAbs, next, 'utf8');
+};
+const shouldOverwriteEnvExample = (envExampleAbs) => {
+    if (!fs.existsSync(envExampleAbs))
+        return true;
+    const prev = fs.readFileSync(envExampleAbs, 'utf8');
+    return prev.includes(GENERATED_MARKER);
+};
+const main = () => {
+    try {
+        const configDir = path.join(ROOT_DIR, 'src', 'config');
+        const configFiles = walkDir(configDir);
+        const usages = configFiles.flatMap((f) => parseEnvUsages(readText(f)));
+        const keys = uniq(usages.map((u) => u.key));
+        if (keys.length === 0) {
+            throw ErrorFactory.createTryCatchError('No Env.get usages found under src/config');
+        }
+        // env.d.ts
+        const envDtsPath = path.join(ROOT_DIR, 'env.d.ts');
+        writeIfChanged(envDtsPath, renderEnvDts(keys));
+        // .env.example (non-destructive by default)
+        const envExamplePath = path.join(ROOT_DIR, '.env.example');
+        const generatedExamplePath = path.join(ROOT_DIR, '.env.example.generated');
+        const renderedExample = renderEnvExample(keys);
+        if (shouldOverwriteEnvExample(envExamplePath)) {
+            writeIfChanged(envExamplePath, renderedExample);
+        }
+        else {
+            writeIfChanged(generatedExamplePath, renderedExample);
+        }
+        // .env.keys (for quick discovery / tooling)
+        const envKeysPath = path.join(ROOT_DIR, '.env.keys');
+        writeIfChanged(envKeysPath, renderEnvKeys(keys));
+        Logger.info(`✓ Generated env artifacts (keys: ${keys.length})`);
+    }
+    catch (error) {
+        Logger.error('GenerateEnvArtifacts failed', error);
+        process.exit(1);
+    }
+};
+main();