@hyperfrontend/project-scope 0.2.1 → 0.2.3

package/_dependencies/@hyperfrontend/logging/index.esm.js

@@ -0,0 +1,186 @@
+import { createError } from '../immutable-api-utils/built-in-copy/error/index.esm.js';
+import { freeze } from '../immutable-api-utils/built-in-copy/object/index.esm.js';
+import { isArray } from '../immutable-api-utils/built-in-copy/array/index.esm.js';
+import '../immutable-api-utils/built-in-copy/map/index.esm.js';
+import { dateNow } from '../immutable-api-utils/built-in-copy/date/index.esm.js';
+import '../immutable-api-utils/built-in-copy/math/index.esm.js';
+import '../immutable-api-utils/built-in-copy/set/index.esm.js';
+import { debug, info, log, warn, error } from '../immutable-api-utils/built-in-copy/console/index.esm.js';
+
+const logLevels = ['none', 'error', 'warn', 'log', 'info', 'debug'];
+const priority = {
+    error: 4,
+    warn: 3,
+    log: 2,
+    info: 1,
+    debug: 0,
+};
+function isValidLogLevel(level) {
+    return logLevels.includes(level);
+}
+function createLogLevelConfig(level = 'error') {
+    if (!isValidLogLevel(level)) {
+        throw createError('Cannot create log level configuration with a valid default log level');
+    }
+    const state = { level };
+    const getLogLevel = () => state.level;
+    const setLogLevel = (level) => {
+        if (!isValidLogLevel(level)) {
+            throw createError(`Cannot set value '${level}' level. Expected levels are ${logLevels}.`);
+        }
+        state.level = level;
+    };
+    const shouldLog = (level) => {
+        if (state.level === 'none' || level === 'none' || !isValidLogLevel(level)) {
+            return false;
+        }
+        return priority[level] >= priority[state.level];
+    };
+    return freeze({
+        getLogLevel,
+        setLogLevel,
+        shouldLog,
+    });
+}
+
+const registeredClasses = [];
+
+const getType = (target) => {
+    if (target === null)
+        return 'null';
+    const nativeDataType = typeof target;
+    if (nativeDataType === 'object') {
+        if (isArray(target))
+            return 'array';
+        for (const registeredClass of registeredClasses) {
+            if (target instanceof registeredClass)
+                return registeredClass.name;
+        }
+    }
+    return nativeDataType;
+};
+
+function createConditionalExecutionFunction(func, conditionFunc) {
+    return function (...args) {
+        if (conditionFunc()) {
+            return func(...args);
+        }
+    };
+}
+
+function createErrorIgnoringFunction(func) {
+    return function (...args) {
+        try {
+            func(...args);
+        }
+        catch {
+        }
+    };
+}
+
+const noop = (...args) => {
+};
+
+function createLogger(error, warn = noop, log = noop, info = noop, debug = noop) {
+    if (notValidLogFn(error)) {
+        throw createError(notFnMsg('error'));
+    }
+    if (notValidLogFn(warn)) {
+        throw createError(notFnMsg('warn'));
+    }
+    if (notValidLogFn(log)) {
+        throw createError(notFnMsg('log'));
+    }
+    if (notValidLogFn(info)) {
+        throw createError(notFnMsg('info'));
+    }
+    if (notValidLogFn(debug)) {
+        throw createError(notFnMsg('debug'));
+    }
+    const { setLogLevel, getLogLevel, shouldLog } = createLogLevelConfig();
+    const wrapLogFn = (fn, level) => {
+        if (fn === noop)
+            return fn;
+        const condition = () => shouldLog(level);
+        return createConditionalExecutionFunction(createErrorIgnoringFunction(fn), condition);
+    };
+    const core = {
+        error: wrapLogFn(error, 'error'),
+        warn: wrapLogFn(warn, 'warn'),
+        log: wrapLogFn(log, 'log'),
+        info: wrapLogFn(info, 'info'),
+        debug: wrapLogFn(debug, 'debug'),
+        setLogLevel,
+        getLogLevel,
+    };
+    return createPrefixedLogger(core, '');
+}
+function createPrefixedLogger(core, fullPrefix) {
+    const tag = fullPrefix ? `[${fullPrefix}]` : '';
+    const prefixed = (fn) => {
+        if (!tag)
+            return fn;
+        return (...data) => fn(tag, ...data);
+    };
+    const instance = freeze({
+        error: prefixed(core.error),
+        warn: prefixed(core.warn),
+        log: prefixed(core.log),
+        info: prefixed(core.info),
+        debug: prefixed(core.debug),
+        setLogLevel: core.setLogLevel,
+        getLogLevel: core.getLogLevel,
+        channel: (childPrefix) => createPrefixedLogger(core, fullPrefix ? `${fullPrefix}:${childPrefix}` : childPrefix),
+        timed(label, fn) {
+            return runTimed(instance, label, fn);
+        },
+        timedAsync(label, fn) {
+            return runTimedAsync(instance, label, fn);
+        },
+    });
+    return instance;
+}
+function runTimed(logger, label, fn) {
+    const start = dateNow();
+    try {
+        const result = fn();
+        const elapsed = dateNow() - start;
+        logger.debug(`${label} completed in ${elapsed}ms`);
+        return result;
+    }
+    catch (error) {
+        const elapsed = dateNow() - start;
+        logger.error(`${label} failed after ${elapsed}ms: ${describeError(error)}`);
+        throw error;
+    }
+}
+async function runTimedAsync(logger, label, fn) {
+    const start = dateNow();
+    try {
+        const result = await fn();
+        const elapsed = dateNow() - start;
+        logger.debug(`${label} completed in ${elapsed}ms`);
+        return result;
+    }
+    catch (error) {
+        const elapsed = dateNow() - start;
+        logger.error(`${label} failed after ${elapsed}ms: ${describeError(error)}`);
+        if (error instanceof Error && error.stack) {
+            logger.debug(`Stack trace:\n${error.stack}`);
+        }
+        throw error;
+    }
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function notValidLogFn(fn) {
+    return getType(fn) !== 'function' && fn !== noop;
+}
+function notFnMsg(label) {
+    return `Cannot create a logger when ${label} is not a function`;
+}
+
+const logger = createLogger(error, warn, log, info, debug);
+
+export { createLogLevelConfig, createLogger, isValidLogLevel, logger };

package/_shared/core/cache/index.cjs.js

@@ -0,0 +1,135 @@
+'use strict';
+
+const index_cjs_js = require('../../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.cjs.js');
+const index_cjs_js$7 = require('../../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/map/index.cjs.js');
+const index_cjs_js$2 = require('../../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.cjs.js');
+
+const cacheRegistry = index_cjs_js.createSet();
+function createCache(options) {
+    const { ttl, maxSize } = options ?? {};
+    const store = index_cjs_js$7.createMap();
+    const insertionOrder = [];
+    /**
+     * Check if an entry is expired.
+     *
+     * @param entry - Cache entry to check
+     * @returns True if entry is expired
+     */
+    function isExpired(entry) {
+        if (ttl === undefined)
+            return false;
+        // eslint-disable-next-line workspace/no-unsafe-builtin-methods -- Date.now() is needed for Jest fake timers compatibility
+        return Date.now() - entry.timestamp > ttl;
+    }
+    /**
+     * Evict oldest entries to make room for new ones.
+     */
+    function evictIfNeeded() {
+        if (maxSize === undefined)
+            return;
+        while (store.size >= maxSize && insertionOrder.length > 0) {
+            const oldestKey = insertionOrder.shift();
+            if (oldestKey !== undefined) {
+                store.delete(oldestKey);
+            }
+        }
+    }
+    /**
+     * Remove key from insertion order tracking.
+     *
+     * @param key - Key to remove from order tracking
+     */
+    function removeFromOrder(key) {
+        const index = insertionOrder.indexOf(key);
+        if (index !== -1) {
+            insertionOrder.splice(index, 1);
+        }
+    }
+    const cache = {
+        get(key) {
+            const entry = store.get(key);
+            if (!entry)
+                return undefined;
+            if (isExpired(entry)) {
+                store.delete(key);
+                removeFromOrder(key);
+                return undefined;
+            }
+            return entry.value;
+        },
+        set(key, value) {
+            if (store.has(key)) {
+                removeFromOrder(key);
+            }
+            else {
+                evictIfNeeded();
+            }
+            // eslint-disable-next-line workspace/no-unsafe-builtin-methods -- Date.now() is needed for Jest fake timers compatibility
+            store.set(key, { value, timestamp: Date.now() });
+            insertionOrder.push(key);
+        },
+        has(key) {
+            const entry = store.get(key);
+            if (!entry)
+                return false;
+            if (isExpired(entry)) {
+                store.delete(key);
+                removeFromOrder(key);
+                return false;
+            }
+            return true;
+        },
+        delete(key) {
+            removeFromOrder(key);
+            return store.delete(key);
+        },
+        clear() {
+            store.clear();
+            insertionOrder.length = 0;
+        },
+        size() {
+            return store.size;
+        },
+        keys() {
+            return [...insertionOrder];
+        },
+    };
+    cacheRegistry.add(cache);
+    return index_cjs_js$2.freeze(cache);
+}
+function clearAllCaches() {
+    for (const cache of cacheRegistry) {
+        cache.clear();
+    }
+}
+function getCacheCount() {
+    return cacheRegistry.size;
+}
+function unregisterCache(cache) {
+    return cacheRegistry.delete(cache);
+}
+function memoize(fn, options) {
+    const cache = createCache(options);
+    const memoized = (key) => {
+        const cached = cache.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = fn(key);
+        cache.set(key, result);
+        return result;
+    };
+    index_cjs_js$2.defineProperty(memoized, 'cache', {
+        value: cache,
+        writable: false,
+        enumerable: true,
+    });
+    return memoized;
+}
+
+exports.cacheRegistry = cacheRegistry;
+exports.createCache = createCache;
+exports.clearAllCaches = clearAllCaches;
+exports.getCacheCount = getCacheCount;
+exports.unregisterCache = unregisterCache;
+exports.memoize = memoize;

package/_shared/core/cache/index.esm.js

@@ -0,0 +1,128 @@
+import { createMap } from '../../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/map/index.esm.js';
+import { keys, freeze, defineProperty } from '../../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.esm.js';
+import { createSet } from '../../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.esm.js';
+
+const cacheRegistry = createSet();
+function createCache(options) {
+    const { ttl, maxSize } = options ?? {};
+    const store = createMap();
+    const insertionOrder = [];
+    /**
+     * Check if an entry is expired.
+     *
+     * @param entry - Cache entry to check
+     * @returns True if entry is expired
+     */
+    function isExpired(entry) {
+        if (ttl === undefined)
+            return false;
+        // eslint-disable-next-line workspace/no-unsafe-builtin-methods -- Date.now() is needed for Jest fake timers compatibility
+        return Date.now() - entry.timestamp > ttl;
+    }
+    /**
+     * Evict oldest entries to make room for new ones.
+     */
+    function evictIfNeeded() {
+        if (maxSize === undefined)
+            return;
+        while (store.size >= maxSize && insertionOrder.length > 0) {
+            const oldestKey = insertionOrder.shift();
+            if (oldestKey !== undefined) {
+                store.delete(oldestKey);
+            }
+        }
+    }
+    /**
+     * Remove key from insertion order tracking.
+     *
+     * @param key - Key to remove from order tracking
+     */
+    function removeFromOrder(key) {
+        const index = insertionOrder.indexOf(key);
+        if (index !== -1) {
+            insertionOrder.splice(index, 1);
+        }
+    }
+    const cache = {
+        get(key) {
+            const entry = store.get(key);
+            if (!entry)
+                return undefined;
+            if (isExpired(entry)) {
+                store.delete(key);
+                removeFromOrder(key);
+                return undefined;
+            }
+            return entry.value;
+        },
+        set(key, value) {
+            if (store.has(key)) {
+                removeFromOrder(key);
+            }
+            else {
+                evictIfNeeded();
+            }
+            // eslint-disable-next-line workspace/no-unsafe-builtin-methods -- Date.now() is needed for Jest fake timers compatibility
+            store.set(key, { value, timestamp: Date.now() });
+            insertionOrder.push(key);
+        },
+        has(key) {
+            const entry = store.get(key);
+            if (!entry)
+                return false;
+            if (isExpired(entry)) {
+                store.delete(key);
+                removeFromOrder(key);
+                return false;
+            }
+            return true;
+        },
+        delete(key) {
+            removeFromOrder(key);
+            return store.delete(key);
+        },
+        clear() {
+            store.clear();
+            insertionOrder.length = 0;
+        },
+        size() {
+            return store.size;
+        },
+        keys() {
+            return [...insertionOrder];
+        },
+    };
+    cacheRegistry.add(cache);
+    return freeze(cache);
+}
+function clearAllCaches() {
+    for (const cache of cacheRegistry) {
+        cache.clear();
+    }
+}
+function getCacheCount() {
+    return cacheRegistry.size;
+}
+function unregisterCache(cache) {
+    return cacheRegistry.delete(cache);
+}
+function memoize(fn, options) {
+    const cache = createCache(options);
+    const memoized = (key) => {
+        const cached = cache.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = fn(key);
+        cache.set(key, result);
+        return result;
+    };
+    defineProperty(memoized, 'cache', {
+        value: cache,
+        writable: false,
+        enumerable: true,
+    });
+    return memoized;
+}
+
+export { cacheRegistry, createCache, clearAllCaches, getCacheCount, unregisterCache, memoize };

package/_shared/core/errors/structured-errors/index.cjs.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const index_cjs_js$6 = require('../../../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
+
+function createStructuredError(message, code, context) {
+    const error = index_cjs_js$6.createError(message);
+    error.code = code;
+    error.context = context ?? {};
+    return error;
+}
+function createConfigError(message, code, context) {
+    return createStructuredError(message, code, { ...context, type: 'config' });
+}
+function createFsError(message, code, context) {
+    return createStructuredError(message, code, { ...context, type: 'fs' });
+}
+function createParseError(message, code, context) {
+    return createStructuredError(message, code, { ...context, type: 'parse' });
+}
+function createValidationError(message, code, context) {
+    return createStructuredError(message, code, { ...context, type: 'validation' });
+}
+
+exports.createStructuredError = createStructuredError;
+exports.createConfigError = createConfigError;
+exports.createFsError = createFsError;
+exports.createParseError = createParseError;
+exports.createValidationError = createValidationError;

package/_shared/core/errors/structured-errors/index.esm.js

@@ -0,0 +1,23 @@
+import { error } from '../../../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/console/index.esm.js';
+import { createError } from '../../../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
+
+function createStructuredError(message, code, context) {
+    const error = createError(message);
+    error.code = code;
+    error.context = context ?? {};
+    return error;
+}
+function createConfigError(message, code, context) {
+    return createStructuredError(message, code, { ...context, type: 'config' });
+}
+function createFsError(message, code, context) {
+    return createStructuredError(message, code, { ...context, type: 'fs' });
+}
+function createParseError(message, code, context) {
+    return createStructuredError(message, code, { ...context, type: 'parse' });
+}
+function createValidationError(message, code, context) {
+    return createStructuredError(message, code, { ...context, type: 'validation' });
+}
+
+export { createStructuredError, createConfigError, createFsError, createParseError, createValidationError };

package/_shared/core/fs/guard/index.cjs.js

@@ -0,0 +1,7 @@
+'use strict';
+
+function isSafePath(filePath) {
+    return !filePath.includes('\u0000');
+}
+
+exports.isSafePath = isSafePath;

package/_shared/core/fs/guard/index.esm.js

@@ -0,0 +1,5 @@
+function isSafePath(filePath) {
+    return !filePath.includes('\u0000');
+}
+
+export { isSafePath };

package/_shared/core/fs/stat/index.cjs.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const { isSafePath } = require('../guard/index.cjs.js');
+const node_fs = require('node:fs');
+
+function getFileStat(filePath, followSymlinks = true) {
+    if (!isSafePath(filePath) || !node_fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const stat = followSymlinks ? node_fs.statSync(filePath) : node_fs.lstatSync(filePath);
+        return {
+            isFile: stat.isFile(),
+            isDirectory: stat.isDirectory(),
+            isSymlink: stat.isSymbolicLink(),
+            size: stat.size,
+            created: stat.birthtime,
+            modified: stat.mtime,
+            accessed: stat.atime,
+            mode: stat.mode,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isFile(filePath) {
+    const stats = getFileStat(filePath);
+    return stats?.isFile ?? false;
+}
+function isDirectory(dirPath) {
+    const stats = getFileStat(dirPath);
+    return stats?.isDirectory ?? false;
+}
+function isSymlink(linkPath) {
+    const stats = getFileStat(linkPath, false);
+    return stats?.isSymlink ?? false;
+}
+function exists(filePath) {
+    return isSafePath(filePath) && node_fs.existsSync(filePath);
+}
+
+exports.getFileStat = getFileStat;
+exports.isFile = isFile;
+exports.isDirectory = isDirectory;
+exports.isSymlink = isSymlink;
+exports.exists = exists;

package/_shared/core/fs/stat/index.esm.js

@@ -0,0 +1,41 @@
+import { isSafePath } from '../guard/index.esm.js';
+import { existsSync, statSync, lstatSync } from 'node:fs';
+
+function getFileStat(filePath, followSymlinks = true) {
+    if (!isSafePath(filePath) || !existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const stat = followSymlinks ? statSync(filePath) : lstatSync(filePath);
+        return {
+            isFile: stat.isFile(),
+            isDirectory: stat.isDirectory(),
+            isSymlink: stat.isSymbolicLink(),
+            size: stat.size,
+            created: stat.birthtime,
+            modified: stat.mtime,
+            accessed: stat.atime,
+            mode: stat.mode,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isFile(filePath) {
+    const stats = getFileStat(filePath);
+    return stats?.isFile ?? false;
+}
+function isDirectory(dirPath) {
+    const stats = getFileStat(dirPath);
+    return stats?.isDirectory ?? false;
+}
+function isSymlink(linkPath) {
+    const stats = getFileStat(linkPath, false);
+    return stats?.isSymlink ?? false;
+}
+function exists(filePath) {
+    return isSafePath(filePath) && existsSync(filePath);
+}
+
+export { getFileStat, isFile, isDirectory, isSymlink, exists };

package/_shared/core/path/confine/index.cjs.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const { removeTrailingSlash, normalizePath } = require('../normalize/index.cjs.js');
+const node_path = require('node:path');
+const node_fs = require('node:fs');
+
+function contains(root, path) {
+    const base = removeTrailingSlash(root);
+    return path === base || path.startsWith(`${base}/`);
+}
+function isWithinRoot(root, candidate) {
+    if (!contains(normalizePath(node_path.resolve(root)), normalizePath(node_path.resolve(candidate)))) {
+        return false;
+    }
+    if (!node_fs.existsSync(candidate)) {
+        return true;
+    }
+    return contains(normalizePath(node_fs.realpathSync(root)), normalizePath(node_fs.realpathSync(candidate)));
+}
+
+exports.contains = contains;
+exports.isWithinRoot = isWithinRoot;

package/_shared/core/path/confine/index.esm.js

@@ -0,0 +1,19 @@
+import { removeTrailingSlash, normalizePath } from '../normalize/index.esm.js';
+import { existsSync, realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function contains(root, path) {
+    const base = removeTrailingSlash(root);
+    return path === base || path.startsWith(`${base}/`);
+}
+function isWithinRoot(root, candidate) {
+    if (!contains(normalizePath(resolve(root)), normalizePath(resolve(candidate)))) {
+        return false;
+    }
+    if (!existsSync(candidate)) {
+        return true;
+    }
+    return contains(normalizePath(realpathSync(root)), normalizePath(realpathSync(candidate)));
+}
+
+export { contains, isWithinRoot };

package/_shared/core/path/join/index.cjs.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const node_path = require('node:path');
+
+function join(...paths) {
+    return node_path.join(...paths);
+}
+function joinPosix(...paths) {
+    return node_path.posix.join(...paths);
+}
+
+exports.join = join;
+exports.joinPosix = joinPosix;

package/_shared/core/path/join/index.esm.js

@@ -0,0 +1,10 @@
+import { posix } from 'node:path';
+
+function join(...paths) {
+    return join$1(...paths);
+}
+function joinPosix(...paths) {
+    return posix.join(...paths);
+}
+
+export { join, joinPosix };