@estjs/shared 0.0.14-beta.9 → 0.0.15-beta.1

package/dist/shared.d.ts

@@ -1,80 +1,325 @@
-declare const _toString: () => string;
+/**
+ * Reference to Object.assign
+ * @type {Function}
+ */
 declare const extend: {
     <T extends {}, U>(target: T, source: U): T & U;
     <T extends {}, U, V>(target: T, source1: U, source2: V): T & U & V;
     <T extends {}, U, V, W>(target: T, source1: U, source2: V, source3: W): T & U & V & W;
     (target: object, ...sources: any[]): any;
 };
+/**
+ * Checks if an object has a specific property
+ * @template T
+ * @param {object} val - The target object to check
+ * @param {string | symbol} key - The property name to check for
+ * @returns {key is keyof T} - Returns true if the object has the property, false otherwise
+ */
 declare const hasOwn: (val: object, key: string | symbol) => key is keyof typeof val;
+/**
+ * Forces a value to be an array
+ * @template T - The type of array elements
+ * @param {T | T[]} data - The data to convert, can be a single element or an array
+ * @returns {T[]} - The resulting array
+ */
 declare function coerceArray<T>(data: T | T[]): T[];
-declare const hasChanged: (value: any, oldValue: any) => boolean;
+/**
+ * Checks if a value has changed
+ * @param {unknown } value - The new value
+ * @param {unknown } oldValue - The old value
+ * @returns {boolean} - Returns true if the value has changed, false otherwise
+ */
+declare const hasChanged: (value: unknown, oldValue: unknown) => boolean;
+/**
+ * Empty function, used for defaults and placeholders
+ * @type {Function}
+ */
 declare const noop: () => void;
 /**
- * A function that checks if a string starts with a specific substring.
- *  indexOf faster under normal circumstances
+ * Checks if a string starts with a specified substring
+ *
+ * Uses indexOf for better performance in most cases
  * @see https://www.measurethat.net/Benchmarks/Show/12350/0/startswith-vs-test-vs-match-vs-indexof#latest_results_block
-
- * @param {string} str - The input string to check.
- * @param {string} searchString - The substring to check for at the beginning of the input string.
- * @return {boolean} Returns true if the input string starts with the specified substring, otherwise false.
+ * @param {string} str - The string to check
+ * @param {string} searchString - The substring to search for
+ * @returns {boolean} - Returns true if the string starts with the substring, false otherwise
+ */
+declare function startsWith(str: string, searchString: string): boolean;
+/**
+ * Generates an 8-character random string as a unique identifier
+ *
+ * Note: Uses Math.random() which is not cryptographically secure.
+ * For security-sensitive use cases, consider using crypto.getRandomValues()
+ * @returns {string} - The generated unique identifier
+ */
+declare function generateUniqueId(): string;
+/**
+ * Checks if the current environment is a browser
+ * @returns {boolean} - Returns true if in a browser environment, false otherwise
+ */
+declare function isBrowser(): boolean;
+/**
+ * Creates a cached version of a string processing function
+ * @template T - The function type
+ * @param {T} fn - The string processing function to cache
+ * @returns {T} - The cached function
+ */
+declare const cacheStringFunction: <T extends (str: string) => string>(fn: T) => T;
+/**
+ * Read-only empty object
+ * @type {Readonly<Record<string, unknown >>}
+ */
+declare const EMPTY_OBJ: {
+    readonly [key: string]: unknown;
+};
+/**
+ * Read-only empty array
+ * @type {readonly never[]}
+ */
+declare const EMPTY_ARR: readonly never[];
+/**
+ * Checks if a property name is an event handler (starts with 'on' followed by uppercase letter)
+ *
+ * Matches patterns like: onClick, onChange, onKeyDown (but not 'onclick' or 'on123')
+ * @param {string} key - The property name to check
+ * @returns {boolean} - Returns true if the property is an event handler, false otherwise
  */
-declare function startsWith(str: any, searchString: any): boolean;
+declare const isOn: (key: string) => boolean;
 /**
- * Escapes special HTML characters in a string.
- * @param str - The string to escape.
- * @returns The escaped string.
+ * Gets the global object for the current environment
+ * @returns {unknown } - The global object for the current environment
  */
-declare function escape(str: string): string;
+declare const getGlobalThis: () => unknown;
 type ExcludeType = ((key: string | symbol) => boolean) | (string | symbol)[];
 /**
- * Checks if a key should be excluded based on the provided exclude criteria.
- * @param key - The key to check.
- * @param exclude - The exclusion criteria.
- * @returns True if the key should be excluded, otherwise false.
+ * Checks if a key should be excluded
+ * @param {string | symbol} key - The key to check
+ * @param {ExcludeType} [exclude] - The exclusion condition, can be a function or array
+ * @returns {boolean} - Returns true if the key should be excluded, false otherwise
  */
 declare function isExclude(key: string | symbol, exclude?: ExcludeType): boolean;
+
 /**
- * Generates a unique random 8 character string ID.
- * The generated IDs only contain alphanumeric characters.
- * @returns A unique random 8 character string ID.
+ * Checks if a value is an object
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is an object, false otherwise
  */
-declare function generateUniqueId(): string;
+declare const isObject: (val: unknown) => val is Record<any, unknown>;
 /**
- * Checks if the current environment is a browser.
- * @returns True if the current environment is a browser, otherwise false.
+ * Checks if a value is a Promise
+ * @template T - The type of the Promise's resolved value
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is a Promise, false otherwise
+ */
+declare function isPromise<T = unknown>(val: unknown): val is Promise<T>;
+/**
+ * Checks if a value is an Array
+ * @type {(arg: unknown ) => arg is unknown []}
  */
-declare function isBrowser(): boolean;
-
-declare const isObject: (val: unknown) => val is Record<any, any>;
-declare function isPromise(val: any): val is Promise<any>;
 declare const isArray: (arg: any) => arg is any[];
+/**
+ * Checks if a value is a string
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is a string, false otherwise
+ */
 declare function isString(val: unknown): val is string;
+/**
+ * Checks if a value is a number
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is a number, false otherwise
+ */
+declare function isNumber(val: unknown): val is number;
+/**
+ * Checks if a value is null
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is null, false otherwise
+ */
+declare function isNull(val: unknown): val is null;
+/**
+ * Checks if a value is a Symbol
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is a Symbol, false otherwise
+ */
 declare function isSymbol(val: unknown): val is symbol;
-declare function isSet(val: any): val is Set<any>;
-declare function isWeakMap(val: any): val is WeakMap<any, any>;
-declare function isWeakSet(val: any): val is WeakSet<any>;
-declare function isMap(val: unknown): val is Map<any, any>;
-declare function isNil(x: any): x is null | undefined;
+/**
+ * Checks if a value is a Set
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is a Set, false otherwise
+ */
+declare function isSet(val: unknown): val is Set<unknown>;
+/**
+ * Checks if a value is a WeakMap
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is a WeakMap, false otherwise
+ */
+declare function isWeakMap(val: unknown): val is WeakMap<any, unknown>;
+/**
+ * Checks if a value is a WeakSet
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is a WeakSet, false otherwise
+ */
+declare function isWeakSet(val: unknown): val is WeakSet<any>;
+/**
+ * Checks if a value is a Map
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is a Map, false otherwise
+ */
+declare function isMap(val: unknown): val is Map<unknown, unknown>;
+/**
+ * Checks if a value is null or undefined
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is null or undefined, false otherwise
+ */
+declare function isNil(val: unknown): val is null | undefined;
+/**
+ * Checks if a value is a function
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is a function, false otherwise
+ */
 declare const isFunction: (val: unknown) => val is Function;
-declare function isFalsy(x: any): x is false | null | undefined;
+/**
+ * Checks if a value is falsy (false, null, or undefined)
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is falsy, false otherwise
+ */
+declare function isFalsy(val: unknown): val is false | null | undefined;
+/**
+ * Checks if a value is a primitive type (string, number, boolean, symbol, null, or undefined)
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is a primitive type, false otherwise
+ */
 declare const isPrimitive: (val: unknown) => val is string | number | boolean | symbol | null | undefined;
-declare function isHTMLElement(obj: any): any;
+/**
+ * Checks if a value is an HTMLElement
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is an HTMLElement, false otherwise
+ */
+declare function isHTMLElement(val: unknown): val is HTMLElement;
+/**
+ * Checks if a value is a plain object (created using Object constructor)
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is a plain object, false otherwise
+ */
 declare const isPlainObject: (val: unknown) => val is object;
+/**
+ * String representation of a number
+ * @typedef {`${number}`} StringNumber
+ */
 type StringNumber = `${number}`;
+/**
+ * Checks if a value is a string representation of a number
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is a string number, false otherwise
+ */
 declare function isStringNumber(val: unknown): val is StringNumber;
+/**
+ * Checks if a value is undefined
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is undefined, false otherwise
+ */
+declare function isUndefined(val: unknown): val is undefined;
+/**
+ * Checks if a value is a boolean
+ * @param {unknown} val - The value to check
+ * @returns {boolean} - Returns true if the value is a boolean, false otherwise
+ */
+declare function isBoolean(val: unknown): val is boolean;
+declare function isNaN(val: unknown): val is number;
 
+/**
+ * Converts a camelCase string to kebab-case
+ * Example: myFunction -> my-function
+ * @param {string} str - The camelCase string to convert
+ * @returns {string} - The kebab-case string
+ */
 declare const kebabCase: (str: string) => string;
+/**
+ * Converts a kebab-case or snake_case string to camelCase
+ * Example: my-function or my_function -> myFunction
+ * @param {string} str - The kebab-case or snake_case string to convert
+ * @returns {string} - The camelCase string
+ */
 declare const camelCase: (str: string) => string;
 /**
- * Capitalizes the first letter of a string.
- *
- * @param {string} inputString - The input string to capitalize the first letter.
- * @return {string} The string with the first letter capitalized.
+ * Capitalizes the first letter of a string
+ * Example: hello -> Hello
+ * @template T - The input string type
+ * @param {T} str - The string to capitalize
+ * @returns {Capitalize<T>} - The capitalized string
  */
 declare const capitalize: <T extends string>(str: T) => Capitalize<T>;
 
-declare function warn(msg: string, ..._args: any[]): void;
-declare function info(msg: string, ..._args: any[]): void;
-declare function error(msg: string, ..._args: any[]): void;
+/**
+ * Outputs a warning level log message
+ * @param {string} msg - The warning message
+ * @param {...unknown } args - Additional arguments to log
+ */
+declare function warn(msg: string, ...args: unknown[]): void;
+/**
+ * Outputs an info level log message
+ * @param {string} msg - The info message
+ * @param {...unknown } args - Additional arguments to log
+ */
+declare function info(msg: string, ...args: unknown[]): void;
+/**
+ * Outputs an error level log message
+ * @param {string} msg - The error message
+ * @param {...unknown } args - Additional arguments to log
+ */
+declare function error(msg: string, ...args: unknown[]): void;
+
+/**
+ * Escapes HTML special characters in a string to their corresponding entity references
+ * @param {unknown} string - The string to escapeHTML
+ * @returns {string} - The escaped string
+ */
+declare function escapeHTML(string: unknown): string;
+/**
+ * Strips special characters from HTML comments
+ * @param {string} src - The source string
+ * @returns {string} - The cleaned string
+ */
+declare function escapeHTMLComment(src: string): string;
+/**
+ * Escapes special characters in CSS variable names
+ * @param {string} key - The CSS variable name
+ * @param {boolean} doubleEscape - Whether to apply double escaping
+ * @returns {string} - The escaped CSS variable name
+ */
+declare function getEscapedCssVarName(key: string, doubleEscape: boolean): string;
+
+declare const isSpecialBooleanAttr: (key: string) => boolean;
+/**
+ * The full list is needed during SSR to produce the correct initial markup.
+ */
+declare const isBooleanAttr: (key: string) => boolean;
+/**
+ * Boolean attributes should be included if the value is truthy or ''.
+ * e.g. `<select multiple>` compiles to `{ multiple: '' }`
+ */
+declare function includeBooleanAttr(value: unknown): boolean;
+declare function isSSRSafeAttrName(name: string): boolean;
+declare const propsToAttrMap: Record<string, string | undefined>;
+/**
+ * Known attributes, this is used for stringification of runtime static nodes
+ * so that we don't stringify bindings that cannot be set from HTML.
+ * Don't also forget to allow `data-*` and `aria-*`!
+ * Generated from https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes
+ */
+declare const isKnownHtmlAttr: (key: string) => boolean;
+/**
+ * Generated from https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute
+ */
+declare const isKnownSvgAttr: (key: string) => boolean;
+/**
+ * Shared between server-renderer and runtime-core hydration logic
+ */
+declare function isRenderAbleAttrValue(value: unknown): boolean;
+declare const isHTMLTag: (key: string) => boolean;
+declare const isSVGTag: (key: string) => boolean;
+declare const isMathMLTag: (key: string) => boolean;
+declare const isVoidTag: (key: string) => boolean;
+declare const isSelfClosingTag: (key: string) => boolean;
+declare const isDelegatedEvent: (key: string) => boolean;
 
-export { type ExcludeType, type StringNumber, _toString, camelCase, capitalize, coerceArray, error, escape, extend, generateUniqueId, hasChanged, hasOwn, info, isArray, isBrowser, isExclude, isFalsy, isFunction, isHTMLElement, isMap, isNil, isObject, isPlainObject, isPrimitive, isPromise, isSet, isString, isStringNumber, isSymbol, isWeakMap, isWeakSet, kebabCase, noop, startsWith, warn };
+export { EMPTY_ARR, EMPTY_OBJ, type ExcludeType, type StringNumber, cacheStringFunction, camelCase, capitalize, coerceArray, error, escapeHTML, escapeHTMLComment, extend, generateUniqueId, getEscapedCssVarName, getGlobalThis, hasChanged, hasOwn, includeBooleanAttr, info, isArray, isBoolean, isBooleanAttr, isBrowser, isDelegatedEvent, isExclude, isFalsy, isFunction, isHTMLElement, isHTMLTag, isKnownHtmlAttr, isKnownSvgAttr, isMap, isMathMLTag, isNaN, isNil, isNull, isNumber, isObject, isOn, isPlainObject, isPrimitive, isPromise, isRenderAbleAttrValue, isSSRSafeAttrName, isSVGTag, isSelfClosingTag, isSet, isSpecialBooleanAttr, isString, isStringNumber, isSymbol, isUndefined, isVoidTag, isWeakMap, isWeakSet, kebabCase, noop, propsToAttrMap, startsWith, warn };