@cyberskill/shared 3.13.0 → 3.14.0

package/dist/node/path/path.constant.js.map

@@ -1 +1 @@
-{"version":3,"file":"path.constant.js","names":[],"sources":["../../../src/node/path/path.constant.ts"],"sourcesContent":["import fsExtra from 'fs-extra';\n\nimport { getEnv } from '#config/env/index.js';\n\nimport type { I_PackageInput, I_PackageJson } from '../package/index.js';\n\nimport { E_CommandType, formatCommand, rawCommand } from '../command/index.js';\nimport { E_PackageType, setupPackages } from '../package/index.js';\nimport { join, resolveWorkingPath } from './path.util.js';\n\nexport const WORKING_DIRECTORY = getEnv().CWD;\nexport const CYBERSKILL_PACKAGE_NAME = '@cyberskill/shared';\nexport const NODE_MODULES = 'node_modules';\nexport const BUILD_DIRECTORY = 'dist';\nexport const PUBLIC_DIRECTORY = 'public';\nexport const PACKAGE_JSON = 'package.json';\nexport const PACKAGE_LOCK_JSON = 'package-lock.json';\nexport const TSCONFIG_JSON = 'tsconfig.json';\nexport const GIT_IGNORE = '.gitignore';\nexport const SIMPLE_GIT_HOOK_JSON = '.simple-git-hooks.json';\nexport const PNPM_LOCK_YAML = 'pnpm-lock.yaml';\nexport const GIT_HOOK = '.git/hooks/';\nexport const GIT_COMMIT_EDITMSG = '.git/COMMIT_EDITMSG';\nexport const GIT_EXCLUDE = '.git/info/exclude';\nexport const MIGRATE_MONGO_CONFIG = '.migrate-mongo.config.js';\nlet _cyberskillDir: string | null = null;\n\n/**\n * Lazily computes the CyberSkill directory path.\n * Reads package.json on first access to determine whether this is the shared package itself\n * or a consumer project, avoiding filesystem reads at module load time.\n */\nexport function getCyberskillDirectory(): string {\n    if (_cyberskillDir !== null) {\n        return _cyberskillDir;\n    }\n\n    try {\n        const packageJson = fsExtra.readJsonSync(resolveWorkingPath(PACKAGE_JSON)) as I_PackageJson;\n\n        _cyberskillDir = packageJson.name === CYBERSKILL_PACKAGE_NAME\n            ? join(WORKING_DIRECTORY, BUILD_DIRECTORY)\n            : join(WORKING_DIRECTORY, NODE_MODULES, CYBERSKILL_PACKAGE_NAME, BUILD_DIRECTORY);\n    }\n    catch {\n        _cyberskillDir = join(WORKING_DIRECTORY, NODE_MODULES, CYBERSKILL_PACKAGE_NAME, BUILD_DIRECTORY);\n    }\n\n    return _cyberskillDir;\n}\n\n/** @deprecated Use `getCyberskillDirectory()` instead. Kept for backward compatibility. */\nexport const CYBERSKILL_DIRECTORY = getCyberskillDirectory();\nexport const CYBERSKILL_CLI = 'cyberskill';\nexport const CYBERSKILL_CLI_PATH = 'src/node/cli/index.ts';\nexport const ESLINT_PACKAGE_NAME = 'eslint';\nexport const ESLINT_CLI = 'eslint';\nexport const VITEST_PACKAGE_NAME = 'vitest';\nexport const VITEST_CLI = 'vitest';\nexport const COMMIT_LINT_PACKAGE_NAME = '@commitlint/cli';\nexport const COMMIT_LINT_CONVENTIONAL_CONFIG_PACKAGE_NAME = '@commitlint/config-conventional';\nexport const COMMIT_LINT_CLI = 'commitlint';\nexport const LINT_STAGED_PACKAGE_NAME = 'lint-staged';\nexport const LINT_STAGED_CLI = 'lint-staged';\nexport const TSC_PACKAGE_NAME = 'typescript';\nexport const TSC_CLI = 'tsc';\nexport const TSX_CLI = 'tsx';\nexport const GIT_CLI = 'git';\nexport const PNPM_CLI = 'pnpm';\nexport const PNPM_EXEC_CLI = 'pnpm exec';\nexport const SIMPLE_GIT_HOOKS_PACKAGE_NAME = 'simple-git-hooks';\nexport const SIMPLE_GIT_HOOK_CLI = 'simple-git-hooks';\nexport const ESLINT_INSPECT_PACKAGE_NAME = '@eslint/config-inspector';\nexport const ESLINT_INSPECT_CLI = 'eslint-config-inspector';\nexport const NODE_MODULES_INSPECT_PACKAGE_NAME = 'node-modules-inspector';\nexport const NODE_MODULES_INSPECT_CLI = 'node-modules-inspector';\nexport const MIGRATE_MONGO_PACKAGE_NAME = 'migrate-mongo';\nexport const MIGRATE_MONGO_CLI = './node_modules/migrate-mongo/bin/migrate-mongo';\nexport const STORYBOOK_PACKAGE_NAME = 'storybook';\nexport const STORYBOOK_CLI = 'storybook';\nexport const AG_KIT_PACKAGE_NAME = '@vudovn/ag-kit';\nexport const DOT_AGENT = '.agent';\n\nexport const PATH = {\n    /** Lazily resolved — defers `getCyberskillDirectory()` until first property access. */\n    get CYBERSKILL_DIRECTORY() { return getCyberskillDirectory(); },\n    WORKING_DIRECTORY,\n    PUBLIC_DIRECTORY: resolveWorkingPath(PUBLIC_DIRECTORY),\n    TS_CONFIG: resolveWorkingPath(TSCONFIG_JSON),\n    GIT_IGNORE: resolveWorkingPath(GIT_IGNORE),\n    GIT_HOOK: resolveWorkingPath(GIT_HOOK),\n    GIT_COMMIT_MSG: resolveWorkingPath(GIT_COMMIT_EDITMSG),\n    GIT_EXCLUDE: resolveWorkingPath(GIT_EXCLUDE),\n    SIMPLE_GIT_HOOKS_JSON: resolveWorkingPath(SIMPLE_GIT_HOOK_JSON),\n    PACKAGE_JSON: resolveWorkingPath(PACKAGE_JSON),\n    PACKAGE_LOCK_JSON: resolveWorkingPath(PACKAGE_LOCK_JSON),\n    PNPM_LOCK_YAML: resolveWorkingPath(PNPM_LOCK_YAML),\n    NODE_MODULES: resolveWorkingPath(NODE_MODULES),\n    MIGRATE_MONGO_CONFIG: resolveWorkingPath(MIGRATE_MONGO_CONFIG),\n    /** Lazily resolved — defers `getCyberskillDirectory()` until first property access. */\n    get LINT_STAGED_CONFIG() { return resolveWorkingPath(`${getCyberskillDirectory()}/config/lint-staged/index.js`); },\n    /** Lazily resolved — defers `getCyberskillDirectory()` until first property access. */\n    get COMMITLINT_CONFIG() { return resolveWorkingPath(`${getCyberskillDirectory()}/config/commitlint/index.js`); },\n    /** Lazily resolved — defers `getCyberskillDirectory()` until first property access. */\n    get VITEST_UNIT_CONFIG() { return resolveWorkingPath(`${getCyberskillDirectory()}/config/vitest/vitest.unit.js`); },\n    /** Lazily resolved — defers `getCyberskillDirectory()` until first property access. */\n    get VITEST_E2E_CONFIG() { return resolveWorkingPath(`${getCyberskillDirectory()}/config/vitest/vitest.e2e.js`); },\n    /** Lazily resolved — defers `getCyberskillDirectory()` until first property access. */\n    get STORYBOOK_MAIN_CONFIG() { return resolveWorkingPath(`${getCyberskillDirectory()}/config/storybook/storybook.main.js`); },\n    /** Lazily resolved — defers `getCyberskillDirectory()` until first property access. */\n    get STORYBOOK_PREVIEW_CONFIG() { return resolveWorkingPath(`${getCyberskillDirectory()}/config/storybook/storybook.preview.js`); },\n    DOT_AGENT: resolveWorkingPath(DOT_AGENT),\n};\n\n/**\n * Creates Git hooks configuration based on whether this is the current project.\n * This function generates a configuration object for Git hooks that includes\n * pre-commit and commit-msg hooks, with an optional pre-push hook for the current project.\n *\n * @returns A Git hooks configuration object with appropriate commands for each hook.\n */\nexport function createGitHooksConfig() {\n    return {\n        'pre-commit': LINT_STAGED_CLI,\n        'commit-msg': COMMIT_LINT_CLI,\n        'pre-push': rawCommand(`${GIT_CLI} pull && ${PNPM_CLI} run --if-present test`),\n    };\n}\n\n/**\n * Builds a command function based on the specified type and configuration.\n * This function creates a command executor that handles different command types\n * including CLI commands and string commands. It manages package dependencies\n * and formats commands appropriately for execution.\n *\n * The function supports:\n * - CLI commands that require package installation\n * - String commands that are executed directly\n * - Automatic package dependency management\n * - Command formatting and validation\n *\n * @param config - Configuration object containing type, packages, and command properties.\n * @param config.type - The type of command to build (CLI or STRING).\n * @param config.packages - Optional array of packages required for CLI commands.\n * @param config.command - The command string to execute.\n * @returns A function that returns a promise resolving to the formatted command string.\n * @throws {Error} When an unsupported command type is provided.\n */\nfunction buildCommand({ type, packages, command }: { type: E_CommandType; packages?: I_PackageInput[]; command: string }): () => Promise<string> {\n    const uniquePackages = packages?.reduce((acc: I_PackageInput[], pkg) => {\n        if (!acc.some(existingPkg => existingPkg.name === pkg.name)) {\n            acc.push(pkg);\n        }\n        return acc;\n    }, []);\n\n    return async () => {\n        switch (type) {\n            case E_CommandType.CLI: {\n                if (uniquePackages?.length) {\n                    await setupPackages(uniquePackages, {\n                        install: true,\n                    });\n                }\n\n                return formatCommand(rawCommand(`${PNPM_EXEC_CLI} ${command}`)) as string;\n            }\n            case E_CommandType.STRING: {\n                return formatCommand(rawCommand(command)) as string;\n            }\n            default: {\n                throw new Error('Unsupported command type');\n            }\n        }\n    };\n}\n\nconst RE_MIGRATE_NAME = /^[\\w-]+$/;\n\nexport const command = {\n    simpleGitHooks: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: SIMPLE_GIT_HOOKS_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n\n        ],\n        command: SIMPLE_GIT_HOOK_CLI,\n    }),\n    eslintInspect: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name:\n                    ESLINT_INSPECT_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n\n        ],\n        command: ESLINT_INSPECT_CLI,\n    }),\n    nodeModulesInspect: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: NODE_MODULES_INSPECT_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n\n        ],\n        command: NODE_MODULES_INSPECT_CLI,\n    }),\n    eslintCheck: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: ESLINT_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n\n        ],\n        command: `${ESLINT_CLI} ${PATH.WORKING_DIRECTORY} --no-cache`,\n    }),\n    eslintFix: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: ESLINT_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n\n        ],\n        command: `${ESLINT_CLI} ${PATH.WORKING_DIRECTORY} --fix --no-cache`,\n    }),\n    typescriptCheck: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: TSC_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n\n        ],\n        command: `${TSC_CLI} -p ${PATH.TS_CONFIG} --noEmit --incremental`,\n    }),\n    testUnit: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: VITEST_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n        ],\n        command: `${VITEST_CLI} --config ${PATH.VITEST_UNIT_CONFIG}`,\n    }),\n    testE2e: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: VITEST_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n        ],\n        command: `${VITEST_CLI} --config ${PATH.VITEST_E2E_CONFIG}`,\n    }),\n    mongoMigrateCreate: (migrateName: string) => {\n        if (!RE_MIGRATE_NAME.test(migrateName)) {\n            throw new Error('Migration name must only contain alphanumeric characters, underscores, and hyphens.');\n        }\n\n        return buildCommand({\n            type: E_CommandType.CLI,\n            packages: [\n                {\n                    name: TSX_CLI,\n                    type: E_PackageType.DEPENDENCY,\n                },\n                {\n                    name: MIGRATE_MONGO_PACKAGE_NAME,\n                    type: E_PackageType.DEPENDENCY,\n                },\n            ],\n            command: `${TSX_CLI} ${MIGRATE_MONGO_CLI} create ${migrateName} -f ${PATH.MIGRATE_MONGO_CONFIG}`,\n        })();\n    },\n    mongoMigrateUp: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: TSX_CLI,\n                type: E_PackageType.DEPENDENCY,\n            },\n            {\n                name: MIGRATE_MONGO_PACKAGE_NAME,\n                type: E_PackageType.DEPENDENCY,\n            },\n        ],\n        command: `${TSX_CLI} ${MIGRATE_MONGO_CLI} up -f ${PATH.MIGRATE_MONGO_CONFIG}`,\n    }),\n    mongoMigrateDown: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: TSX_CLI,\n                type: E_PackageType.DEPENDENCY,\n            },\n            {\n                name: MIGRATE_MONGO_PACKAGE_NAME,\n                type: E_PackageType.DEPENDENCY,\n            },\n        ],\n        command: `${TSX_CLI} ${MIGRATE_MONGO_CLI} down -f ${PATH.MIGRATE_MONGO_CONFIG}`,\n    }),\n    commitLint: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: COMMIT_LINT_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n            {\n                name: COMMIT_LINT_CONVENTIONAL_CONFIG_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n        ],\n        command: `${COMMIT_LINT_CLI} --edit ${PATH.GIT_COMMIT_MSG} --config ${PATH.COMMITLINT_CONFIG}`,\n    }),\n    lintStaged: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: LINT_STAGED_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n        ],\n        command: `${LINT_STAGED_CLI} --config ${PATH.LINT_STAGED_CONFIG}`,\n    }),\n    configureGitHook: buildCommand({\n        type: E_CommandType.STRING,\n        command: `${GIT_CLI} config core.hooksPath ${PATH.GIT_HOOK}`,\n    }),\n    build: buildCommand({\n        type: E_CommandType.STRING,\n        command: `${PNPM_CLI} run --if-present build`,\n    }),\n    pnpmInstallStandard: buildCommand({\n        type: E_CommandType.STRING,\n        command: `${PNPM_CLI} install --ignore-scripts`,\n    }),\n    pnpmInstallLegacy: buildCommand({\n        type: E_CommandType.STRING,\n        command: `${PNPM_CLI} install --ignore-scripts --legacy-peer-deps`,\n    }),\n    pnpmInstallForce: buildCommand({\n        type: E_CommandType.STRING,\n        command: `${PNPM_CLI} install --ignore-scripts --force`,\n    }),\n    pnpmPruneStore: buildCommand({\n        type: E_CommandType.STRING,\n        command: `${PNPM_CLI} store prune`,\n    }),\n    pnpmCleanCache: buildCommand({\n        type: E_CommandType.STRING,\n        command: `${PNPM_CLI} cache delete`,\n    }),\n    storybookDev: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: STORYBOOK_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n        ],\n        command: `${STORYBOOK_CLI} dev`,\n    }),\n    storybookBuild: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: STORYBOOK_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n        ],\n        command: `${STORYBOOK_CLI} build`,\n    }),\n};\n"],"mappings":"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"}
+{"version":3,"file":"path.constant.js","names":[],"sources":["../../../src/node/path/path.constant.ts"],"sourcesContent":["import fsExtra from 'fs-extra';\n\nimport { getEnv } from '#config/env/index.js';\n\nimport type { I_PackageInput, I_PackageJson } from '../package/index.js';\n\nimport { E_CommandType, formatCommand, rawCommand } from '../command/index.js';\nimport { E_PackageType, setupPackages } from '../package/index.js';\nimport { join, resolveWorkingPath } from './path.util.js';\n\nexport const WORKING_DIRECTORY = getEnv().CWD;\nexport const CYBERSKILL_PACKAGE_NAME = '@cyberskill/shared';\nexport const NODE_MODULES = 'node_modules';\nexport const BUILD_DIRECTORY = 'dist';\nexport const PUBLIC_DIRECTORY = 'public';\nexport const PACKAGE_JSON = 'package.json';\nexport const PACKAGE_LOCK_JSON = 'package-lock.json';\nexport const TSCONFIG_JSON = 'tsconfig.json';\nexport const GIT_IGNORE = '.gitignore';\nexport const SIMPLE_GIT_HOOK_JSON = '.simple-git-hooks.json';\nexport const PNPM_LOCK_YAML = 'pnpm-lock.yaml';\nexport const GIT_HOOK = '.git/hooks/';\nexport const GIT_COMMIT_EDITMSG = '.git/COMMIT_EDITMSG';\nexport const GIT_EXCLUDE = '.git/info/exclude';\nexport const MIGRATE_MONGO_CONFIG = '.migrate-mongo.config.js';\nlet _cyberskillDir: string | null = null;\n\n/**\n * Resets the cached directory path. For testing only.\n */\nexport function resetCyberskillDirCacheForTesting(): void {\n    _cyberskillDir = null;\n}\n\n/**\n * Lazily computes the CyberSkill directory path.\n * Reads package.json on first access to determine whether this is the shared package itself\n * or a consumer project, avoiding filesystem reads at module load time.\n */\nexport function getCyberskillDirectory(): string {\n    if (_cyberskillDir !== null) {\n        return _cyberskillDir;\n    }\n\n    try {\n        const packageJson = fsExtra.readJsonSync(resolveWorkingPath(PACKAGE_JSON)) as I_PackageJson;\n\n        _cyberskillDir = packageJson.name === CYBERSKILL_PACKAGE_NAME\n            ? join(WORKING_DIRECTORY, BUILD_DIRECTORY)\n            : join(WORKING_DIRECTORY, NODE_MODULES, CYBERSKILL_PACKAGE_NAME, BUILD_DIRECTORY);\n    }\n    catch {\n        /* Intentionally empty — fallback to node_modules path when package.json is unreadable */\n        _cyberskillDir = join(WORKING_DIRECTORY, NODE_MODULES, CYBERSKILL_PACKAGE_NAME, BUILD_DIRECTORY);\n    }\n\n    return _cyberskillDir;\n}\n\n/** @deprecated Use `getCyberskillDirectory()` instead. Kept for backward compatibility. */\nexport const CYBERSKILL_DIRECTORY = getCyberskillDirectory();\nexport const CYBERSKILL_CLI = 'cyberskill';\nexport const CYBERSKILL_CLI_PATH = 'src/node/cli/index.ts';\nexport const ESLINT_PACKAGE_NAME = 'eslint';\nexport const ESLINT_CLI = 'eslint';\nexport const VITEST_PACKAGE_NAME = 'vitest';\nexport const VITEST_CLI = 'vitest';\nexport const COMMIT_LINT_PACKAGE_NAME = '@commitlint/cli';\nexport const COMMIT_LINT_CONVENTIONAL_CONFIG_PACKAGE_NAME = '@commitlint/config-conventional';\nexport const COMMIT_LINT_CLI = 'commitlint';\nexport const LINT_STAGED_PACKAGE_NAME = 'lint-staged';\nexport const LINT_STAGED_CLI = 'lint-staged';\nexport const TSC_PACKAGE_NAME = 'typescript';\nexport const TSC_CLI = 'tsc';\nexport const TSX_CLI = 'tsx';\nexport const GIT_CLI = 'git';\nexport const PNPM_CLI = 'pnpm';\nexport const PNPM_EXEC_CLI = 'pnpm exec';\nexport const SIMPLE_GIT_HOOKS_PACKAGE_NAME = 'simple-git-hooks';\nexport const SIMPLE_GIT_HOOK_CLI = 'simple-git-hooks';\nexport const ESLINT_INSPECT_PACKAGE_NAME = '@eslint/config-inspector';\nexport const ESLINT_INSPECT_CLI = 'eslint-config-inspector';\nexport const NODE_MODULES_INSPECT_PACKAGE_NAME = 'node-modules-inspector';\nexport const NODE_MODULES_INSPECT_CLI = 'node-modules-inspector';\nexport const MIGRATE_MONGO_PACKAGE_NAME = 'migrate-mongo';\nexport const MIGRATE_MONGO_CLI = './node_modules/migrate-mongo/bin/migrate-mongo';\nexport const STORYBOOK_PACKAGE_NAME = 'storybook';\nexport const STORYBOOK_CLI = 'storybook';\nexport const AG_KIT_PACKAGE_NAME = '@vudovn/ag-kit';\nexport const DOT_AGENT = '.agent';\n\nexport const PATH = {\n    /** Lazily resolved — defers `getCyberskillDirectory()` until first property access. */\n    get CYBERSKILL_DIRECTORY() { return getCyberskillDirectory(); },\n    WORKING_DIRECTORY,\n    PUBLIC_DIRECTORY: resolveWorkingPath(PUBLIC_DIRECTORY),\n    TS_CONFIG: resolveWorkingPath(TSCONFIG_JSON),\n    GIT_IGNORE: resolveWorkingPath(GIT_IGNORE),\n    GIT_HOOK: resolveWorkingPath(GIT_HOOK),\n    GIT_COMMIT_MSG: resolveWorkingPath(GIT_COMMIT_EDITMSG),\n    GIT_EXCLUDE: resolveWorkingPath(GIT_EXCLUDE),\n    SIMPLE_GIT_HOOKS_JSON: resolveWorkingPath(SIMPLE_GIT_HOOK_JSON),\n    PACKAGE_JSON: resolveWorkingPath(PACKAGE_JSON),\n    PACKAGE_LOCK_JSON: resolveWorkingPath(PACKAGE_LOCK_JSON),\n    PNPM_LOCK_YAML: resolveWorkingPath(PNPM_LOCK_YAML),\n    NODE_MODULES: resolveWorkingPath(NODE_MODULES),\n    MIGRATE_MONGO_CONFIG: resolveWorkingPath(MIGRATE_MONGO_CONFIG),\n    /** Lazily resolved — defers `getCyberskillDirectory()` until first property access. */\n    get LINT_STAGED_CONFIG() { return resolveWorkingPath(`${getCyberskillDirectory()}/config/lint-staged/index.js`); },\n    /** Lazily resolved — defers `getCyberskillDirectory()` until first property access. */\n    get COMMITLINT_CONFIG() { return resolveWorkingPath(`${getCyberskillDirectory()}/config/commitlint/index.js`); },\n    /** Lazily resolved — defers `getCyberskillDirectory()` until first property access. */\n    get VITEST_UNIT_CONFIG() { return resolveWorkingPath(`${getCyberskillDirectory()}/config/vitest/vitest.unit.js`); },\n    /** Lazily resolved — defers `getCyberskillDirectory()` until first property access. */\n    get VITEST_E2E_CONFIG() { return resolveWorkingPath(`${getCyberskillDirectory()}/config/vitest/vitest.e2e.js`); },\n    /** Lazily resolved — defers `getCyberskillDirectory()` until first property access. */\n    get STORYBOOK_MAIN_CONFIG() { return resolveWorkingPath(`${getCyberskillDirectory()}/config/storybook/storybook.main.js`); },\n    /** Lazily resolved — defers `getCyberskillDirectory()` until first property access. */\n    get STORYBOOK_PREVIEW_CONFIG() { return resolveWorkingPath(`${getCyberskillDirectory()}/config/storybook/storybook.preview.js`); },\n    DOT_AGENT: resolveWorkingPath(DOT_AGENT),\n};\n\n/**\n * Creates Git hooks configuration based on whether this is the current project.\n * This function generates a configuration object for Git hooks that includes\n * pre-commit and commit-msg hooks, with an optional pre-push hook for the current project.\n *\n * @returns A Git hooks configuration object with appropriate commands for each hook.\n */\nexport function createGitHooksConfig() {\n    return {\n        'pre-commit': LINT_STAGED_CLI,\n        'commit-msg': COMMIT_LINT_CLI,\n        'pre-push': rawCommand(`${GIT_CLI} pull && ${PNPM_CLI} run --if-present test`),\n    };\n}\n\n/**\n * Builds a command function based on the specified type and configuration.\n * This function creates a command executor that handles different command types\n * including CLI commands and string commands. It manages package dependencies\n * and formats commands appropriately for execution.\n *\n * The function supports:\n * - CLI commands that require package installation\n * - String commands that are executed directly\n * - Automatic package dependency management\n * - Command formatting and validation\n *\n * @param config - Configuration object containing type, packages, and command properties.\n * @param config.type - The type of command to build (CLI or STRING).\n * @param config.packages - Optional array of packages required for CLI commands.\n * @param config.command - The command string to execute.\n * @returns A function that returns a promise resolving to the formatted command string.\n * @throws {Error} When an unsupported command type is provided.\n */\nfunction buildCommand({ type, packages, command }: { type: E_CommandType; packages?: I_PackageInput[]; command: string }): () => Promise<string> {\n    const uniquePackages = packages?.reduce((acc: I_PackageInput[], pkg) => {\n        if (!acc.some(existingPkg => existingPkg.name === pkg.name)) {\n            acc.push(pkg);\n        }\n        return acc;\n    }, []);\n\n    return async () => {\n        switch (type) {\n            case E_CommandType.CLI: {\n                if (uniquePackages?.length) {\n                    await setupPackages(uniquePackages, {\n                        install: true,\n                    });\n                }\n\n                return formatCommand(rawCommand(`${PNPM_EXEC_CLI} ${command}`)) as string;\n            }\n            case E_CommandType.STRING: {\n                return formatCommand(rawCommand(command)) as string;\n            }\n            default: {\n                throw new Error('Unsupported command type');\n            }\n        }\n    };\n}\n\nconst RE_MIGRATE_NAME = /^[\\w-]+$/;\n\nexport const command = {\n    simpleGitHooks: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: SIMPLE_GIT_HOOKS_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n\n        ],\n        command: SIMPLE_GIT_HOOK_CLI,\n    }),\n    eslintInspect: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name:\n                    ESLINT_INSPECT_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n\n        ],\n        command: ESLINT_INSPECT_CLI,\n    }),\n    nodeModulesInspect: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: NODE_MODULES_INSPECT_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n\n        ],\n        command: NODE_MODULES_INSPECT_CLI,\n    }),\n    eslintCheck: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: ESLINT_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n\n        ],\n        command: `${ESLINT_CLI} ${PATH.WORKING_DIRECTORY} --no-cache`,\n    }),\n    eslintFix: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: ESLINT_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n\n        ],\n        command: `${ESLINT_CLI} ${PATH.WORKING_DIRECTORY} --fix --no-cache`,\n    }),\n    typescriptCheck: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: TSC_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n\n        ],\n        command: `${TSC_CLI} -p ${PATH.TS_CONFIG} --noEmit --incremental`,\n    }),\n    testUnit: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: VITEST_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n        ],\n        command: `${VITEST_CLI} --config ${PATH.VITEST_UNIT_CONFIG}`,\n    }),\n    testE2e: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: VITEST_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n        ],\n        command: `${VITEST_CLI} --config ${PATH.VITEST_E2E_CONFIG}`,\n    }),\n    mongoMigrateCreate: (migrateName: string) => {\n        if (!RE_MIGRATE_NAME.test(migrateName)) {\n            throw new Error('Migration name must only contain alphanumeric characters, underscores, and hyphens.');\n        }\n\n        return buildCommand({\n            type: E_CommandType.CLI,\n            packages: [\n                {\n                    name: TSX_CLI,\n                    type: E_PackageType.DEPENDENCY,\n                },\n                {\n                    name: MIGRATE_MONGO_PACKAGE_NAME,\n                    type: E_PackageType.DEPENDENCY,\n                },\n            ],\n            command: `${TSX_CLI} ${MIGRATE_MONGO_CLI} create ${migrateName} -f ${PATH.MIGRATE_MONGO_CONFIG}`,\n        })();\n    },\n    mongoMigrateUp: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: TSX_CLI,\n                type: E_PackageType.DEPENDENCY,\n            },\n            {\n                name: MIGRATE_MONGO_PACKAGE_NAME,\n                type: E_PackageType.DEPENDENCY,\n            },\n        ],\n        command: `${TSX_CLI} ${MIGRATE_MONGO_CLI} up -f ${PATH.MIGRATE_MONGO_CONFIG}`,\n    }),\n    mongoMigrateDown: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: TSX_CLI,\n                type: E_PackageType.DEPENDENCY,\n            },\n            {\n                name: MIGRATE_MONGO_PACKAGE_NAME,\n                type: E_PackageType.DEPENDENCY,\n            },\n        ],\n        command: `${TSX_CLI} ${MIGRATE_MONGO_CLI} down -f ${PATH.MIGRATE_MONGO_CONFIG}`,\n    }),\n    commitLint: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: COMMIT_LINT_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n            {\n                name: COMMIT_LINT_CONVENTIONAL_CONFIG_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n        ],\n        command: `${COMMIT_LINT_CLI} --edit ${PATH.GIT_COMMIT_MSG} --config ${PATH.COMMITLINT_CONFIG}`,\n    }),\n    lintStaged: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: LINT_STAGED_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n        ],\n        command: `${LINT_STAGED_CLI} --config ${PATH.LINT_STAGED_CONFIG}`,\n    }),\n    configureGitHook: buildCommand({\n        type: E_CommandType.STRING,\n        command: `${GIT_CLI} config core.hooksPath ${PATH.GIT_HOOK}`,\n    }),\n    build: buildCommand({\n        type: E_CommandType.STRING,\n        command: `${PNPM_CLI} run --if-present build`,\n    }),\n    pnpmInstallStandard: buildCommand({\n        type: E_CommandType.STRING,\n        command: `${PNPM_CLI} install --ignore-scripts`,\n    }),\n    pnpmInstallLegacy: buildCommand({\n        type: E_CommandType.STRING,\n        command: `${PNPM_CLI} install --ignore-scripts --legacy-peer-deps`,\n    }),\n    pnpmInstallForce: buildCommand({\n        type: E_CommandType.STRING,\n        command: `${PNPM_CLI} install --ignore-scripts --force`,\n    }),\n    pnpmPruneStore: buildCommand({\n        type: E_CommandType.STRING,\n        command: `${PNPM_CLI} store prune`,\n    }),\n    pnpmCleanCache: buildCommand({\n        type: E_CommandType.STRING,\n        command: `${PNPM_CLI} cache delete`,\n    }),\n    storybookDev: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: STORYBOOK_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n        ],\n        command: `${STORYBOOK_CLI} dev`,\n    }),\n    storybookBuild: buildCommand({\n        type: E_CommandType.CLI,\n        packages: [\n            {\n                name: STORYBOOK_PACKAGE_NAME,\n                type: E_PackageType.DEV_DEPENDENCY,\n            },\n        ],\n        command: `${STORYBOOK_CLI} build`,\n    }),\n};\n"],"mappings":"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"}

package/dist/node/storage/storage.util.d.ts

@@ -1,9 +1,25 @@
+export interface I_StorageDriver {
+    init: (options?: unknown) => Promise<void>;
+    clear: () => Promise<void>;
+    getItem: <T>(key: string) => Promise<T | null>;
+    keys: () => Promise<string[]>;
+    removeItem: (key: string) => Promise<void>;
+    setItem: <T>(key: string, value: T) => Promise<T>;
+}
 /**
  * Persistent storage utility object for data persistence across application sessions.
  * Uses a filesystem-backed driver that stores JSON-encoded values on disk,
  * with automatic initialization and error handling.
  */
 export declare const storage: {
+    /**
+     * Initializes the utility with a custom storage driver instead of the default filesystem driver.
+     * This allows swapping to Redis, Memory, or cloud-based drivers.
+     * Must optionally be called before the first read/write operation.
+     *
+     * @param driver - The custom storage driver object that adheres to I_StorageDriver.
+     */
+    initDriver(driver: I_StorageDriver): Promise<void>;
     /**
      * Retrieves a value from persistent storage by key.
      * This method fetches data that was previously stored using the set method.
@@ -20,9 +36,13 @@ export declare const storage: {
      *
      * @param key - The unique identifier for the value to store.
      * @param value - The data to store (will be automatically serialized).
+     * @param options - Optional settings, such as `ttlMs` for setting an expiration on the key.
+     * @param options.ttlMs - The time-to-live in milliseconds.
      * @returns A promise that resolves when the storage operation is complete.
      */
-    set<T = unknown>(key: string, value: T): Promise<void>;
+    set<T = unknown>(key: string, value: T, options?: {
+        ttlMs?: number;
+    }): Promise<void>;
     /**
      * Removes a value from persistent storage by key.
      * This method permanently deletes the stored data associated with the specified key.
@@ -31,6 +51,21 @@ export declare const storage: {
      * @returns A promise that resolves when the removal operation is complete.
      */
     remove(key: string): Promise<void>;
+    /**
+     * Checks if a key exists in persistent storage.
+     * This method efficiently checks for key existence and respects TTL parsing.
+     * Returns false if the key exists but has expired.
+     *
+     * @param key - The unique identifier to check.
+     * @returns A promise that resolves to true if the key exists and has not expired.
+     * @since 3.13.0
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Clears all entries from storage atomically.
+     * @returns A promise that resolves when the clearing operation is complete.
+     */
+    clear(): Promise<void>;
     /**
      * Retrieves all storage keys.
      * This method returns an array of all keys that currently have stored values.
@@ -48,10 +83,24 @@ export declare const storage: {
      * @returns A promise that resolves to a formatted log link string or null if an error occurs.
      */
     getLogLink(key: string): Promise<string | null>;
+    /**
+     * Retrieves a value from persistent storage, or creates and stores it if it doesn't exist.
+     * This method combines check, creation, and storage into a single convenient operation.
+     *
+     * @param key - The unique identifier for the value.
+     * @param factory - A function (sync or async) that generates the value if it's missing or expired.
+     * @param options - Optional storage options.
+     * @param options.ttlMs - The time-to-live in milliseconds.
+     * @returns A promise that resolves to the retrieved or newly created value.
+     */
+    getOrSet<T = unknown>(key: string, factory: () => T | Promise<T>, options?: {
+        ttlMs?: number;
+    }): Promise<T>;
 };
 /**
  * Resets all module-level singleton state used by the storage module.
  * Intended for use in tests to ensure isolation between test cases.
  * Do NOT call this in production code.
+ * @since 3.13.0
  */
 export declare function resetStorageForTesting(): void;

package/dist/node/storage/storage.util.js

@@ -1,58 +1,59 @@
-import { getEnv as e } from "../../config/env/env.util.js";
-import { catchError as t, log as n } from "../log/log.util.js";
-import { STORAGE_KEY_EXTENSION as r } from "./storage.constant.js";
-import i from "node:path";
-import a from "node:fs/promises";
+import { createTtlEnvelope as e, isExpiredEnvelope as t, isTtlEnvelope as n } from "../../util/storage/storage-envelope.js";
+import { getEnv as r } from "../../config/env/env.util.js";
+import { catchError as i, log as a } from "../log/log.util.js";
+import { STORAGE_KEY_EXTENSION as o } from "./storage.constant.js";
+import s from "node:path";
+import c from "node:fs/promises";
 //#region src/node/storage/storage.util.ts
-var o = 200, s = { baseDir: "" };
-function c(e) {
-	if (e.length > o) throw RangeError(`Storage key exceeds maximum length of ${o} characters`);
-	return `${encodeURIComponent(e)}${r}`;
+var l = 200, u = { baseDir: "" };
+function d(e) {
+	if (e.length > l) throw RangeError(`Storage key exceeds maximum length of ${l} characters`);
+	return `${encodeURIComponent(e)}${o}`;
 }
-function l(e) {
-	return decodeURIComponent(e.slice(0, -r.length));
+function f(e) {
+	return decodeURIComponent(e.slice(0, -o.length));
 }
-function u(e, t) {
-	return i.join(t, c(e));
+function p(e, t) {
+	return s.join(t, d(e));
 }
-var d = {
-	async init(t) {
+var m = {
+	async init(e) {
 		try {
-			typeof t == "string" && t.length > 0 ? s.baseDir = t : s.baseDir = e().CYBERSKILL_STORAGE_DIRECTORY, await a.mkdir(s.baseDir, { recursive: !0 });
+			typeof e == "string" && e.length > 0 ? u.baseDir = e : u.baseDir = r().CYBERSKILL_STORAGE_DIRECTORY, await c.mkdir(u.baseDir, { recursive: !0 });
 		} catch (e) {
-			throw n.error("[Storage:init]", e), e;
+			throw a.error("[Storage:init]", e), e;
 		}
 	},
 	async clear() {
-		let { baseDir: e } = s;
+		let { baseDir: e } = u;
 		if (!e) return;
 		let t = `${e}.trash.${Date.now()}`, n = `${e}.fresh.${Date.now()}`;
 		try {
-			await a.mkdir(n, { recursive: !0 });
+			await c.mkdir(n, { recursive: !0 });
 			try {
-				await a.rename(e, t);
+				await c.rename(e, t);
 			} catch {}
-			await a.rename(n, e), a.rm(t, {
+			await c.rename(n, e), c.rm(t, {
 				recursive: !0,
 				force: !0
 			}).catch(() => {});
 		} catch {
-			await a.rm(e, {
+			await c.rm(e, {
 				recursive: !0,
 				force: !0
-			}), await a.mkdir(e, { recursive: !0 }), a.rm(n, {
+			}), await c.mkdir(e, { recursive: !0 }), c.rm(n, {
 				recursive: !0,
 				force: !0
-			}).catch(() => {}), a.rm(t, {
+			}).catch(() => {}), c.rm(t, {
 				recursive: !0,
 				force: !0
 			}).catch(() => {});
 		}
 	},
 	async getItem(e) {
-		let { baseDir: t } = s, n = u(e, t);
+		let { baseDir: t } = u, n = p(e, t);
 		try {
-			let e = await a.readFile(n, "utf8");
+			let e = await c.readFile(n, "utf8");
 			return JSON.parse(e);
 		} catch (e) {
 			if (e.code === "ENOENT") return null;
@@ -60,70 +61,94 @@ var d = {
 		}
 	},
 	async keys() {
-		let { baseDir: e } = s;
+		let { baseDir: e } = u;
 		try {
-			return (await a.readdir(e)).filter((e) => e.endsWith(r)).map(l);
+			return (await c.readdir(e)).filter((e) => e.endsWith(o)).map(f);
 		} catch (e) {
 			if (e.code === "ENOENT") return [];
 			throw e;
 		}
 	},
 	async removeItem(e) {
-		let { baseDir: t } = s, n = u(e, t);
-		await a.rm(n, { force: !0 });
+		let { baseDir: t } = u, n = p(e, t);
+		await c.rm(n, { force: !0 });
 	},
 	async setItem(e, t) {
-		let { baseDir: n } = s, r = u(e, n);
-		return await a.mkdir(n, { recursive: !0 }), await a.writeFile(r, JSON.stringify(t), "utf8"), t;
+		let { baseDir: n } = u, r = p(e, n);
+		return await c.mkdir(n, { recursive: !0 }), await c.writeFile(r, JSON.stringify(t), "utf8"), t;
 	}
-}, f = null;
-async function p() {
-	return f ? (await f, d) : (f = d.init().catch((e) => {
-		throw f = null, e;
-	}), await f, d);
+}, h = null, g = m;
+async function _() {
+	return h ? (await h, g) : (h = g.init().catch((e) => {
+		throw h = null, e;
+	}), await h, g);
 }
-var m = {
+var v = {
+	async initDriver(e) {
+		g = e, h = null, await _();
+	},
 	async get(e) {
 		try {
-			return await (await p()).getItem(e) ?? null;
+			let r = await _(), i = await r.getItem(e);
+			return i === null ? null : n(i) ? t(i) ? (r.removeItem(e).catch(() => {}), null) : i.value : i;
 		} catch (e) {
-			return t(e, { returnValue: null });
+			return i(e, { returnValue: null });
 		}
 	},
-	async set(e, n) {
+	async set(t, n, r) {
 		try {
-			await (await p()).setItem(e, n);
+			let i = await _(), a = n;
+			r?.ttlMs && (a = e(n, r.ttlMs)), await i.setItem(t, a);
 		} catch (e) {
-			throw t(e), e;
+			throw i(e), e;
 		}
 	},
 	async remove(e) {
 		try {
-			await (await p()).removeItem(e);
+			await (await _()).removeItem(e);
+		} catch (e) {
+			i(e);
+		}
+	},
+	async has(e) {
+		try {
+			let r = await _(), i = await r.getItem(e);
+			return i === null ? !1 : n(i) && t(i) ? (r.removeItem(e).catch(() => {}), !1) : !0;
 		} catch (e) {
-			t(e);
+			return i(e, { returnValue: !1 });
+		}
+	},
+	async clear() {
+		try {
+			await (await _()).clear();
+		} catch (e) {
+			i(e);
 		}
 	},
 	async keys() {
 		try {
-			let e = await (await p()).keys();
-			return Array.isArray(e) ? e : (n.warn("[Storage:keys] Invalid keys response:", e), []);
+			let e = await (await _()).keys();
+			return Array.isArray(e) ? e : (a.warn("[Storage:keys] Invalid keys response:", e), []);
 		} catch (e) {
-			return t(e, { returnValue: [] });
+			return i(e, { returnValue: [] });
 		}
 	},
-	async getLogLink(n) {
+	async getLogLink(e) {
 		try {
-			return `${i.join(e().CYBERSKILL_STORAGE_DIRECTORY, c(n))} (key: ${n})`;
+			return `${s.join(r().CYBERSKILL_STORAGE_DIRECTORY, d(e))} (key: ${e})`;
 		} catch (e) {
-			return t(e, { returnValue: null });
+			return i(e, { returnValue: null });
 		}
+	},
+	async getOrSet(e, t, n) {
+		let r = await this.get(e);
+		return r === null && (r = await t(), await this.set(e, r, n)), r;
 	}
 };
-function h() {
-	f = null, s.baseDir = "";
+function y() {
+	h = null, g = m, u.baseDir = "";
 }
 //#endregion
-export { h as resetStorageForTesting, m as storage };
+export { y as resetStorageForTesting, v as storage };
 
 //# sourceMappingURL=storage.util.js.map

package/dist/node/storage/storage.util.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.util.js","names":[],"sources":["../../../src/node/storage/storage.util.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\n\nimport { getEnv } from '#config/env/index.js';\n\nimport { catchError, log } from '../log/index.js';\nimport { STORAGE_KEY_EXTENSION } from './storage.constant.js';\n\nconst MAX_KEY_LENGTH = 200;\n\ninterface NodeFsDriverState {\n    baseDir: string;\n}\n\nconst nodeFsDriverState: NodeFsDriverState = {\n    baseDir: '',\n};\n\n/**\n * Encodes a storage key into a filename-safe string.\n * Validates key length before encoding to prevent OS filename limits.\n *\n * @throws {RangeError} When key exceeds maximum length.\n */\nfunction encodeKey(key: string): string {\n    if (key.length > MAX_KEY_LENGTH) {\n        throw new RangeError(`Storage key exceeds maximum length of ${MAX_KEY_LENGTH} characters`);\n    }\n    return `${encodeURIComponent(key)}${STORAGE_KEY_EXTENSION}`;\n}\n\n/**\n * Decodes a filename-safe key back to the original storage key.\n */\nfunction decodeKey(fileName: string): string {\n    return decodeURIComponent(fileName.slice(0, -STORAGE_KEY_EXTENSION.length));\n}\n\n/**\n * Maps a storage key to an absolute file path inside the storage directory.\n */\nfunction getFilePath(key: string, baseDir: string): string {\n    return path.join(baseDir, encodeKey(key));\n}\n\n/**\n * Filesystem-backed storage driver that stores JSON-encoded values on disk.\n * Directly implements all storage operations without any external dependencies.\n * storage operations without the unnecessary browser-oriented dependency.\n */\nconst fsDriver = {\n    /** Ensures the storage directory exists. */\n    async init(baseDir?: string) {\n        try {\n            if (typeof baseDir === 'string' && baseDir.length > 0) {\n                nodeFsDriverState.baseDir = baseDir;\n            }\n            else {\n                nodeFsDriverState.baseDir = getEnv().CYBERSKILL_STORAGE_DIRECTORY;\n            }\n\n            await fs.mkdir(nodeFsDriverState.baseDir, { recursive: true });\n        }\n        catch (error) {\n            log.error('[Storage:init]', error);\n            throw error;\n        }\n    },\n    /** Deletes all stored entries atomically by swapping to a fresh directory. */\n    async clear() {\n        const { baseDir } = nodeFsDriverState;\n\n        if (!baseDir) {\n            return;\n        }\n\n        // Atomic swap: create a fresh temp dir, rename old→trash, rename fresh→baseDir, remove trash\n        const trashDir = `${baseDir}.trash.${Date.now()}`;\n        const freshDir = `${baseDir}.fresh.${Date.now()}`;\n\n        try {\n            await fs.mkdir(freshDir, { recursive: true });\n            // Try atomic rename swap\n            try {\n                await fs.rename(baseDir, trashDir);\n            }\n            catch {\n                // baseDir might not exist yet; no-op\n            }\n            await fs.rename(freshDir, baseDir);\n            // Clean up trash in the background (non-blocking)\n            fs.rm(trashDir, { recursive: true, force: true }).catch(() => {});\n        }\n        catch {\n            // Fallback: non-atomic clear (e.g., cross-device rename)\n            await fs.rm(baseDir, { recursive: true, force: true });\n            await fs.mkdir(baseDir, { recursive: true });\n            // Clean up any leftover temp dirs\n            fs.rm(freshDir, { recursive: true, force: true }).catch(() => {});\n            fs.rm(trashDir, { recursive: true, force: true }).catch(() => {});\n        }\n    },\n    /** Reads and parses a stored value; returns null when the file is missing. */\n    async getItem<T>(key: string): Promise<T | null> {\n        const { baseDir } = nodeFsDriverState;\n        const filePath = getFilePath(key, baseDir);\n\n        try {\n            const content = await fs.readFile(filePath, 'utf8');\n\n            return JSON.parse(content) as T;\n        }\n        catch (error) {\n            if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n                return null;\n            }\n            throw error;\n        }\n    },\n    /** Lists all stored keys. */\n    async keys(): Promise<string[]> {\n        const { baseDir } = nodeFsDriverState;\n\n        try {\n            const files = await fs.readdir(baseDir);\n\n            return files\n                .filter(file => file.endsWith(STORAGE_KEY_EXTENSION))\n                .map(decodeKey);\n        }\n        catch (error) {\n            if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n                return [];\n            }\n            throw error;\n        }\n    },\n    /** Removes a stored value for the given key. */\n    async removeItem(key: string): Promise<void> {\n        const { baseDir } = nodeFsDriverState;\n        const filePath = getFilePath(key, baseDir);\n\n        await fs.rm(filePath, { force: true });\n    },\n    /** Stores a value as JSON on disk. */\n    async setItem<T>(key: string, value: T): Promise<T> {\n        const { baseDir } = nodeFsDriverState;\n        const filePath = getFilePath(key, baseDir);\n\n        await fs.mkdir(baseDir, { recursive: true });\n        await fs.writeFile(filePath, JSON.stringify(value), 'utf8');\n\n        return value;\n    },\n};\n\nlet initPromise: Promise<void> | null = null;\n\n/**\n * Initializes the filesystem storage driver (singleton, idempotent).\n * Ensures the storage directory exists before any read/write operations.\n */\nasync function ensureDriverReady(): Promise<typeof fsDriver> {\n    if (initPromise) {\n        await initPromise;\n        return fsDriver;\n    }\n\n    initPromise = fsDriver.init().catch((error) => {\n        initPromise = null;\n        throw error;\n    });\n\n    await initPromise;\n\n    return fsDriver;\n}\n\n/**\n * Persistent storage utility object for data persistence across application sessions.\n * Uses a filesystem-backed driver that stores JSON-encoded values on disk,\n * with automatic initialization and error handling.\n */\nexport const storage = {\n    /**\n     * Retrieves a value from persistent storage by key.\n     * This method fetches data that was previously stored using the set method.\n     * Returns null if the key doesn't exist or if an error occurs.\n     *\n     * @param key - The unique identifier for the stored value.\n     * @returns A promise that resolves to the stored value or null if not found.\n     */\n    async get<T = unknown>(key: string): Promise<T | null> {\n        try {\n            const driver = await ensureDriverReady();\n            const result = await driver.getItem<T>(key);\n\n            return result ?? null;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: null });\n        }\n    },\n    /**\n     * Stores a value in persistent storage with a unique key.\n     * This method saves data that can be retrieved later using the get method.\n     * The data is automatically serialized and stored in the configured storage directory.\n     *\n     * @param key - The unique identifier for the value to store.\n     * @param value - The data to store (will be automatically serialized).\n     * @returns A promise that resolves when the storage operation is complete.\n     */\n    async set<T = unknown>(key: string, value: T): Promise<void> {\n        try {\n            const driver = await ensureDriverReady();\n\n            await driver.setItem(key, value);\n        }\n        catch (error) {\n            catchError(error);\n            throw error;\n        }\n    },\n    /**\n     * Removes a value from persistent storage by key.\n     * This method permanently deletes the stored data associated with the specified key.\n     *\n     * @param key - The unique identifier of the value to remove.\n     * @returns A promise that resolves when the removal operation is complete.\n     */\n    async remove(key: string): Promise<void> {\n        try {\n            const driver = await ensureDriverReady();\n\n            await driver.removeItem(key);\n        }\n        catch (error) {\n            catchError(error);\n        }\n    },\n    /**\n     * Retrieves all storage keys.\n     * This method returns an array of all keys that currently have stored values.\n     * Returns an empty array if no keys exist or if an error occurs.\n     *\n     * @returns A promise that resolves to an array of storage keys.\n     */\n    async keys(): Promise<string[]> {\n        try {\n            const driver = await ensureDriverReady();\n            const keys = await driver.keys();\n\n            if (!Array.isArray(keys)) {\n                log.warn(`[Storage:keys] Invalid keys response:`, keys);\n                return [];\n            }\n\n            return keys;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: [] });\n        }\n    },\n    /**\n     * Gets a human-readable log link for a storage key.\n     * This method provides a formatted string that shows the storage directory path\n     * and the key name for debugging and manual inspection purposes.\n     *\n     * @param key - The storage key to generate a log link for.\n     * @returns A promise that resolves to a formatted log link string or null if an error occurs.\n     */\n    async getLogLink(key: string): Promise<string | null> {\n        try {\n            const storagePath = path.join(getEnv().CYBERSKILL_STORAGE_DIRECTORY, encodeKey(key));\n\n            return `${storagePath} (key: ${key})`;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: null });\n        }\n    },\n\n};\n\n/**\n * Resets all module-level singleton state used by the storage module.\n * Intended for use in tests to ensure isolation between test cases.\n * Do NOT call this in production code.\n */\nexport function resetStorageForTesting(): void {\n    initPromise = null;\n    nodeFsDriverState.baseDir = '';\n}\n"],"mappings":"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"}
+{"version":3,"file":"storage.util.js","names":[],"sources":["../../../src/node/storage/storage.util.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\n\nimport { getEnv } from '#config/env/index.js';\n\nimport { createTtlEnvelope, isExpiredEnvelope, isTtlEnvelope } from '../../util/storage/storage-envelope.js';\nimport { catchError, log } from '../log/index.js';\nimport { STORAGE_KEY_EXTENSION } from './storage.constant.js';\n\nconst MAX_KEY_LENGTH = 200;\n\ninterface NodeFsDriverState {\n    baseDir: string;\n}\n\nexport interface I_StorageDriver {\n    init: (options?: unknown) => Promise<void>;\n    clear: () => Promise<void>;\n    getItem: <T>(key: string) => Promise<T | null>;\n    keys: () => Promise<string[]>;\n    removeItem: (key: string) => Promise<void>;\n    setItem: <T>(key: string, value: T) => Promise<T>;\n}\n\nconst nodeFsDriverState: NodeFsDriverState = {\n    baseDir: '',\n};\n\n/**\n * Encodes a storage key into a filename-safe string.\n * Validates key length before encoding to prevent OS filename limits.\n *\n * @throws {RangeError} When key exceeds maximum length.\n */\nfunction encodeKey(key: string): string {\n    if (key.length > MAX_KEY_LENGTH) {\n        throw new RangeError(`Storage key exceeds maximum length of ${MAX_KEY_LENGTH} characters`);\n    }\n    return `${encodeURIComponent(key)}${STORAGE_KEY_EXTENSION}`;\n}\n\n/**\n * Decodes a filename-safe key back to the original storage key.\n */\nfunction decodeKey(fileName: string): string {\n    return decodeURIComponent(fileName.slice(0, -STORAGE_KEY_EXTENSION.length));\n}\n\n/**\n * Maps a storage key to an absolute file path inside the storage directory.\n */\nfunction getFilePath(key: string, baseDir: string): string {\n    return path.join(baseDir, encodeKey(key));\n}\n\n/**\n * Filesystem-backed storage driver that stores JSON-encoded values on disk.\n * Directly implements all storage operations without any external dependencies.\n */\nconst fsDriver: I_StorageDriver = {\n    /** Ensures the storage directory exists. */\n    async init(baseDir?: unknown) {\n        try {\n            if (typeof baseDir === 'string' && baseDir.length > 0) {\n                nodeFsDriverState.baseDir = baseDir;\n            }\n            else {\n                nodeFsDriverState.baseDir = getEnv().CYBERSKILL_STORAGE_DIRECTORY;\n            }\n\n            await fs.mkdir(nodeFsDriverState.baseDir, { recursive: true });\n        }\n        catch (error) {\n            log.error('[Storage:init]', error);\n            throw error;\n        }\n    },\n    /** Deletes all stored entries atomically by swapping to a fresh directory. */\n    async clear() {\n        const { baseDir } = nodeFsDriverState;\n\n        if (!baseDir) {\n            return;\n        }\n\n        // Atomic swap: create a fresh temp dir, rename old→trash, rename fresh→baseDir, remove trash\n        const trashDir = `${baseDir}.trash.${Date.now()}`;\n        const freshDir = `${baseDir}.fresh.${Date.now()}`;\n\n        try {\n            await fs.mkdir(freshDir, { recursive: true });\n            // Try atomic rename swap\n            try {\n                await fs.rename(baseDir, trashDir);\n            }\n            catch {\n                // baseDir might not exist yet; no-op\n            }\n            await fs.rename(freshDir, baseDir);\n            // Clean up trash in the background (non-blocking)\n            fs.rm(trashDir, { recursive: true, force: true }).catch(() => { });\n        }\n        catch {\n            // Fallback: non-atomic clear (e.g., cross-device rename)\n            await fs.rm(baseDir, { recursive: true, force: true });\n            await fs.mkdir(baseDir, { recursive: true });\n            // Clean up any leftover temp dirs\n            fs.rm(freshDir, { recursive: true, force: true }).catch(() => { });\n            fs.rm(trashDir, { recursive: true, force: true }).catch(() => { });\n        }\n    },\n    /** Reads and parses a stored value; returns null when the file is missing. */\n    async getItem<T>(key: string): Promise<T | null> {\n        const { baseDir } = nodeFsDriverState;\n        const filePath = getFilePath(key, baseDir);\n\n        try {\n            const content = await fs.readFile(filePath, 'utf8');\n\n            return JSON.parse(content) as T;\n        }\n        catch (error) {\n            if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n                return null;\n            }\n            throw error;\n        }\n    },\n    /** Lists all stored keys. */\n    async keys(): Promise<string[]> {\n        const { baseDir } = nodeFsDriverState;\n\n        try {\n            const files = await fs.readdir(baseDir);\n\n            return files\n                .filter(file => file.endsWith(STORAGE_KEY_EXTENSION))\n                .map(decodeKey);\n        }\n        catch (error) {\n            if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n                return [];\n            }\n            throw error;\n        }\n    },\n    /** Removes a stored value for the given key. */\n    async removeItem(key: string): Promise<void> {\n        const { baseDir } = nodeFsDriverState;\n        const filePath = getFilePath(key, baseDir);\n\n        await fs.rm(filePath, { force: true });\n    },\n    /** Stores a value as JSON on disk. */\n    async setItem<T>(key: string, value: T): Promise<T> {\n        const { baseDir } = nodeFsDriverState;\n        const filePath = getFilePath(key, baseDir);\n\n        await fs.mkdir(baseDir, { recursive: true });\n        await fs.writeFile(filePath, JSON.stringify(value), 'utf8');\n\n        return value;\n    },\n};\n\nlet initPromise: Promise<void> | null = null;\nlet activeDriver: I_StorageDriver = fsDriver;\n\n/**\n * Initializes the storage driver (singleton, idempotent).\n */\nasync function ensureDriverReady(): Promise<I_StorageDriver> {\n    if (initPromise) {\n        await initPromise;\n        return activeDriver;\n    }\n\n    initPromise = activeDriver.init().catch((error) => {\n        initPromise = null;\n        throw error;\n    });\n\n    await initPromise;\n\n    return activeDriver;\n}\n\n/**\n * Persistent storage utility object for data persistence across application sessions.\n * Uses a filesystem-backed driver that stores JSON-encoded values on disk,\n * with automatic initialization and error handling.\n */\nexport const storage = {\n    /**\n     * Initializes the utility with a custom storage driver instead of the default filesystem driver.\n     * This allows swapping to Redis, Memory, or cloud-based drivers.\n     * Must optionally be called before the first read/write operation.\n     *\n     * @param driver - The custom storage driver object that adheres to I_StorageDriver.\n     */\n    async initDriver(driver: I_StorageDriver): Promise<void> {\n        activeDriver = driver;\n        initPromise = null;\n        await ensureDriverReady();\n    },\n    /**\n     * Retrieves a value from persistent storage by key.\n     * This method fetches data that was previously stored using the set method.\n     * Returns null if the key doesn't exist or if an error occurs.\n     *\n     * @param key - The unique identifier for the stored value.\n     * @returns A promise that resolves to the stored value or null if not found.\n     */\n    async get<T = unknown>(key: string): Promise<T | null> {\n        try {\n            const driver = await ensureDriverReady();\n            const result = await driver.getItem<unknown>(key);\n\n            if (result === null) {\n                return null;\n            }\n\n            if (isTtlEnvelope<T>(result)) {\n                if (isExpiredEnvelope(result)) {\n                    driver.removeItem(key).catch(() => { });\n\n                    return null;\n                }\n\n                return result.value;\n            }\n\n            return result as T;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: null });\n        }\n    },\n    /**\n     * Stores a value in persistent storage with a unique key.\n     * This method saves data that can be retrieved later using the get method.\n     * The data is automatically serialized and stored in the configured storage directory.\n     *\n     * @param key - The unique identifier for the value to store.\n     * @param value - The data to store (will be automatically serialized).\n     * @param options - Optional settings, such as `ttlMs` for setting an expiration on the key.\n     * @param options.ttlMs - The time-to-live in milliseconds.\n     * @returns A promise that resolves when the storage operation is complete.\n     */\n    async set<T = unknown>(key: string, value: T, options?: { ttlMs?: number }): Promise<void> {\n        try {\n            const driver = await ensureDriverReady();\n\n            let payloadToStore: unknown = value;\n\n            if (options?.ttlMs) {\n                payloadToStore = createTtlEnvelope(value, options.ttlMs);\n            }\n\n            await driver.setItem(key, payloadToStore);\n        }\n        catch (error) {\n            catchError(error);\n            throw error;\n        }\n    },\n    /**\n     * Removes a value from persistent storage by key.\n     * This method permanently deletes the stored data associated with the specified key.\n     *\n     * @param key - The unique identifier of the value to remove.\n     * @returns A promise that resolves when the removal operation is complete.\n     */\n    async remove(key: string): Promise<void> {\n        try {\n            const driver = await ensureDriverReady();\n\n            await driver.removeItem(key);\n        }\n        catch (error) {\n            catchError(error);\n        }\n    },\n    /**\n     * Checks if a key exists in persistent storage.\n     * This method efficiently checks for key existence and respects TTL parsing.\n     * Returns false if the key exists but has expired.\n     *\n     * @param key - The unique identifier to check.\n     * @returns A promise that resolves to true if the key exists and has not expired.\n     * @since 3.13.0\n     */\n    async has(key: string): Promise<boolean> {\n        try {\n            const driver = await ensureDriverReady();\n            const result = await driver.getItem<unknown>(key);\n\n            if (result === null) {\n                return false;\n            }\n\n            if (isTtlEnvelope<unknown>(result)) {\n                if (isExpiredEnvelope(result)) {\n                    driver.removeItem(key).catch(() => { });\n\n                    return false;\n                }\n            }\n\n            return true;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: false });\n        }\n    },\n    /**\n     * Clears all entries from storage atomically.\n     * @returns A promise that resolves when the clearing operation is complete.\n     */\n    async clear(): Promise<void> {\n        try {\n            const driver = await ensureDriverReady();\n            await driver.clear();\n        }\n        catch (error) {\n            catchError(error);\n        }\n    },\n    /**\n     * Retrieves all storage keys.\n     * This method returns an array of all keys that currently have stored values.\n     * Returns an empty array if no keys exist or if an error occurs.\n     *\n     * @returns A promise that resolves to an array of storage keys.\n     */\n    async keys(): Promise<string[]> {\n        try {\n            const driver = await ensureDriverReady();\n            const keys = await driver.keys();\n\n            if (!Array.isArray(keys)) {\n                log.warn(`[Storage:keys] Invalid keys response:`, keys);\n                return [];\n            }\n\n            return keys;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: [] });\n        }\n    },\n    /**\n     * Gets a human-readable log link for a storage key.\n     * This method provides a formatted string that shows the storage directory path\n     * and the key name for debugging and manual inspection purposes.\n     *\n     * @param key - The storage key to generate a log link for.\n     * @returns A promise that resolves to a formatted log link string or null if an error occurs.\n     */\n    async getLogLink(key: string): Promise<string | null> {\n        try {\n            const storagePath = path.join(getEnv().CYBERSKILL_STORAGE_DIRECTORY, encodeKey(key));\n\n            return `${storagePath} (key: ${key})`;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: null });\n        }\n    },\n    /**\n     * Retrieves a value from persistent storage, or creates and stores it if it doesn't exist.\n     * This method combines check, creation, and storage into a single convenient operation.\n     *\n     * @param key - The unique identifier for the value.\n     * @param factory - A function (sync or async) that generates the value if it's missing or expired.\n     * @param options - Optional storage options.\n     * @param options.ttlMs - The time-to-live in milliseconds.\n     * @returns A promise that resolves to the retrieved or newly created value.\n     */\n    async getOrSet<T = unknown>(key: string, factory: () => T | Promise<T>, options?: { ttlMs?: number }): Promise<T> {\n        let value = await this.get<T>(key);\n\n        if (value === null) {\n            value = await factory();\n            await this.set(key, value, options);\n        }\n\n        return value;\n    },\n};\n\n/**\n * Resets all module-level singleton state used by the storage module.\n * Intended for use in tests to ensure isolation between test cases.\n * Do NOT call this in production code.\n * @since 3.13.0\n */\nexport function resetStorageForTesting(): void {\n    initPromise = null;\n    activeDriver = fsDriver;\n    nodeFsDriverState.baseDir = '';\n}\n"],"mappings":";;;;;;;AASA,IAAM,IAAiB,KAejB,IAAuC,EACzC,SAAS,IACZ;AAQD,SAAS,EAAU,GAAqB;AACpC,KAAI,EAAI,SAAS,EACb,OAAU,WAAW,yCAAyC,EAAe,aAAa;AAE9F,QAAO,GAAG,mBAAmB,EAAI,GAAG;;AAMxC,SAAS,EAAU,GAA0B;AACzC,QAAO,mBAAmB,EAAS,MAAM,GAAG,CAAC,EAAsB,OAAO,CAAC;;AAM/E,SAAS,EAAY,GAAa,GAAyB;AACvD,QAAO,EAAK,KAAK,GAAS,EAAU,EAAI,CAAC;;AAO7C,IAAM,IAA4B;CAE9B,MAAM,KAAK,GAAmB;AAC1B,MAAI;AAQA,GAPI,OAAO,KAAY,YAAY,EAAQ,SAAS,IAChD,EAAkB,UAAU,IAG5B,EAAkB,UAAU,GAAQ,CAAC,8BAGzC,MAAM,EAAG,MAAM,EAAkB,SAAS,EAAE,WAAW,IAAM,CAAC;WAE3D,GAAO;AAEV,SADA,EAAI,MAAM,kBAAkB,EAAM,EAC5B;;;CAId,MAAM,QAAQ;EACV,IAAM,EAAE,eAAY;AAEpB,MAAI,CAAC,EACD;EAIJ,IAAM,IAAW,GAAG,EAAQ,SAAS,KAAK,KAAK,IACzC,IAAW,GAAG,EAAQ,SAAS,KAAK,KAAK;AAE/C,MAAI;AACA,SAAM,EAAG,MAAM,GAAU,EAAE,WAAW,IAAM,CAAC;AAE7C,OAAI;AACA,UAAM,EAAG,OAAO,GAAS,EAAS;WAEhC;AAKN,GAFA,MAAM,EAAG,OAAO,GAAU,EAAQ,EAElC,EAAG,GAAG,GAAU;IAAE,WAAW;IAAM,OAAO;IAAM,CAAC,CAAC,YAAY,GAAI;UAEhE;AAMF,GAJA,MAAM,EAAG,GAAG,GAAS;IAAE,WAAW;IAAM,OAAO;IAAM,CAAC,EACtD,MAAM,EAAG,MAAM,GAAS,EAAE,WAAW,IAAM,CAAC,EAE5C,EAAG,GAAG,GAAU;IAAE,WAAW;IAAM,OAAO;IAAM,CAAC,CAAC,YAAY,GAAI,EAClE,EAAG,GAAG,GAAU;IAAE,WAAW;IAAM,OAAO;IAAM,CAAC,CAAC,YAAY,GAAI;;;CAI1E,MAAM,QAAW,GAAgC;EAC7C,IAAM,EAAE,eAAY,GACd,IAAW,EAAY,GAAK,EAAQ;AAE1C,MAAI;GACA,IAAM,IAAU,MAAM,EAAG,SAAS,GAAU,OAAO;AAEnD,UAAO,KAAK,MAAM,EAAQ;WAEvB,GAAO;AACV,OAAK,EAAgC,SAAS,SAC1C,QAAO;AAEX,SAAM;;;CAId,MAAM,OAA0B;EAC5B,IAAM,EAAE,eAAY;AAEpB,MAAI;AAGA,WAFc,MAAM,EAAG,QAAQ,EAAQ,EAGlC,QAAO,MAAQ,EAAK,SAAS,EAAsB,CAAC,CACpD,IAAI,EAAU;WAEhB,GAAO;AACV,OAAK,EAAgC,SAAS,SAC1C,QAAO,EAAE;AAEb,SAAM;;;CAId,MAAM,WAAW,GAA4B;EACzC,IAAM,EAAE,eAAY,GACd,IAAW,EAAY,GAAK,EAAQ;AAE1C,QAAM,EAAG,GAAG,GAAU,EAAE,OAAO,IAAM,CAAC;;CAG1C,MAAM,QAAW,GAAa,GAAsB;EAChD,IAAM,EAAE,eAAY,GACd,IAAW,EAAY,GAAK,EAAQ;AAK1C,SAHA,MAAM,EAAG,MAAM,GAAS,EAAE,WAAW,IAAM,CAAC,EAC5C,MAAM,EAAG,UAAU,GAAU,KAAK,UAAU,EAAM,EAAE,OAAO,EAEpD;;CAEd,EAEG,IAAoC,MACpC,IAAgC;AAKpC,eAAe,IAA8C;AAazD,QAZI,KACA,MAAM,GACC,MAGX,IAAc,EAAa,MAAM,CAAC,OAAO,MAAU;AAE/C,QADA,IAAc,MACR;GACR,EAEF,MAAM,GAEC;;AAQX,IAAa,IAAU;CAQnB,MAAM,WAAW,GAAwC;AAGrD,EAFA,IAAe,GACf,IAAc,MACd,MAAM,GAAmB;;CAU7B,MAAM,IAAiB,GAAgC;AACnD,MAAI;GACA,IAAM,IAAS,MAAM,GAAmB,EAClC,IAAS,MAAM,EAAO,QAAiB,EAAI;AAgBjD,UAdI,MAAW,OACJ,OAGP,EAAiB,EAAO,GACpB,EAAkB,EAAO,IACzB,EAAO,WAAW,EAAI,CAAC,YAAY,GAAI,EAEhC,QAGJ,EAAO,QAGX;WAEJ,GAAO;AACV,UAAO,EAAW,GAAO,EAAE,aAAa,MAAM,CAAC;;;CAcvD,MAAM,IAAiB,GAAa,GAAU,GAA6C;AACvF,MAAI;GACA,IAAM,IAAS,MAAM,GAAmB,EAEpC,IAA0B;AAM9B,GAJI,GAAS,UACT,IAAiB,EAAkB,GAAO,EAAQ,MAAM,GAG5D,MAAM,EAAO,QAAQ,GAAK,EAAe;WAEtC,GAAO;AAEV,SADA,EAAW,EAAM,EACX;;;CAUd,MAAM,OAAO,GAA4B;AACrC,MAAI;AAGA,UAFe,MAAM,GAAmB,EAE3B,WAAW,EAAI;WAEzB,GAAO;AACV,KAAW,EAAM;;;CAYzB,MAAM,IAAI,GAA+B;AACrC,MAAI;GACA,IAAM,IAAS,MAAM,GAAmB,EAClC,IAAS,MAAM,EAAO,QAAiB,EAAI;AAcjD,UAZI,MAAW,OACJ,KAGP,EAAuB,EAAO,IAC1B,EAAkB,EAAO,IACzB,EAAO,WAAW,EAAI,CAAC,YAAY,GAAI,EAEhC,MAIR;WAEJ,GAAO;AACV,UAAO,EAAW,GAAO,EAAE,aAAa,IAAO,CAAC;;;CAOxD,MAAM,QAAuB;AACzB,MAAI;AAEA,UADe,MAAM,GAAmB,EAC3B,OAAO;WAEjB,GAAO;AACV,KAAW,EAAM;;;CAUzB,MAAM,OAA0B;AAC5B,MAAI;GAEA,IAAM,IAAO,OADE,MAAM,GAAmB,EACd,MAAM;AAOhC,UALK,MAAM,QAAQ,EAAK,GAKjB,KAJH,EAAI,KAAK,yCAAyC,EAAK,EAChD,EAAE;WAKV,GAAO;AACV,UAAO,EAAW,GAAO,EAAE,aAAa,EAAE,EAAE,CAAC;;;CAWrD,MAAM,WAAW,GAAqC;AAClD,MAAI;AAGA,UAAO,GAFa,EAAK,KAAK,GAAQ,CAAC,8BAA8B,EAAU,EAAI,CAAC,CAE9D,SAAS,EAAI;WAEhC,GAAO;AACV,UAAO,EAAW,GAAO,EAAE,aAAa,MAAM,CAAC;;;CAavD,MAAM,SAAsB,GAAa,GAA+B,GAA0C;EAC9G,IAAI,IAAQ,MAAM,KAAK,IAAO,EAAI;AAOlC,SALI,MAAU,SACV,IAAQ,MAAM,GAAS,EACvB,MAAM,KAAK,IAAI,GAAK,GAAO,EAAQ,GAGhC;;CAEd;AAQD,SAAgB,IAA+B;AAG3C,CAFA,IAAc,MACd,IAAe,GACf,EAAkB,UAAU"}

package/dist/node/upload/upload.type.d.ts

@@ -8,6 +8,7 @@ export declare enum E_UploadType {
 export interface I_UploadValidationConfig {
     filename: string;
     fileSize?: number;
+    mimetype?: string;
 }
 export interface I_UploadTypeConfig {
     allowedExtensions: string[];
@@ -23,6 +24,7 @@ export interface I_UploadConfig {
 export interface I_UploadFileData {
     createReadStream: () => NodeJS.ReadableStream;
     filename: string;
+    mimetype?: string;
 }
 export interface I_UploadFile {
     file: I_UploadFileData;

package/dist/node/upload/upload.type.js.map

@@ -1 +1 @@
-{"version":3,"file":"upload.type.js","names":[],"sources":["../../../src/node/upload/upload.type.ts"],"sourcesContent":["export enum E_UploadType {\n    IMAGE = 'IMAGE',\n    VIDEO = 'VIDEO',\n    AUDIO = 'AUDIO',\n    DOCUMENT = 'DOCUMENT',\n    OTHER = 'OTHER',\n}\n\nexport interface I_UploadValidationConfig {\n    filename: string;\n    fileSize?: number;\n}\n\nexport interface I_UploadTypeConfig {\n    allowedExtensions: string[];\n    sizeLimit: number;\n}\n\nexport interface I_UploadConfig {\n    [E_UploadType.IMAGE]: I_UploadTypeConfig;\n    [E_UploadType.VIDEO]: I_UploadTypeConfig;\n    [E_UploadType.AUDIO]: I_UploadTypeConfig;\n    [E_UploadType.DOCUMENT]: I_UploadTypeConfig;\n    [E_UploadType.OTHER]: I_UploadTypeConfig;\n}\n\nexport interface I_UploadFileData {\n    createReadStream: () => NodeJS.ReadableStream;\n    filename: string;\n}\n\nexport interface I_UploadFile {\n    file: I_UploadFileData;\n}\n\nexport interface I_UploadOptions {\n    file: Promise<I_UploadFile>;\n    path: string;\n    type: E_UploadType;\n    config?: I_UploadConfig;\n    /** Base directory for path containment validation. When set, the resolved `path` must reside within this directory. */\n    baseDir?: string;\n}\n"],"mappings":";AAAA,IAAY,IAAL,yBAAA,GAAA;QACH,EAAA,QAAA,SACA,EAAA,QAAA,SACA,EAAA,QAAA,SACA,EAAA,WAAA,YACA,EAAA,QAAA;KACH"}
+{"version":3,"file":"upload.type.js","names":[],"sources":["../../../src/node/upload/upload.type.ts"],"sourcesContent":["export enum E_UploadType {\n    IMAGE = 'IMAGE',\n    VIDEO = 'VIDEO',\n    AUDIO = 'AUDIO',\n    DOCUMENT = 'DOCUMENT',\n    OTHER = 'OTHER',\n}\n\nexport interface I_UploadValidationConfig {\n    filename: string;\n    fileSize?: number;\n    mimetype?: string;\n}\n\nexport interface I_UploadTypeConfig {\n    allowedExtensions: string[];\n    sizeLimit: number;\n}\n\nexport interface I_UploadConfig {\n    [E_UploadType.IMAGE]: I_UploadTypeConfig;\n    [E_UploadType.VIDEO]: I_UploadTypeConfig;\n    [E_UploadType.AUDIO]: I_UploadTypeConfig;\n    [E_UploadType.DOCUMENT]: I_UploadTypeConfig;\n    [E_UploadType.OTHER]: I_UploadTypeConfig;\n}\n\nexport interface I_UploadFileData {\n    createReadStream: () => NodeJS.ReadableStream;\n    filename: string;\n    mimetype?: string;\n}\n\nexport interface I_UploadFile {\n    file: I_UploadFileData;\n}\n\nexport interface I_UploadOptions {\n    file: Promise<I_UploadFile>;\n    path: string;\n    type: E_UploadType;\n    config?: I_UploadConfig;\n    /** Base directory for path containment validation. When set, the resolved `path` must reside within this directory. */\n    baseDir?: string;\n}\n"],"mappings":";AAAA,IAAY,IAAL,yBAAA,GAAA;QACH,EAAA,QAAA,SACA,EAAA,QAAA,SACA,EAAA,QAAA,SACA,EAAA,WAAA,YACA,EAAA,QAAA;KACH"}

package/dist/node/upload/upload.util.d.ts

@@ -73,6 +73,7 @@ export declare function validateUpload(config: I_UploadValidationConfig, uploadC
  *
  * @param overrides - Optional configuration overrides to merge with the default configuration.
  * @returns A complete upload configuration object with defaults and any provided overrides.
+ * @since 3.13.0
  */
 export declare function createUploadConfig(overrides?: Partial<I_UploadConfig>): I_UploadConfig;
 /**