@estjs/shared 0.0.15 → 0.0.16-beta.1

package/dist/shared.d.cts

@@ -9,25 +9,26 @@ declare const extend: {
     (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
+ * Checks if an object has a specific property.
+ *
+ * @param val - The target object to check.
+ * @param key - The property name to check for.
+ * @returns {boolean} 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
+ * Forces a value to be an array.
+ *
+ * @param data - The data to convert, can be a single element or an array.
+ * @returns The resulting array.
  */
 declare function coerceArray<T>(data: T | T[]): T[];
 /**
- * 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
+ * Checks if a value has changed.
+ *
+ * @param value - The new value.
+ * @param oldValue - The old value.
+ * @returns {boolean} True if the value has changed, false otherwise.
  */
 declare const hasChanged: (value: unknown, oldValue: unknown) => boolean;
 /**
@@ -36,33 +37,30 @@ declare const hasChanged: (value: unknown, oldValue: unknown) => boolean;
  */
 declare const noop: () => void;
 /**
- * Checks if a string starts with a specified substring
+ * 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 string to check
- * @param {string} searchString - The substring to search for
- * @returns {boolean} - Returns true if the string starts with the substring, false otherwise
+ * @param str - The string to check.
+ * @param searchString - The substring to search for.
+ * @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
+ * 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
+ * @returns 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
+ * Checks if the current environment is a browser.
+ *
+ * @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
+ * Creates a cached version of a string processing function.
+ *
+ * @param fn - The string processing function to cache.
+ * @returns The cached function.
  */
 declare const cacheStringFunction: <T extends (str: string) => string>(fn: T) => T;
 /**
@@ -78,119 +76,136 @@ declare const EMPTY_OBJ: {
  */
 declare const EMPTY_ARR: readonly never[];
 /**
- * Checks if a property name is an event handler (starts with 'on' followed by uppercase letter)
+ * Checks if a property name is an event handler.
  *
- * 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
+ * @param key - The property name to check.
+ * @returns {boolean} True if the property is an event handler, false otherwise.
  */
 declare const isOn: (key: string) => boolean;
 /**
  * Gets the global object for the current environment
- * @returns {unknown } - The global object for the current environment
+ * @returns {unknown} - The global object for the current environment
  */
 declare const getGlobalThis: () => unknown;
 
 /**
- * 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
+ * Checks if a value is an object.
+ *
+ * @param val - The value to check.
+ * @returns {boolean} True if the value is an object, false otherwise.
  */
 declare const isObject: (val: unknown) => val is Record<any, unknown>;
 /**
- * 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
+ * Checks if a value is a Promise.
+ *
+ * @template T - The type of the Promise's resolved value.
+ * @param val - The value to check.
+ * @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 []}
+ * Checks if a value is an Array.
+ *
+ * @param arg - The value to check.
+ * @returns True if the value is an array, false otherwise.
  */
 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
+ * Checks if a value is a string.
+ *
+ * @param val - The value to check.
+ * @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
+ * Checks if a value is a number.
+ *
+ * @param val - The value to check.
+ * @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
+ * Checks if a value is null.
+ *
+ * @param val - The value to check.
+ * @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
+ * Checks if a value is a Symbol.
+ *
+ * @param val - The value to check.
+ * @returns True if the value is a Symbol, false otherwise.
  */
 declare function isSymbol(val: unknown): val is symbol;
 /**
- * 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
+ * Checks if a value is a Set.
+ *
+ * @param val - The value to check.
+ * @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
+ * Checks if a value is a WeakMap.
+ *
+ * @param val - The value to check.
+ * @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
+ * Checks if a value is a WeakSet.
+ *
+ * @param val - The value to check.
+ * @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
+ * Checks if a value is a Map.
+ *
+ * @param val - The value to check.
+ * @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
+ * Checks if a value is null or undefined.
+ *
+ * @param val - The value to check.
+ * @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
+ * Checks if a value is a function.
+ *
+ * @param val - The value to check.
+ * @returns {boolean} True if the value is a function, false otherwise.
  */
 declare const isFunction: (val: unknown) => val is Function;
 /**
- * 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
+ * Checks if a value is falsy (false, null, or undefined).
+ *
+ * @param val - The value to check.
+ * @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
+ * Checks if a value is a primitive type.
+ *
+ * @param val - The value to check.
+ * @returns {boolean} True if the value is a primitive type, false otherwise.
  */
 declare const isPrimitive: (val: unknown) => val is string | number | boolean | symbol | null | undefined;
 /**
- * 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
+ * Checks if a value is an HTMLElement.
+ *
+ * @param val - The value to check.
+ * @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
+ * Checks if a value is a plain object.
+ *
+ * @param val - The value to check.
+ * @returns {boolean} True if the value is a plain object, false otherwise.
  */
 declare const isPlainObject: (val: unknown) => val is object;
 /**
@@ -199,84 +214,125 @@ declare const isPlainObject: (val: unknown) => val is object;
  */
 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
+ * Checks if a value is a string representation of a number.
+ *
+ * @param val - The value to check.
+ * @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
+ * Checks if a value is undefined.
+ *
+ * @param val - The value to check.
+ * @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
+ * Checks if a value is a boolean.
+ *
+ * @param val - The value to check.
+ * @returns True if the value is a boolean, false otherwise.
  */
 declare function isBoolean(val: unknown): val is boolean;
+/**
+ * Checks whether the value is `NaN`.
+ *
+ * @param val - The value to check.
+ * @returns True if the value is NaN.
+ */
 declare function isNaN(val: unknown): val is number;
+/**
+ * Checks whether the value is a bigint.
+ *
+ * @param val - The value to check.
+ * @returns True if the value is a bigint.
+ */
+declare function isBigint(val: unknown): val is bigint;
 
 /**
- * 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
+ * Converts a camelCase string to kebab-case.
+ *
+ * @param str - The camelCase string to convert.
+ * @returns {string} The kebab-case string.
+ *
+ * @example
+ * ```typescript
+ * kebabCase('myFunction') // 'my-function'
+ * ```
  */
 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
+ * Converts a kebab-case or snake_case string to camelCase.
+ *
+ * @param str - The kebab-case or snake_case string to convert.
+ * @returns {string} The camelCase string.
+ *
+ * @example
+ * ```typescript
+ * camelCase('my-function') // 'myFunction'
+ * camelCase('my_function') // 'myFunction'
+ * ```
  */
 declare const camelCase: (str: string) => string;
 /**
- * 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
+ * Capitalizes the first letter of a string.
+ *
+ * @template T - The input string type.
+ * @param str - The string to capitalize.
+ * @returns {Capitalize<T>} The capitalized string.
+ *
+ * @example
+ * ```typescript
+ * capitalize('hello') // 'Hello'
+ * ```
  */
 declare const capitalize: <T extends string>(str: T) => Capitalize<T>;
 
 /**
- * Outputs a warning level log message
- * @param {string} msg - The warning message
- * @param {...unknown } args - Additional arguments to log
+ * Outputs a warning level log message.
+ *
+ * @param msg - The warning message.
+ * @param args - Additional arguments to log.
+ * @returns {void}
  */
 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
+ * Outputs an info level log message.
+ *
+ * @param msg - The info message.
+ * @param args - Additional arguments to log.
+ * @returns {void}
  */
 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
+ * Outputs an error level log message.
+ *
+ * @param msg - The error message.
+ * @param args - Additional arguments to log.
+ * @returns {void}
  */
 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
+ * Escapes HTML special characters in a string to their corresponding entity references.
+ *
+ * @param string - The string to escape.
+ * @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
+ * Strips special characters from HTML comments.
+ *
+ * @param 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
+ * Escapes special characters in CSS variable names.
+ *
+ * @param key - The CSS variable name.
+ * @param doubleEscape - Whether to apply double escaping.
+ * @returns The escaped CSS variable name.
  */
 declare function getEscapedCssVarName(key: string, doubleEscape: boolean): string;
 
@@ -288,8 +344,17 @@ declare const isBooleanAttr: (key: string) => boolean;
 /**
  * Boolean attributes should be included if the value is truthy or ''.
  * e.g. `<select multiple>` compiles to `{ multiple: '' }`
+ *
+ * @param value - The value to check.
+ * @returns True if the attribute should be included.
  */
 declare function includeBooleanAttr(value: unknown): boolean;
+/**
+ * Checks whether an attribute name is safe to render during SSR.
+ *
+ * @param name - The attribute name to check.
+ * @returns True if the attribute name is safe.
+ */
 declare function isSSRSafeAttrName(name: string): boolean;
 declare const propsToAttrMap: Record<string, string | undefined>;
 /**
@@ -303,14 +368,9 @@ 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;
 
@@ -368,41 +428,32 @@ type StyleValue = string | NormalizedStyle | StyleValue[] | null | undefined;
  */
 type ClassValue = string | Record<string, boolean> | ClassValue[] | null | undefined;
 /**
- * Parse CSS style string into object format
+ * Parse CSS style string into object format.
  *
- * @param cssText - CSS style string
- * @returns Normalized style object
+ * @param cssText - CSS style string.
+ * @returns {NormalizedStyle} Normalized style object.
  */
 declare function parseStyleString(cssText: string): NormalizedStyle;
 /**
- * Normalize style value to a unified format
+ * Normalize style value to a unified format.
  *
- * @param styleValue - Original style value (object, string, or array)
- * @returns Normalized style object or string
+ * @param styleValue - Original style value (object, string, or array).
+ * @returns {NormalizedStyle | string | undefined} Normalized style object or string.
  */
 declare function normalizeStyle(styleValue: unknown): NormalizedStyle | string | undefined;
 /**
- * Convert style object to CSS string
+ * Convert style object to CSS string.
  *
- * @param styleValue - Style object or string
- * @returns Formatted CSS string
+ * @param styleValue - Style object or string.
+ * @returns {string} Formatted CSS string.
  */
 declare function styleToString(styleValue: NormalizedStyle | string | undefined): string;
 /**
- * Normalize class value to a unified string format
+ * Normalize class value to a unified string format.
  *
- * @param classValue - Original class value (string, array, or object)
- * @returns Normalized class name string
+ * @param classValue - Original class value (string, array, or object).
+ * @returns {string} Normalized class name string.
  */
 declare function normalizeClassName(classValue: unknown): string;
-/**
- * Convert style object to CSS string
- *
- * Handle different types of style values, and apply CSS variable and kebab-case transformations
- *
- * @param styleValue Style object or string
- * @returns Formatted CSS string
- */
-declare function styleObjectToString(styleValue: NormalizedStyle | string | undefined): string;
 
-export { type ClassValue, EMPTY_ARR, EMPTY_OBJ, type NormalizedStyle, type StringNumber, type StyleValue, cacheStringFunction, camelCase, capitalize, coerceArray, error, escapeHTML, escapeHTMLComment, extend, generateUniqueId, getEscapedCssVarName, getGlobalThis, hasChanged, hasOwn, includeBooleanAttr, info, isArray, isBoolean, isBooleanAttr, isBrowser, isDelegatedEvent, isFalsy, isFunction, isHTMLElement, isHTMLTag, isHtmlFormElement, isHtmlInputElement, isHtmlSelectElement, isHtmlTextAreaElement, isKnownHtmlAttr, isKnownSvgAttr, isMap, isMathMLTag, isNaN, isNil, isNode, isNull, isNumber, isObject, isOn, isPlainObject, isPrimitive, isPromise, isRenderAbleAttrValue, isSSRSafeAttrName, isSVGTag, isSelfClosingTag, isSet, isSpecialBooleanAttr, isString, isStringNumber, isSymbol, isTextNode, isUndefined, isVoidTag, isWeakMap, isWeakSet, kebabCase, noop, normalizeClassName, normalizeStyle, parseStyleString, propsToAttrMap, startsWith, styleObjectToString, styleToString, warn };
+export { type ClassValue, EMPTY_ARR, EMPTY_OBJ, type NormalizedStyle, type StringNumber, type StyleValue, cacheStringFunction, camelCase, capitalize, coerceArray, error, escapeHTML, escapeHTMLComment, extend, generateUniqueId, getEscapedCssVarName, getGlobalThis, hasChanged, hasOwn, includeBooleanAttr, info, isArray, isBigint, isBoolean, isBooleanAttr, isBrowser, isDelegatedEvent, isFalsy, isFunction, isHTMLElement, isHTMLTag, isHtmlFormElement, isHtmlInputElement, isHtmlSelectElement, isHtmlTextAreaElement, isKnownHtmlAttr, isKnownSvgAttr, isMap, isMathMLTag, isNaN, isNil, isNode, isNull, isNumber, isObject, isOn, isPlainObject, isPrimitive, isPromise, isSSRSafeAttrName, isSVGTag, isSelfClosingTag, isSet, isSpecialBooleanAttr, isString, isStringNumber, isSymbol, isTextNode, isUndefined, isWeakMap, isWeakSet, kebabCase, noop, normalizeClassName, normalizeStyle, parseStyleString, propsToAttrMap, startsWith, styleToString, warn };