@h3ravel/support 0.10.4 → 0.11.0

package/dist/index.d.cts

@@ -1,6 +1,9 @@
 /// <reference path="./app.globals.d.ts" />
+import "node:module";
 import { DotFlatten, DotNestedKeys, DotNestedValue } from "@h3ravel/shared";
 
+//#region rolldown:runtime
+//#endregion
 //#region src/Contracts/StrContract.d.ts
 /**
  * Converts CamelCased strings to snake_case
@@ -24,8 +27,9 @@ type TGeneric<V = any, K extends string = string> = Record<K, V>;
 type XGeneric<V = TGeneric, T = any> = {
   [key: string]: T;
 } & V;
-//#endregion
-//#region src/Helpers/Arr.d.ts
+declare namespace Arr_d_exports {
+  export { alternate, chunk, collapse, combine, find, first, flatten, forget, isEmpty, isNotEmpty, last, pop, prepend, range, reverse, shift, take };
+}
 /**
  * Splits an array into chunks of a specified size.
  *
@@ -35,6 +39,40 @@ type XGeneric<V = TGeneric, T = any> = {
  * @returns An array of chunks (arrays)
  */
 declare const chunk: <T>(arr: T[], size?: number) => T[][];
+/**
+ * Collapse an array of arrays into a single array.
+ */
+declare const collapse: <T>(arr: (T | T[])[]) => T[];
+/**
+ * Alternates between two arrays, creating a zipped result.
+ */
+declare const alternate: <T>(a: T[], b: T[]) => T[];
+/**
+ * Combine arrays and sum their values element by element.
+ */
+declare const combine: (...arr: number[][]) => number[];
+/** Find the value associated with a given key. */
+declare const find: <T>(key: T, arr: T[]) => T | null;
+/** Returns a new array without the given indices. */
+declare const forget: <T>(arr: T[], keys: number[]) => T[];
+/** Remove the first element and return tuple [el, rest]. */
+declare const first: <T>(arr: T[]) => [T, T[]];
+/** Remove the last element and return tuple [el, rest]. */
+declare const last: <T>(arr: T[]) => [T, T[]];
+/** Check if array is empty. */
+declare const isEmpty: <T>(arr: T[]) => boolean;
+/** Check if array is empty. */
+declare const isNotEmpty: <T>(arr: T[]) => boolean;
+/** Pop the element off the end of array. */
+declare const pop: <T>(arr: T[]) => T[];
+/** Add elements to the beginning of array. */
+declare const prepend: <T>(arr: T[], ...elements: T[]) => T[];
+/** Take first n elements of array. */
+declare const take: <T>(amount: number, arr: T[]) => T[];
+/** Create a new array in reverse order. */
+declare const reverse: <T>(arr: T[]) => T[];
+/** Alias for first element removal. */
+declare const shift: <T>(arr: T[]) => [T, T[]];
 /**
  * Generates an array of sequential numbers.
  *
@@ -43,22 +81,126 @@ declare const chunk: <T>(arr: T[], size?: number) => T[][];
  * @returns An array of numbers from startAt to startAt + size - 1
  */
 declare const range: (size: number, startAt?: number) => number[];
-//#endregion
-//#region src/Helpers/DumpDie.d.ts
+/** Flatten multi-dimensional arrays into single level. */
+declare const flatten: <T>(arr: T[]) => T[];
+declare namespace Crypto_d_exports {
+  export { PasswordOptions, base64Decode, base64Encode, caesarCipher, checksum, hash, hmac, random, randomColor, randomPassword, randomSecure, secureToken, uuid, verifyChecksum, xor };
+}
 /**
- * Dump something and kill the process for quick debugging. Based on Laravel's dd()
+ * Generate a random UUID string.
  *
- * @param args
+ * @returns A random UUID string
  */
-declare const dd: (...args: unknown[]) => never;
+declare const uuid: () => string;
 /**
- * Dump something but keep the process for quick debugging. Based on Laravel's dump()
+ * Generate a random string of specified length.
  *
- * @param args
+ * @param length - Length of the random string (default: 16)
+ * @param charset - Character set to use (default: alphanumeric)
+ * @returns A random string
  */
-declare const dump: (...args: unknown[]) => void;
-//#endregion
-//#region src/Helpers/Number.d.ts
+declare const random: (length?: number, charset?: string) => string;
+/**
+ * Secure random string generator that uses crypto.randomBytes.
+ *
+ * @param length - Length of the random string (default: 32)
+ * @returns A cryptographically secure random string
+ */
+declare const randomSecure: (length?: number) => string;
+/**
+ * Hash a string using the specified algorithm.
+ *
+ * @param data - Data to hash
+ * @param algorithm - Hash algorithm (default: 'sha256')
+ * @returns Hexadecimal hash string
+ */
+declare const hash: (data: string, algorithm?: string) => string;
+/**
+ * Hash a string with salt using HMAC.
+ *
+ * @param data - Data to hash
+ * @param key - Secret key for HMAC
+ * @param algorithm - Hash algorithm (default: 'sha256')
+ * @returns Hexadecimal hash string
+ */
+declare const hmac: (data: string, key: string, algorithm?: string) => string;
+/**
+ * Encode data to base64.
+ *
+ * @param data - Data to encode
+ * @returns Base64 encoded string
+ */
+declare const base64Encode: (data: string) => string;
+/**
+ * Decode base64 data.
+ *
+ * @param data - Base64 string to decode
+ * @returns Decoded string
+ */
+declare const base64Decode: (data: string) => string;
+/**
+ * Simple XOR encryption/decryption.
+ *
+ * @param data - Data to encrypt/decrypt
+ * @param key - Encryption key
+ * @returns Encrypted/decrypted string
+ */
+declare const xor: (data: string, key: string) => string;
+/**
+ * Generate a random hex color code.
+ *
+ * @returns A hex color code string (e.g., '#a3b2f3')
+ */
+declare const randomColor: () => string;
+/**
+ * Generate a secure password using configurable parameters.
+ *
+ * @param length - Password length (default: 16)
+ * @param options - Character options
+ * @returns A secure password string
+ */
+interface PasswordOptions {
+  useUppercase?: boolean;
+  useLowercase?: boolean;
+  useNumbers?: boolean;
+  useSymbols?: boolean;
+}
+declare const randomPassword: (length?: number, options?: PasswordOptions) => string;
+/**
+ * Generate a cryptographically secure token for APIs, sessions, etc.
+ *
+ * @param strength - Token strength (bytes) (default: 32)
+ * @returns A secure token string
+ */
+declare const secureToken: (strength?: number) => string;
+/**
+ * Create a checksum for data integrity verification.
+ *
+ * @param data - Data to create checksum for
+ * @param algorithm - Hash algorithm (default: 'sha256')
+ * @returns SHA256 checksum
+ */
+declare const checksum: (data: string, algorithm?: string) => string;
+/**
+ * Verify data integrity using checksum.
+ *
+ * @param data - Data to verify
+ * @param expectedChecksum - Expected checksum
+ * @param algorithm - Hash algorithm (default: 'sha256')
+ * @returns True if checksums match
+ */
+declare const verifyChecksum: (data: string, expectedChecksum: string, algorithm?: string) => boolean;
+/**
+ * Simple Caesar cipher implementation.
+ *
+ * @param text - Text to encrypt/decrypt
+ * @param shift - Number of positions to shift (default: 13)
+ * @returns Encrypted/decrypted text
+ */
+declare const caesarCipher: (text: string, shift?: number) => string;
+declare namespace Number_d_exports {
+  export { abbreviate, humanize, toBytes, toHumanTime };
+}
 /**
  * Abbreviates large numbers using SI symbols (K, M, B...)
  * and formats the output according to the given locale.
@@ -95,8 +237,9 @@ declare const toBytes: (bytes?: number, decimals?: number, bits?: boolean) => st
  * @returns A formatted time string
  */
 declare const toHumanTime: (seconds?: number, worded?: boolean) => string;
-//#endregion
-//#region src/Helpers/Obj.d.ts
+declare namespace Obj_d_exports {
+  export { dot, extractProperties, getValue, modObj, safeDot, setNested, slugifyKeys };
+}
 /**
  * Flattens a nested object into a single-level object
  * with dot-separated keys.
@@ -175,8 +318,9 @@ declare const setNested: (obj: Record<string, any>, key: string, value: any) =>
  * @returns A new object with slugified keys
  */
 declare const slugifyKeys: <T extends object>(obj: T, only?: string[], separator?: string) => KeysToSnakeCase<T>;
-//#endregion
-//#region src/Helpers/Str.d.ts
+declare namespace Str_d_exports {
+  export { after, afterLast, before, beforeLast, capitalize, chop, esc, firstLines, isInteger, isNumber, lastLines, padString, pluralize, replacePunctuation, rot, singularize, slugify, split, ss, sub, subString, substitute, substr, translate, truncate };
+}
 /**
  * Get the portion of the string after the first occurrence of the given value.
  *
@@ -209,69 +353,264 @@ declare const before: (value: string, search: string) => string;
  * @returns
  */
 declare const beforeLast: (value: string, search: string) => string;
+/** Capitalizes the first character of a string. */
+declare function capitalize(str: string): string;
+/**
+ * Returns the pluralized form of a word based on the given number.
+ */
+declare const pluralize: (word: string, count: number) => string;
+/** Converts a plural English word into its singular form. */
+declare const singularize: (word: string) => string;
+/** Converts a string into a slug format. */
+declare const slugify: (str: string, joiner?: string) => string;
+/** Truncates a string to a specified length and appends an ellipsis if needed. */
+declare const subString: (str: string, len: number, ellipsis?: string) => string;
+/** Substitute placeholders { key } using object with dot notation. */
+declare const substitute: (str: string, data?: Record<string, unknown>, def?: string) => string | undefined;
+/** Truncate string removing HTML tags and append suffix if needed. */
+declare const truncate: (str: string, len?: number, suffix?: string) => string;
+/** Get substring from offset/length similar to PHP substr. */
+declare const substr: (string: string, offset: number, length?: number) => string;
+/** Get substring by start/stop indexes. */
+declare const sub: (string: string, start: number, stop: number) => string;
+/** Escape string for JSON encoding (returns string without quotes). */
+declare const esc: (string: string) => string;
+/** Padding to a fixed size, right by default. */
+declare const padString: (string: string, size: number, padString?: string, padRight?: boolean) => string;
+/** Split by delimiter with edge-case rule. */
+declare const split: (string: string, delimiter: string) => string[];
+/** Returns all the characters except the last. */
+declare const chop: (string: string) => string;
+/** Number checks. */
+declare const isNumber: (string: string) => boolean;
+declare const isInteger: (string: string) => boolean;
+/** ROT-N cipher. */
+declare const rot: (string: string, n?: number) => string;
+/** Replace trailing punctuation with new format. */
+declare const replacePunctuation: (string: string, newFormat: string) => string;
+/** Array/object driven text replacement. */
+declare const translate: (string: string, replacements: Record<string, string> | Array<[string, string]>) => string;
+/** Strip slashes recursively. */
+declare const ss: (string: string) => string;
+/** First and last N lines. */
+declare const firstLines: (string: string, amount?: number) => string;
+declare const lastLines: (string: string, amount?: number) => string;
+declare namespace Time_d_exports {
+  export { TimeFormat, TimeUnit, add, dayOfYear, diff, end, firstDayOfMonth, format, fromNow, fromTimestamp, isBetween, isLeapYear, lastDayOfMonth, now, randomTime, start, subtract, unix };
+}
+type TimeFormat = 'Y-m-d' | 'Y-m-d H:i:s' | 'd-m-Y' | 'd/m/Y' | 'M j, Y' | 'F j, Y' | 'D j M' | 'timestamp' | 'unix';
+type TimeUnit = 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days';
 /**
- * Capitalizes the first character of a string.
+ * Get current timestamp in milliseconds.
  *
- * @param str - The input string
- * @returns The string with the first character capitalized
+ * @returns Current timestamp as number
  */
-declare function capitalize(str: string): string;
+declare const now: () => number;
 /**
- * Returns the pluralized form of a word based on the given number.
+ * Get current Unix timestamp.
  *
- * @param word - The word to pluralize
- * @param count - The number determining pluralization
- * @returns Singular if count === 1, otherwise plural form
+ * @returns Current Unix timestamp
  */
-declare const pluralize: (word: string, count: number) => string;
+declare const unix: () => number;
 /**
- * Converts a plural English word into its singular form.
+ * Format a date string according to a specified format (UTC-based for determinism).
  *
- * @param word - The word to singularize
- * @returns The singular form of the word
+ * @param date - Date string or Date object
+ * @param format - Format to output (default: 'Y-m-d H:i:s')
+ * @returns Formatted date string
  */
-declare const singularize: (word: string) => string;
+declare const format: (date: string | Date, format?: TimeFormat) => string;
 /**
- * Converts a string into a slug format.
- * Handles camelCase, spaces, and non-alphanumeric characters.
+ * Create a date for a given timestamp.
  *
- * @param str - The input string to slugify
- * @param joiner - The character used to join words (default: "_")
- * @returns A slugified string
+ * @param timestamp - Unix timestamp
+ * @returns Date object
  */
-declare const slugify: (str: string, joiner?: string) => string;
+declare const fromTimestamp: (timestamp: number) => Date;
 /**
- * Truncates a string to a specified length and appends an ellipsis if needed.
+ * Return the difference for given date in seconds.
  *
- * @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
+ * @param date - Date to compare
+ * @param referenceDate - Reference date (optional, defaults to now)
+ * @returns Number of seconds difference
  */
-declare const subString: (str: string, len: number, ellipsis?: string) => string;
+declare const diff: (date: string | Date, referenceDate?: string | Date) => number;
+/**
+ * Subtract time from the given date.
+ */
+declare const subtract: (date: string | Date, amount?: number, unit?: TimeUnit) => Date;
+/**
+ * Add time to the given date.
+ */
+declare const add: (date: string | Date, amount?: number, unit?: TimeUnit) => Date;
+/**
+ * Start time of a specific unit.
+ */
+declare const start: (date: string | Date, unit?: TimeUnit) => Date;
+/**
+ * End time of a specific unit.
+ */
+declare const end: (date: string | Date, unit?: TimeUnit) => Date;
+/**
+ * Get the difference in days from today.
+ */
+declare const fromNow: (date: string | Date) => number;
 /**
- * Replaces placeholders in a string with corresponding values from a data object.
+ * Get a random time between the specified hour and minute.
+ */
+declare const randomTime: (startHour?: number, startMinute?: number, endHour?: number, endMinute?: number) => Date;
+/**
+ * Check if the current time is between the specified durations.
+ */
+declare const isBetween: (startTime: string, endTime: string) => boolean;
+/** Day of year, first/last day of month, leap year checks. */
+declare const dayOfYear: (date?: string | Date) => number;
+declare const firstDayOfMonth: (date?: string | Date) => Date;
+declare const lastDayOfMonth: (date?: string | Date) => Date;
+declare const isLeapYear: (year?: number) => boolean;
+//#endregion
+//#region src/Helpers/DumpDie.d.ts
+/**
+ * Dump something and kill the process for quick debugging. Based on Laravel's dd()
  *
- * Example:
- * substitute("Hello { user.name }!", { user: { name: "John" } })
- * // "Hello John!"
+ * @param args
+ */
+declare const dd: (...args: unknown[]) => never;
+/**
+ * Dump something but keep the process for quick debugging. Based on Laravel's dump()
  *
- * @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.
+ * @param args
  */
-declare const substitute: (str: string, data?: Record<string, unknown>, def?: string) => string | undefined;
+declare const dump: (...args: unknown[]) => void;
+//#endregion
+//#region src/GlobalBootstrap.d.ts
 /**
- * Truncates a string to a specified length, removing HTML tags and
- * appending a suffix if the string exceeds the length.
+ * Global helpers interface that mirrors Laravel's helpers
+ * and provides convenient access to all utility functions
+ */
+interface GlobalHelpers {
+  Arr: typeof Arr_d_exports;
+  chunk: typeof chunk;
+  collapse: typeof collapse;
+  alternate: typeof alternate;
+  combine: typeof combine;
+  find: typeof find;
+  forget: typeof forget;
+  first: typeof first;
+  last: typeof last;
+  isEmpty: typeof isEmpty;
+  isNotEmpty: typeof isNotEmpty;
+  pop: typeof pop;
+  prepend: typeof prepend;
+  take: typeof take;
+  reverse: typeof reverse;
+  shift: typeof shift;
+  range: typeof range;
+  flatten: typeof flatten;
+  Str: typeof Str_d_exports;
+  after: typeof after;
+  afterLast: typeof afterLast;
+  before: typeof before;
+  beforeLast: typeof beforeLast;
+  capitalize: typeof capitalize;
+  pluralize: typeof pluralize;
+  singularize: typeof singularize;
+  slugify: typeof slugify;
+  subString: typeof subString;
+  substitute: typeof substitute;
+  truncate: typeof truncate;
+  substr: typeof substr;
+  sub: typeof sub;
+  esc: typeof esc;
+  padString: typeof padString;
+  split: typeof split;
+  chop: typeof chop;
+  isNumber: typeof isNumber;
+  isInteger: typeof isInteger;
+  rot: typeof rot;
+  replacePunctuation: typeof replacePunctuation;
+  translate: typeof translate;
+  ss: typeof ss;
+  firstLines: typeof firstLines;
+  lastLines: typeof lastLines;
+  Obj: typeof Obj_d_exports;
+  dot: typeof dot;
+  extractProperties: typeof extractProperties;
+  getValue: typeof getValue;
+  modObj: typeof modObj;
+  safeDot: typeof safeDot;
+  setNested: typeof setNested;
+  slugifyKeys: typeof slugifyKeys;
+  Crypto: typeof Crypto_d_exports;
+  uuid: typeof uuid;
+  random: typeof random;
+  randomSecure: typeof randomSecure;
+  hash: typeof hash;
+  hmac: typeof hmac;
+  base64Encode: typeof base64Encode;
+  base64Decode: typeof base64Decode;
+  xor: typeof xor;
+  randomColor: typeof randomColor;
+  randomPassword: typeof randomPassword;
+  secureToken: typeof secureToken;
+  checksum: typeof checksum;
+  verifyChecksum: typeof verifyChecksum;
+  caesarCipher: typeof caesarCipher;
+  Time: typeof Time_d_exports;
+  now: typeof now;
+  unix: typeof unix;
+  format: typeof format;
+  fromTimestamp: typeof fromTimestamp;
+  diff: typeof diff;
+  subtract: typeof subtract;
+  add: typeof add;
+  start: typeof start;
+  end: typeof end;
+  fromNow: typeof fromNow;
+  randomTime: typeof randomTime;
+  isBetween: typeof isBetween;
+  dayOfYear: typeof dayOfYear;
+  firstDayOfMonth: typeof firstDayOfMonth;
+  lastDayOfMonth: typeof lastDayOfMonth;
+  isLeapYear: typeof isLeapYear;
+  Number: typeof Number_d_exports;
+  abbreviate: typeof abbreviate;
+  humanize: typeof humanize;
+  toBytes: typeof toBytes;
+  toHumanTime: typeof toHumanTime;
+  dump: typeof dump;
+  dd: typeof dd;
+}
+/**
+ * Bootstrap the global helpers into the global scope.
+ * This enables optional global access to all helper functions.
+ *
+ * Example usage:
+ * ```typescript
+ * import { bootstrap } from '@h3ravel/support'
  *
- * @param str - The string to truncate
- * @param len - Maximum length (default: 20)
- * @param suffix - Suffix to append if truncated (default: "...")
- * @returns The truncated string
+ * // Make helpers globally available
+ * bootstrap()
+ *
+ * // Now you can use:
+ * Arr.chunk([1, 2, 3, 4], 2)
+ * // or directly:
+ * chunk([1, 2, 3, 4], 2)
+ * Str.capitalize('hello world')
+ * // or directly:
+ * capitalize('hello world')
+ * ```
+ *
+ * @param target - The target object to attach helpers to (default: globalThis)
  */
-declare const truncate: (str: string, len?: number, suffix?: string) => string;
+declare function bootstrap(target?: any): void;
+/**
+ * Clean up global helpers by removing them from the global scope.
+ * This function removes all global helper attachments.
+ *
+ * @param target - The target object to clean up (default: globalThis)
+ */
+declare function cleanBootstrap(target?: any): void;
 //#endregion
-export { CamelToSnakeCase, KeysToSnakeCase, SnakeToCamelCase, SnakeToTitleCase, TGeneric, XGeneric, abbreviate, after, afterLast, before, beforeLast, capitalize, chunk, dd, dot, dump, extractProperties, getValue, humanize, modObj, pluralize, range, safeDot, setNested, singularize, slugify, slugifyKeys, subString, substitute, toBytes, toHumanTime, truncate };
+export { CamelToSnakeCase, GlobalHelpers, KeysToSnakeCase, PasswordOptions, SnakeToCamelCase, SnakeToTitleCase, TGeneric, TimeFormat, TimeUnit, XGeneric, abbreviate, add, after, afterLast, alternate, base64Decode, base64Encode, before, beforeLast, bootstrap, caesarCipher, capitalize, checksum, chop, chunk, cleanBootstrap, collapse, combine, dayOfYear, dd, diff, dot, dump, end, esc, extractProperties, find, first, firstDayOfMonth, firstLines, flatten, forget, format, fromNow, fromTimestamp, getValue, hash, hmac, humanize, isBetween, isEmpty, isInteger, isLeapYear, isNotEmpty, isNumber, last, lastDayOfMonth, lastLines, modObj, now, padString, pluralize, pop, prepend, random, randomColor, randomPassword, randomSecure, randomTime, range, replacePunctuation, reverse, rot, safeDot, secureToken, setNested, shift, singularize, slugify, slugifyKeys, split, ss, start, sub, subString, substitute, substr, subtract, take, toBytes, toHumanTime, translate, truncate, unix, uuid, verifyChecksum, xor };
 //# sourceMappingURL=index.d.cts.map