@h3ravel/support 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,271 @@
+/**
+ * Converts CamelCased strings to snake_case
+ */
+type CamelToSnakeCase<S extends string> = S extends `${infer T}${infer U}` ? `${T extends Capitalize<T> ? '_' : ''}${Lowercase<T>}${CamelToSnakeCase<U>}` : S;
+
+/**
+ * Adds a dot prefix to nested keys
+ */
+type DotPrefix<T extends string, U extends string> = T extends '' ? U : `${T}.${U}`;
+/**
+ * Converts a union of objects into a single merged object
+ */
+type MergeUnion<T> = (T extends any ? (k: T) => void : never) extends (k: infer I) => void ? {
+    [K in keyof I]: I[K];
+} : never;
+/**
+ * Flattens nested objects into dotted keys
+ */
+type DotFlatten<T, Prefix extends string = ''> = MergeUnion<{
+    [K in keyof T & string]: T[K] extends Record<string, any> ? DotFlatten<T[K], DotPrefix<Prefix, K>> : {
+        [P in DotPrefix<Prefix, K>]: T[K];
+    };
+}[keyof T & string]>;
+/**
+ * Builds "nested.key" paths for autocompletion
+ */
+type DotNestedKeys<T> = {
+    [K in keyof T & string]: T[K] extends object ? `${K}` | `${K}.${DotNestedKeys<T[K]>}` : `${K}`;
+}[keyof T & string];
+/**
+ * Retrieves type at a given dot-path
+ */
+type DotNestedValue<T, Path extends string> = Path extends `${infer Key}.${infer Rest}` ? Key extends keyof T ? DotNestedValue<T[Key], Rest> : never : Path extends keyof T ? T[Path] : never;
+/**
+ * Convert CamelCased Object keys to snake_case
+ */
+type KeysToSnakeCase<T> = {
+    [K in keyof T as CamelToSnakeCase<string & K>]: T[K];
+};
+
+/**
+ * Splits an array into chunks of a specified size.
+ *
+ * @template T - Type of elements in the array
+ * @param arr - The input array
+ * @param size - Size of each chunk (default: 2)
+ * @returns An array of chunks (arrays)
+ */
+declare const chunk: <T>(arr: T[], size?: number) => T[][];
+/**
+ * Generates an array of sequential numbers.
+ *
+ * @param size - Number of elements in the range
+ * @param startAt - Starting number (default: 0)
+ * @returns An array of numbers from startAt to startAt + size - 1
+ */
+declare const range: (size: number, startAt?: number) => number[];
+
+/**
+ * Abbreviates large numbers using SI symbols (K, M, B...)
+ * and formats the output according to the given locale.
+ *
+ * @param value - The number to abbreviate
+ * @param locale - Optional locale string (default: "en-US")
+ * @returns A localized, abbreviated number string
+ */
+declare const abbreviate: (value?: number, locale?: string) => string;
+/**
+ * Concverts a number into human readable string
+ *
+ * @param num The number to convert
+ * @param slugify convert the ouput into a slug using this as a separator
+ * @returns
+ */
+declare const humanize: (num: number, slugify?: "-" | "_") => string;
+/**
+ * Converts a number of bytes into a human-readable string.
+ *
+ * @param bytes - The size in bytes to convert
+ * @param decimals - Number of decimal places to display (default: 2)
+ * @param bits - If true, uses 1000-based (SI) units (B, KB, MB...);
+ *               otherwise uses 1024-based binary units (Bytes, KiB...)
+ * @returns A formatted string with the appropriate unit
+ */
+declare const toBytes: (bytes?: number, decimals?: number, bits?: boolean) => string;
+/**
+ * Formats a duration (in seconds) into a human-readable string.
+ *
+ * @param seconds - Duration in seconds
+ * @param worded - If true, outputs worded format (e.g., "1hr 2min 3sec"),
+ *                 otherwise HH:MM:SS (e.g., "01:02:03")
+ * @returns A formatted time string
+ */
+declare const toHumanTime: (seconds?: number, worded?: boolean) => string;
+
+/**
+ * Flattens a nested object into a single-level object
+ * with dot-separated keys.
+ *
+ * Example:
+ * doter({
+ *   user: { name: "John", address: { city: "NY" } },
+ *   active: true
+ * })
+ *
+ * Output:
+ * {
+ *   "user.name": "John",
+ *   "user.address.city": "NY",
+ *   "active": true
+ * }
+ *
+ * @template T - The type of the input object
+ * @param obj - The nested object to flatten
+ * @returns A flattened object with dotted keys and inferred types
+ */
+declare const dot: <T extends Record<string, any>>(obj: T) => DotFlatten<T>;
+/**
+ * Extracts a subset of properties from an object.
+ *
+ * @template T - Type of the source object
+ * @template K - Keys of T to extract
+ * @param obj - The source object
+ * @param keys - Array of keys to extract
+ * @returns A new object with only the specified keys
+ */
+declare const extractProperties: <T extends object, K extends keyof T>(obj: T, keys?: readonly K[]) => Pick<T, K>;
+/**
+ * Safely retrieves a value from an object by key or nested keys.
+ *
+ * @template T - Type of the source object
+ * @param key - Single key or tuple [parentKey, childKey]
+ * @param item - The source object
+ * @returns The found value as a string or the key itself if not found
+ */
+declare const getValue: <T extends Record<string, any>>(key: string | [keyof T, keyof T[string]], item: T) => string;
+/**
+ * Maps over an object's entries and returns a new object
+ * with transformed keys and/or values.
+ *
+ * @template T - Type of the input object
+ * @template R - Type of the new values
+ * @param obj - The object to transform
+ * @param callback - Function that receives [key, value] and returns [newKey, newValue]
+ * @returns A new object with transformed entries
+ */
+declare const modObj: <T extends object, R>(obj: T, callback: (entry: [keyof T & string, T[keyof T]]) => [string, R]) => Record<string, R>;
+declare function safeDot<T extends Record<string, any>>(data: T): T;
+declare function safeDot<T extends Record<string, any>, K extends DotNestedKeys<T>>(data: T, key?: K): DotNestedValue<T, K>;
+/**
+ * Sets a nested property on an object using dot notation.
+ *
+ * @example
+ * const obj = {}
+ * setNested(obj, 'app.user.name', 'Legacy')
+ * console.log(obj)
+ * // Output: { app: { user: { name: 'Legacy' } } }
+ *
+ * @param obj - The target object to modify.
+ * @param key - The dot-separated key (e.g., 'app.user.name').
+ * @param value - The value to set at the specified path.
+ */
+declare const setNested: (obj: Record<string, any>, key: string, value: any) => void;
+/**
+ * Converts object keys to a slugified format (e.g., snake_case).
+ *
+ * @template T - Type of the input object
+ * @param obj - The object whose keys will be slugified
+ * @param only - Optional array of keys to slugify (others remain unchanged)
+ * @param separator - Separator for slugified keys (default: "_")
+ * @returns A new object with slugified keys
+ */
+declare const slugifyKeys: <T extends object>(obj: T, only?: string[], separator?: string) => KeysToSnakeCase<T>;
+
+/**
+ * Get the portion of the string after the first occurrence of the given value.
+ *
+ * @param value
+ * @param search
+ * @returns
+ */
+declare const after: (value: string, search: string) => string;
+/**
+ * Get the portion of the string after the last occurrence of the given value.
+ *
+ * @param value
+ * @param search
+ * @returns
+ */
+declare const afterLast: (value: string, search: string) => string;
+/**
+ * Get the portion of the string before the first occurrence of the given value.
+ *
+ * @param value
+ * @param search
+ * @returns
+ */
+declare const before: (value: string, search: string) => string;
+/**
+ * Get the portion of the string before the last occurrence of the given value.
+ *
+ * @param value
+ * @param search
+ * @returns
+ */
+declare const beforeLast: (value: string, search: string) => string;
+/**
+ * Capitalizes the first character of a string.
+ *
+ * @param str - The input string
+ * @returns The string with the first character capitalized
+ */
+declare function capitalize(str: string): string;
+/**
+ * Returns the pluralized form of a word based on the given number.
+ *
+ * @param word - The word to pluralize
+ * @param count - The number determining pluralization
+ * @returns Singular if count === 1, otherwise plural form
+ */
+declare const pluralize: (word: string, count: number) => string;
+/**
+ * Converts a plural English word into its singular form.
+ *
+ * @param word - The word to singularize
+ * @returns The singular form of the word
+ */
+declare const singularize: (word: string) => string;
+/**
+ * Converts a string into a slug format.
+ * Handles camelCase, spaces, and non-alphanumeric characters.
+ *
+ * @param str - The input string to slugify
+ * @param joiner - The character used to join words (default: "_")
+ * @returns A slugified string
+ */
+declare const slugify: (str: string, joiner?: string) => string;
+/**
+ * Truncates a string to a specified length and appends an ellipsis if needed.
+ *
+ * @param str - The input string
+ * @param len - Maximum length of the result (including ellipsis)
+ * @param ellipsis - String to append if truncated (default: "...")
+ * @returns The truncated string
+ */
+declare const subString: (str: string, len: number, ellipsis?: string) => string;
+/**
+ * Replaces placeholders in a string with corresponding values from a data object.
+ *
+ * Example:
+ * substitute("Hello { user.name }!", { user: { name: "John" } })
+ * // "Hello John!"
+ *
+ * @param str - The string containing placeholders wrapped in { } braces.
+ * @param data - Object containing values to substitute. Supports nested keys via dot notation.
+ * @param def - Default value to use if a key is missing. (Optional)
+ * @returns The substituted string or undefined if the input string or data is invalid.
+ */
+declare const substitute: (str: string, data?: Record<string, unknown>, def?: string) => string | undefined;
+/**
+ * Truncates a string to a specified length, removing HTML tags and
+ * appending a suffix if the string exceeds the length.
+ *
+ * @param str - The string to truncate
+ * @param len - Maximum length (default: 20)
+ * @param suffix - Suffix to append if truncated (default: "...")
+ * @returns The truncated string
+ */
+declare const truncate: (str: string, len?: number, suffix?: string) => string;
+
+export { type CamelToSnakeCase, type DotFlatten, type DotNestedKeys, type DotNestedValue, type KeysToSnakeCase, abbreviate, after, afterLast, before, beforeLast, capitalize, chunk, dot, extractProperties, getValue, humanize, modObj, pluralize, range, safeDot, setNested, singularize, slugify, slugifyKeys, subString, substitute, toBytes, toHumanTime, truncate };

package/dist/index.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Converts CamelCased strings to snake_case
+ */
+type CamelToSnakeCase<S extends string> = S extends `${infer T}${infer U}` ? `${T extends Capitalize<T> ? '_' : ''}${Lowercase<T>}${CamelToSnakeCase<U>}` : S;
+
+/**
+ * Adds a dot prefix to nested keys
+ */
+type DotPrefix<T extends string, U extends string> = T extends '' ? U : `${T}.${U}`;
+/**
+ * Converts a union of objects into a single merged object
+ */
+type MergeUnion<T> = (T extends any ? (k: T) => void : never) extends (k: infer I) => void ? {
+    [K in keyof I]: I[K];
+} : never;
+/**
+ * Flattens nested objects into dotted keys
+ */
+type DotFlatten<T, Prefix extends string = ''> = MergeUnion<{
+    [K in keyof T & string]: T[K] extends Record<string, any> ? DotFlatten<T[K], DotPrefix<Prefix, K>> : {
+        [P in DotPrefix<Prefix, K>]: T[K];
+    };
+}[keyof T & string]>;
+/**
+ * Builds "nested.key" paths for autocompletion
+ */
+type DotNestedKeys<T> = {
+    [K in keyof T & string]: T[K] extends object ? `${K}` | `${K}.${DotNestedKeys<T[K]>}` : `${K}`;
+}[keyof T & string];
+/**
+ * Retrieves type at a given dot-path
+ */
+type DotNestedValue<T, Path extends string> = Path extends `${infer Key}.${infer Rest}` ? Key extends keyof T ? DotNestedValue<T[Key], Rest> : never : Path extends keyof T ? T[Path] : never;
+/**
+ * Convert CamelCased Object keys to snake_case
+ */
+type KeysToSnakeCase<T> = {
+    [K in keyof T as CamelToSnakeCase<string & K>]: T[K];
+};
+
+/**
+ * Splits an array into chunks of a specified size.
+ *
+ * @template T - Type of elements in the array
+ * @param arr - The input array
+ * @param size - Size of each chunk (default: 2)
+ * @returns An array of chunks (arrays)
+ */
+declare const chunk: <T>(arr: T[], size?: number) => T[][];
+/**
+ * Generates an array of sequential numbers.
+ *
+ * @param size - Number of elements in the range
+ * @param startAt - Starting number (default: 0)
+ * @returns An array of numbers from startAt to startAt + size - 1
+ */
+declare const range: (size: number, startAt?: number) => number[];
+
+/**
+ * Abbreviates large numbers using SI symbols (K, M, B...)
+ * and formats the output according to the given locale.
+ *
+ * @param value - The number to abbreviate
+ * @param locale - Optional locale string (default: "en-US")
+ * @returns A localized, abbreviated number string
+ */
+declare const abbreviate: (value?: number, locale?: string) => string;
+/**
+ * Concverts a number into human readable string
+ *
+ * @param num The number to convert
+ * @param slugify convert the ouput into a slug using this as a separator
+ * @returns
+ */
+declare const humanize: (num: number, slugify?: "-" | "_") => string;
+/**
+ * Converts a number of bytes into a human-readable string.
+ *
+ * @param bytes - The size in bytes to convert
+ * @param decimals - Number of decimal places to display (default: 2)
+ * @param bits - If true, uses 1000-based (SI) units (B, KB, MB...);
+ *               otherwise uses 1024-based binary units (Bytes, KiB...)
+ * @returns A formatted string with the appropriate unit
+ */
+declare const toBytes: (bytes?: number, decimals?: number, bits?: boolean) => string;
+/**
+ * Formats a duration (in seconds) into a human-readable string.
+ *
+ * @param seconds - Duration in seconds
+ * @param worded - If true, outputs worded format (e.g., "1hr 2min 3sec"),
+ *                 otherwise HH:MM:SS (e.g., "01:02:03")
+ * @returns A formatted time string
+ */
+declare const toHumanTime: (seconds?: number, worded?: boolean) => string;
+
+/**
+ * Flattens a nested object into a single-level object
+ * with dot-separated keys.
+ *
+ * Example:
+ * doter({
+ *   user: { name: "John", address: { city: "NY" } },
+ *   active: true
+ * })
+ *
+ * Output:
+ * {
+ *   "user.name": "John",
+ *   "user.address.city": "NY",
+ *   "active": true
+ * }
+ *
+ * @template T - The type of the input object
+ * @param obj - The nested object to flatten
+ * @returns A flattened object with dotted keys and inferred types
+ */
+declare const dot: <T extends Record<string, any>>(obj: T) => DotFlatten<T>;
+/**
+ * Extracts a subset of properties from an object.
+ *
+ * @template T - Type of the source object
+ * @template K - Keys of T to extract
+ * @param obj - The source object
+ * @param keys - Array of keys to extract
+ * @returns A new object with only the specified keys
+ */
+declare const extractProperties: <T extends object, K extends keyof T>(obj: T, keys?: readonly K[]) => Pick<T, K>;
+/**
+ * Safely retrieves a value from an object by key or nested keys.
+ *
+ * @template T - Type of the source object
+ * @param key - Single key or tuple [parentKey, childKey]
+ * @param item - The source object
+ * @returns The found value as a string or the key itself if not found
+ */
+declare const getValue: <T extends Record<string, any>>(key: string | [keyof T, keyof T[string]], item: T) => string;
+/**
+ * Maps over an object's entries and returns a new object
+ * with transformed keys and/or values.
+ *
+ * @template T - Type of the input object
+ * @template R - Type of the new values
+ * @param obj - The object to transform
+ * @param callback - Function that receives [key, value] and returns [newKey, newValue]
+ * @returns A new object with transformed entries
+ */
+declare const modObj: <T extends object, R>(obj: T, callback: (entry: [keyof T & string, T[keyof T]]) => [string, R]) => Record<string, R>;
+declare function safeDot<T extends Record<string, any>>(data: T): T;
+declare function safeDot<T extends Record<string, any>, K extends DotNestedKeys<T>>(data: T, key?: K): DotNestedValue<T, K>;
+/**
+ * Sets a nested property on an object using dot notation.
+ *
+ * @example
+ * const obj = {}
+ * setNested(obj, 'app.user.name', 'Legacy')
+ * console.log(obj)
+ * // Output: { app: { user: { name: 'Legacy' } } }
+ *
+ * @param obj - The target object to modify.
+ * @param key - The dot-separated key (e.g., 'app.user.name').
+ * @param value - The value to set at the specified path.
+ */
+declare const setNested: (obj: Record<string, any>, key: string, value: any) => void;
+/**
+ * Converts object keys to a slugified format (e.g., snake_case).
+ *
+ * @template T - Type of the input object
+ * @param obj - The object whose keys will be slugified
+ * @param only - Optional array of keys to slugify (others remain unchanged)
+ * @param separator - Separator for slugified keys (default: "_")
+ * @returns A new object with slugified keys
+ */
+declare const slugifyKeys: <T extends object>(obj: T, only?: string[], separator?: string) => KeysToSnakeCase<T>;
+
+/**
+ * Get the portion of the string after the first occurrence of the given value.
+ *
+ * @param value
+ * @param search
+ * @returns
+ */
+declare const after: (value: string, search: string) => string;
+/**
+ * Get the portion of the string after the last occurrence of the given value.
+ *
+ * @param value
+ * @param search
+ * @returns
+ */
+declare const afterLast: (value: string, search: string) => string;
+/**
+ * Get the portion of the string before the first occurrence of the given value.
+ *
+ * @param value
+ * @param search
+ * @returns
+ */
+declare const before: (value: string, search: string) => string;
+/**
+ * Get the portion of the string before the last occurrence of the given value.
+ *
+ * @param value
+ * @param search
+ * @returns
+ */
+declare const beforeLast: (value: string, search: string) => string;
+/**
+ * Capitalizes the first character of a string.
+ *
+ * @param str - The input string
+ * @returns The string with the first character capitalized
+ */
+declare function capitalize(str: string): string;
+/**
+ * Returns the pluralized form of a word based on the given number.
+ *
+ * @param word - The word to pluralize
+ * @param count - The number determining pluralization
+ * @returns Singular if count === 1, otherwise plural form
+ */
+declare const pluralize: (word: string, count: number) => string;
+/**
+ * Converts a plural English word into its singular form.
+ *
+ * @param word - The word to singularize
+ * @returns The singular form of the word
+ */
+declare const singularize: (word: string) => string;
+/**
+ * Converts a string into a slug format.
+ * Handles camelCase, spaces, and non-alphanumeric characters.
+ *
+ * @param str - The input string to slugify
+ * @param joiner - The character used to join words (default: "_")
+ * @returns A slugified string
+ */
+declare const slugify: (str: string, joiner?: string) => string;
+/**
+ * Truncates a string to a specified length and appends an ellipsis if needed.
+ *
+ * @param str - The input string
+ * @param len - Maximum length of the result (including ellipsis)
+ * @param ellipsis - String to append if truncated (default: "...")
+ * @returns The truncated string
+ */
+declare const subString: (str: string, len: number, ellipsis?: string) => string;
+/**
+ * Replaces placeholders in a string with corresponding values from a data object.
+ *
+ * Example:
+ * substitute("Hello { user.name }!", { user: { name: "John" } })
+ * // "Hello John!"
+ *
+ * @param str - The string containing placeholders wrapped in { } braces.
+ * @param data - Object containing values to substitute. Supports nested keys via dot notation.
+ * @param def - Default value to use if a key is missing. (Optional)
+ * @returns The substituted string or undefined if the input string or data is invalid.
+ */
+declare const substitute: (str: string, data?: Record<string, unknown>, def?: string) => string | undefined;
+/**
+ * Truncates a string to a specified length, removing HTML tags and
+ * appending a suffix if the string exceeds the length.
+ *
+ * @param str - The string to truncate
+ * @param len - Maximum length (default: 20)
+ * @param suffix - Suffix to append if truncated (default: "...")
+ * @returns The truncated string
+ */
+declare const truncate: (str: string, len?: number, suffix?: string) => string;
+
+export { type CamelToSnakeCase, type DotFlatten, type DotNestedKeys, type DotNestedValue, type KeysToSnakeCase, abbreviate, after, afterLast, before, beforeLast, capitalize, chunk, dot, extractProperties, getValue, humanize, modObj, pluralize, range, safeDot, setNested, singularize, slugify, slugifyKeys, subString, substitute, toBytes, toHumanTime, truncate };