@hyperfrontend/project-scope 0.2.0 → 0.2.2

package/core/encoding/index.esm.js

@@ -1,389 +1,11 @@
-/**
- * Safe copies of Math built-in methods.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/math
- */
-// Capture references at module initialization time
-const _Math = globalThis.Math;
-/**
- * (Safe copy) Returns the smaller of zero or more numbers.
- */
-const min = _Math.min;
-
-/**
- * Safe copies of Array built-in static methods.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/array
- */
-// Capture references at module initialization time
-const _Array = globalThis.Array;
-/**
- * (Safe copy) Determines whether the passed value is an Array.
- */
-const isArray = _Array.isArray;
-
-/**
- * Safe copies of Console built-in methods.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/console
- */
-// Capture references at module initialization time
-const _console = globalThis.console;
-/**
- * (Safe copy) Outputs a message to the console.
- */
-const log = _console.log.bind(_console);
-/**
- * (Safe copy) Outputs a warning message to the console.
- */
-const warn = _console.warn.bind(_console);
-/**
- * (Safe copy) Outputs an error message to the console.
- */
-const error = _console.error.bind(_console);
-/**
- * (Safe copy) Outputs an informational message to the console.
- */
-const info = _console.info.bind(_console);
-/**
- * (Safe copy) Outputs a debug message to the console.
- */
-const debug = _console.debug.bind(_console);
-/**
- * (Safe copy) Outputs a stack trace to the console.
- */
-_console.trace.bind(_console);
-/**
- * (Safe copy) Displays an interactive listing of the properties of a specified object.
- */
-_console.dir.bind(_console);
-/**
- * (Safe copy) Displays tabular data as a table.
- */
-_console.table.bind(_console);
-/**
- * (Safe copy) Writes an error message to the console if the assertion is false.
- */
-_console.assert.bind(_console);
-/**
- * (Safe copy) Clears the console.
- */
-_console.clear.bind(_console);
-/**
- * (Safe copy) Logs the number of times that this particular call to count() has been called.
- */
-_console.count.bind(_console);
-/**
- * (Safe copy) Resets the counter used with console.count().
- */
-_console.countReset.bind(_console);
-/**
- * (Safe copy) Creates a new inline group in the console.
- */
-_console.group.bind(_console);
-/**
- * (Safe copy) Creates a new inline group in the console that is initially collapsed.
- */
-_console.groupCollapsed.bind(_console);
-/**
- * (Safe copy) Exits the current inline group.
- */
-_console.groupEnd.bind(_console);
-/**
- * (Safe copy) Starts a timer with a name specified as an input parameter.
- */
-_console.time.bind(_console);
-/**
- * (Safe copy) Stops a timer that was previously started.
- */
-_console.timeEnd.bind(_console);
-/**
- * (Safe copy) Logs the current value of a timer that was previously started.
- */
-_console.timeLog.bind(_console);
-
-/**
- * Safe copies of JSON built-in methods.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/json
- */
-// Capture references at module initialization time
-const _JSON = globalThis.JSON;
-/**
- * (Safe copy) Converts a JavaScript value to a JavaScript Object Notation (JSON) string.
- */
-const stringify = _JSON.stringify;
-
-/**
- * Safe copies of Object built-in methods.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/object
- */
-// Capture references at module initialization time
-const _Object = globalThis.Object;
-/**
- * (Safe copy) Prevents modification of existing property attributes and values,
- * and prevents the addition of new properties.
- */
-const freeze = _Object.freeze;
-/**
- * (Safe copy) Returns the names of the enumerable string properties and methods of an object.
- */
-const keys = _Object.keys;
-/**
- * (Safe copy) Returns an array of key/values of the enumerable own properties of an object.
- */
-const entries = _Object.entries;
-
-/**
- * Safe copies of Set built-in via factory function.
- *
- * Since constructors cannot be safely captured via Object.assign, this module
- * provides a factory function that uses Reflect.construct internally.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/set
- */
-// Capture references at module initialization time
-const _Set = globalThis.Set;
-const _Reflect$1 = globalThis.Reflect;
-/**
- * (Safe copy) Creates a new Set using the captured Set constructor.
- * Use this instead of `new Set()`.
- *
- * @param iterable - Optional iterable of values.
- * @returns A new Set instance.
- */
-const createSet = (iterable) => _Reflect$1.construct(_Set, iterable ? [iterable] : []);
-
-const registeredClasses = [];
-
-/**
- * Returns the data type of the target.
- * Uses native `typeof` operator, however, makes distinction between `null`, `array`, and `object`.
- * Also, when classes are registered via `registerClass`, it checks if objects are instance of any known registered class.
- *
- * @param target - The target to get the data type of.
- * @returns The data type of the target.
- */
-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;
-};
-
-/**
- * Safe copies of Error built-ins via factory functions.
- *
- * Since constructors cannot be safely captured via Object.assign, this module
- * provides factory functions that use Reflect.construct internally.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/error
- */
-// Capture references at module initialization time
-const _Error = globalThis.Error;
-const _Reflect = globalThis.Reflect;
-/**
- * (Safe copy) Creates a new Error using the captured Error constructor.
- * Use this instead of `new Error()`.
- *
- * @param message - Optional error message.
- * @param options - Optional error options.
- * @returns A new Error instance.
- */
-const createError = (message, options) => _Reflect.construct(_Error, [message, options]);
-
-/* eslint-disable @typescript-eslint/no-explicit-any */
-/**
- * Creates a wrapper function that only executes the wrapped function if the condition function returns true.
- *
- * @param func - The function to be conditionally executed.
- * @param conditionFunc - A function that returns a boolean, determining if `func` should be executed.
- * @returns A wrapped version of `func` that executes conditionally.
- */
-function createConditionalExecutionFunction(func, conditionFunc) {
-    return function (...args) {
-        if (conditionFunc()) {
-            return func(...args);
-        }
-    };
-}
-
-/* eslint-disable @typescript-eslint/no-explicit-any */
-/**
- * Creates a wrapper function that silently ignores any errors thrown by the wrapped void function.
- * This function is specifically for wrapping functions that do not return a value (void functions).
- * Exceptions are swallowed without any logging or handling.
- *
- * @param func - The void function to be wrapped.
- * @returns A wrapped version of the input function that ignores errors.
- */
-function createErrorIgnoringFunction(func) {
-    return function (...args) {
-        try {
-            func(...args);
-        }
-        catch {
-            // Deliberately swallowing/ignoring the exception
-        }
-    };
-}
-
-/* eslint-disable @typescript-eslint/no-unused-vars */
-/**
- * A no-operation function (noop) that does nothing regardless of the arguments passed.
- * It is designed to be as permissive as possible in its typing without using the `Function` keyword.
- *
- * @param args - Any arguments passed to the function (ignored)
- */
-const noop = (...args) => {
-    // Intentionally does nothing
-};
-
-const logLevels = ['none', 'error', 'warn', 'log', 'info', 'debug'];
-const priority = {
-    error: 4,
-    warn: 3,
-    log: 2,
-    info: 1,
-    debug: 0,
-};
-/**
- * Validates whether a given string is a valid log level.
- *
- * @param level - The log level to validate
- * @returns True if the level is valid, false otherwise
- */
-function isValidLogLevel(level) {
-    return logLevels.includes(level);
-}
-/**
- * Creates a log level configuration manager for controlling logging behavior.
- * Provides methods to get, set, and evaluate log levels based on priority.
- *
- * @param level - The initial log level (defaults to 'error')
- * @returns A configuration object with log level management methods
- * @throws {Error} When the provided level is not a valid log 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,
-    });
-}
-
-/**
- * Creates a logger instance with configurable log level filtering.
- * Each log function is wrapped to respect the current log level setting.
- *
- * @param error - Function to handle error-level logs (required)
- * @param warn - Function to handle warning-level logs (optional, defaults to noop)
- * @param log - Function to handle standard logs (optional, defaults to noop)
- * @param info - Function to handle info-level logs (optional, defaults to noop)
- * @param debug - Function to handle debug-level logs (optional, defaults to noop)
- * @returns A frozen logger object with log methods and level control
- * @throws {ErrorLevelFn} When any provided log function is invalid
- */
-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);
-    };
-    return freeze({
-        error: wrapLogFn(error, 'error'),
-        warn: wrapLogFn(warn, 'warn'),
-        log: wrapLogFn(log, 'log'),
-        info: wrapLogFn(info, 'info'),
-        debug: wrapLogFn(debug, 'debug'),
-        setLogLevel,
-        getLogLevel,
-    });
-}
-/**
- * Validates whether a given value is a valid log function.
- *
- * @param fn - The value to validate
- * @returns True if the value is not a function (invalid), false if it is valid
- */
-function notValidLogFn(fn) {
-    return getType(fn) !== 'function' && fn !== noop;
-}
-/**
- * Generates an error message for invalid log function parameters.
- *
- * @param label - The name of the log function that failed validation
- * @returns A formatted error message string
- */
-function notFnMsg(label) {
-    return `Cannot create a logger when ${label} is not a function`;
-}
-
-createLogger(error, warn, log, info, debug);
+import { createError } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
+import { isArray } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.esm.js';
+import { error, warn, log, info, debug } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/console/index.esm.js';
+import { stringify } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.esm.js';
+import { freeze, entries, keys } 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';
+import { createLogger } from '../../_dependencies/@hyperfrontend/logging/index.esm.js';
+import { min } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.esm.js';
 
 /**
  * Global log level registry.
@@ -423,6 +45,13 @@ function isSensitiveKey(key) {
  *
  * @param obj - Object to sanitize
  * @returns New object with sensitive values redacted
+ *
+ * @example Sanitizing sensitive data
+ * ```typescript
+ * const config = { apiKey: 'secret123', endpoint: 'https://api.example.com' }
+ * const safe = sanitize(config)
+ * // => { apiKey: '[REDACTED]', endpoint: 'https://api.example.com' }
+ * ```
  */
 function sanitize(obj) {
     if (obj === null || obj === undefined) {
@@ -473,7 +102,7 @@ function formatMessage(namespace, message, meta) {
  * @param options - Logger configuration options
  * @returns A configured scoped logger instance
  *
- * @example
+ * @example Creating a scoped logger
  * ```typescript
  * const logger = createScopedLogger('project-scope')
  * logger.setLogLevel('debug')
@@ -488,14 +117,11 @@ function formatMessage(namespace, message, meta) {
  */
 function createScopedLogger(namespace, options = {}) {
     const { level = 'error', sanitizeSecrets = true } = options;
-    // Create wrapper functions that add namespace prefix and sanitization
     const createLogFn = (baseFn) => (message, meta) => {
         const processedMeta = sanitizeSecrets && meta ? sanitize(meta) : meta;
         baseFn(formatMessage(namespace, message, processedMeta));
     };
-    // Create base logger with wrapped functions
     const baseLogger = createLogger(createLogFn(error), createLogFn(warn), createLogFn(log), createLogFn(info), createLogFn(debug));
-    // Set initial log level (use global override if set)
     baseLogger.setLogLevel(level);
     const scopedLogger = freeze({
         error: (message, meta) => baseLogger.error(message, meta),
@@ -506,7 +132,6 @@ function createScopedLogger(namespace, options = {}) {
         setLogLevel: baseLogger.setLogLevel,
         getLogLevel: baseLogger.getLogLevel,
     });
-    // Register logger for global level management
     loggerRegistry.add(scopedLogger);
     return scopedLogger;
 }
@@ -514,7 +139,7 @@ function createScopedLogger(namespace, options = {}) {
  * Default logger instance for the project-scope library.
  * Use this for general logging within the library.
  *
- * @example
+ * @example Using the default logger
  * ```typescript
  * import { logger } from '@hyperfrontend/project-scope/core'
  *
@@ -552,28 +177,34 @@ const BINARY_SIGNATURES = [
  *
  * @param buffer - Buffer to analyze
  * @returns Encoding information
+ *
+ * @example Detecting encoding and BOM info
+ * ```typescript
+ * const buffer = readFileSync('./document.txt')
+ * const info = detectEncodingInfo(buffer)
+ * if (info.type === 'text') {
+ *   console.log(`Encoding: ${info.encoding}, BOM: ${info.hasBom}`)
+ * }
+ * ```
  */
 function detectEncodingInfo(buffer) {
     encodingLogger.debug('Detecting encoding info', { bufferSize: buffer.length });
-    // Check for UTF-8 BOM
     if (buffer.length >= 3) {
         if (buffer[0] === UTF8_BOM_BYTES[0] && buffer[1] === UTF8_BOM_BYTES[1] && buffer[2] === UTF8_BOM_BYTES[2]) {
             encodingLogger.debug('Detected UTF-8 BOM');
             return { type: 'text', encoding: 'utf-8', hasBom: true };
         }
     }
-    // Check for UTF-16 BOMs
     if (buffer.length >= 2) {
         if (buffer[0] === UTF16_BE_BOM_BYTES[0] && buffer[1] === UTF16_BE_BOM_BYTES[1]) {
             encodingLogger.debug('Detected UTF-16 BE BOM');
-            return { type: 'text', encoding: 'utf16le', hasBom: true }; // Node treats BE through utf16le
+            return { type: 'text', encoding: 'utf16le', hasBom: true };
         }
         if (buffer[0] === UTF16_LE_BOM_BYTES[0] && buffer[1] === UTF16_LE_BOM_BYTES[1]) {
             encodingLogger.debug('Detected UTF-16 LE BOM');
             return { type: 'text', encoding: 'utf16le', hasBom: true };
         }
     }
-    // Check for binary signatures
     for (const { signature, description } of BINARY_SIGNATURES) {
         if (buffer.length >= signature.length) {
             let matches = true;
@@ -589,7 +220,6 @@ function detectEncodingInfo(buffer) {
             }
         }
     }
-    // Check for null bytes (usually indicates binary)
     const sampleSize = min(buffer.length, 8000);
     for (let i = 0; i < sampleSize; i++) {
         if (buffer[i] === 0) {
@@ -605,25 +235,28 @@ function detectEncodingInfo(buffer) {
  *
  * @param buffer - Buffer to analyze
  * @returns Detected encoding, defaults to 'utf-8'
+ *
+ * @example Detecting encoding from buffer
+ * ```typescript
+ * const buffer = readFileSync('./data.txt')
+ * const encoding = detectEncoding(buffer)
+ * const content = buffer.toString(encoding)
+ * ```
  */
 function detectEncoding(buffer) {
     if (buffer.length >= 3) {
-        // Check for UTF-8 BOM
         if (buffer[0] === UTF8_BOM_BYTES[0] && buffer[1] === UTF8_BOM_BYTES[1] && buffer[2] === UTF8_BOM_BYTES[2]) {
             return 'utf-8';
         }
     }
     if (buffer.length >= 2) {
-        // Check for UTF-16 LE BOM
         if (buffer[0] === UTF16_LE_BOM_BYTES[0] && buffer[1] === UTF16_LE_BOM_BYTES[1]) {
             return 'utf16le';
         }
-        // Check for UTF-16 BE BOM
         if (buffer[0] === UTF16_BE_BOM_BYTES[0] && buffer[1] === UTF16_BE_BOM_BYTES[1]) {
-            return 'utf16le'; // Node.js handles BE through utf16le
+            return 'utf16le';
         }
     }
-    // Default to UTF-8
     return 'utf-8';
 }
 /**
@@ -631,6 +264,14 @@ function detectEncoding(buffer) {
  *
  * @param buffer - Buffer to check
  * @returns True if buffer has a BOM
+ *
+ * @example Checking if buffer has BOM
+ * ```typescript
+ * const buffer = readFileSync('./file.txt')
+ * if (hasBom(buffer)) {
+ *   // Strip BOM before processing
+ * }
+ * ```
  */
 function hasBom(buffer) {
     if (buffer.length >= 3) {
@@ -651,19 +292,18 @@ function hasBom(buffer) {
  *
  * @param buffer - Buffer to check
  * @returns True if the buffer appears to be text
+ *
+ * @example Checking if content is text
+ * ```typescript
+ * const buffer = readFileSync('./unknown-file')
+ * if (isTextFile(buffer)) {
+ *   const content = buffer.toString('utf-8')
+ * }
+ * ```
  */
 function isTextFile(buffer) {
     return detectEncodingInfo(buffer).type === 'text';
 }
-/**
- * Check if buffer represents binary content.
- *
- * @param buffer - Buffer to check
- * @returns True if the buffer appears to be binary
- */
-function isBinaryFile(buffer) {
-    return detectEncodingInfo(buffer).type === 'binary';
-}
 
 const convertLogger = createScopedLogger('project-scope:encoding:convert');
 /**
@@ -672,6 +312,13 @@ const convertLogger = createScopedLogger('project-scope:encoding:convert');
  * @param content - Buffer or string content
  * @param sourceEncoding - Source encoding (auto-detected if not provided)
  * @returns UTF-8 string
+ *
+ * @example Converting a buffer to UTF-8 string
+ * ```typescript
+ * const buffer = Buffer.from('Hello', 'utf-8')
+ * const text = toUtf8(buffer)
+ * // => 'Hello'
+ * ```
  */
 function toUtf8(content, sourceEncoding = 'utf-8') {
     if (typeof content === 'string') {
@@ -686,6 +333,13 @@ function toUtf8(content, sourceEncoding = 'utf-8') {
  * @param encoding - Optional encoding override (auto-detected if not provided)
  * @returns Converted string
  * @throws {Error} If content is binary and cannot be converted
+ *
+ * @example Converting file buffer to string with auto-detection
+ * ```typescript
+ * const fileBuffer = readFileSync('./config.json')
+ * const content = bufferToString(fileBuffer)
+ * // => '{"key": "value"}'
+ * ```
  */
 function bufferToString(content, encoding) {
     convertLogger.debug('Converting buffer to string', { bufferSize: content.length, providedEncoding: encoding });
@@ -693,10 +347,8 @@ function bufferToString(content, encoding) {
         convertLogger.debug('Using provided encoding', { encoding });
         return content.toString(encoding);
     }
-    // Auto-detect and convert
     const info = detectEncodingInfo(content);
     if (info.type === 'text') {
-        // Remove BOM if present
         let offset = 0;
         if (info.hasBom) {
             offset = info.encoding === 'utf-8' ? 3 : 2;
@@ -712,6 +364,13 @@ function bufferToString(content, encoding) {
  *
  * @param content - String that may have BOM
  * @returns String without BOM
+ *
+ * @example Stripping BOM from a string
+ * ```typescript
+ * const withBom = '\ufeffHello World'
+ * const clean = stripBom(withBom)
+ * // => 'Hello World'
+ * ```
  */
 function stripBom(content) {
     if (content.charCodeAt(0) === 0xfeff) {
@@ -724,6 +383,13 @@ function stripBom(content) {
  *
  * @param content - String to add BOM to
  * @returns String with BOM
+ *
+ * @example Adding UTF-8 BOM to content
+ * ```typescript
+ * const content = 'Hello World'
+ * const withBom = addBom(content)
+ * // => '\ufeffHello World'
+ * ```
  */
 function addBom(content) {
     if (content.charCodeAt(0) === 0xfeff) {
@@ -732,5 +398,4 @@ function addBom(content) {
     return UTF8_BOM + content;
 }
 
-export { BINARY_SIGNATURES, UTF16_BE_BOM_BYTES, UTF16_LE_BOM_BYTES, UTF8_BOM, UTF8_BOM_BYTES, addBom, bufferToString, detectEncoding, detectEncodingInfo, hasBom, isBinaryFile, isTextFile, stripBom, toUtf8 };
-//# sourceMappingURL=index.esm.js.map
+export { BINARY_SIGNATURES, UTF16_BE_BOM_BYTES, UTF16_LE_BOM_BYTES, UTF8_BOM, UTF8_BOM_BYTES, addBom, bufferToString, detectEncoding, detectEncodingInfo, hasBom, isTextFile, stripBom, toUtf8 };