Upload files to "/"

dist/modules/data/arrays.d.ts

@@ -0,0 +1,238 @@
+/**
+ * @file src/modules/data/arrays.ts
+ * @version 2.1.0
+ * @since 2.0.0
+ * @license GPL-3.0-or-later
+ * @copyright Sven Minio 2026
+ * @author Sven Minio <https://sven-minio.de>
+ * @category Data
+ * @description
+ * * Utility functions for array manipulation and data processing.
+ * @requires ./types
+ * * Depends on types.
+ */
+import { MatchMode } from './types';
+/**
+ * * Splits an array into smaller groups (chunks). Ideal for pagination or grid layouts.
+ * @example chunk([1, 2, 3, 4, 5], 2) => [[1, 2], [3, 4], [5]]
+ * @template T The type of the items in the array.
+ * @param array The source array.
+ * @param size The size of each chunk.
+ * @returns An array of arrays.
+ */
+export declare function chunk<T>(array: T[], size: number): T[][];
+/**
+ * * Merges multiple arrays into a single flat array.
+ * @example mergeArray([1, 2], [3, 4], [5]) => [1, 2, 3, 4, 5]
+ * @template T The type of the items in the arrays.
+ * @param arrays A list of arrays.
+ * @returns A new, merged array.
+ */
+export declare function mergeArray<T>(...arrays: T[][]): T[];
+/**
+ * * ALIAS for mergeArray (Consistency with object.merge)
+ */
+export declare const merge: typeof mergeArray;
+/**
+ * * Safely adds an element at a specific position without mutating the original array (Immutable).
+ * @example add([1, 2, 4], 3, 2) => [1, 2, 3, 4]
+ * @template T The type of the items in the array.
+ * @param array The array.
+ * @param item The item to add.
+ * @param index The position (default: end). Negative values count from the back (-1 = before the last one).
+ * @returns A new array including the element.
+ */
+export declare function add<T>(array: T[], item: T, index?: number): T[];
+/**
+ * * Clears the array and returns a new empty array (Immutable).
+ * @example clear([1, 2, 3]) => []
+ * @template T The type of the items in the array.
+ * @param array The array to clear.
+ * @returns A new empty array.
+ */
+export declare function clear<T>(array: T[]): T[];
+/**
+ * * ALIAS for clear.
+ */
+export declare const empty: typeof clear;
+/**
+ * * Creates a new array containing only the elements at the specified indices (Allowlist).
+ * * Mirrors object.pick.
+ * @example pick(['a', 'b', 'c', 'd'], [0, 2]) => ['a', 'c']
+ * @template T The type of the items in the array.
+ * @param array The source array.
+ * @param indices Array of indices to keep.
+ * @returns A new array with selected elements.
+ */
+export declare function pick<T>(array: T[], indices: number[]): T[];
+/**
+ * * Creates a new array containing all elements EXCEPT those at the specified indices (Blocklist).
+ * * Mirrors object.omit.
+ * @example omit(['a', 'b', 'c', 'd'], [1, 3]) => ['a', 'c']
+ * @template T The type of the items in the array.
+ * @param array The source array.
+ * @param indices Array of indices to remove.
+ * @returns A new array without the specified elements.
+ */
+export declare function omit<T>(array: T[], indices: number[]): T[];
+/**
+ * * Safely retrieves a value from a nested array/object structure (Safe Navigation).
+ * * Mirrors object.get.
+ * @example get(users, '0.profile.name') => Returns the name of the first user.
+ * @param array The array.
+ * @param path The path as a dot-notation string.
+ * @returns The found value or undefined.
+ */
+export declare function get(array: any[], path: string): any;
+/**
+ * * Sets a value deeply within a nested array/object structure.
+ * * Mirrors object.set.
+ * @example set(users, '0.profile.name', 'Sven')
+ * @param array The array to modify.
+ * @param path The path as a string (e.g., '0.profile.name').
+ * @param value The value to set.
+ */
+export declare function set(array: any[], path: string, value: any): void;
+/**
+ * * Removes elements based on index or match logic.
+ */
+export declare const remove: {
+    /**
+     * * Removes an element at a specific index.
+     * @example remove.at([1, 2, 3, 4], -2) => [1, 2, 4]
+     * @template T The type of the items in the array.
+     * @param array The array.
+     * @param index The index (negative values allowed).
+     * @returns A new array with the element removed.
+     */
+    at<T>(array: T[], index: number): T[];
+    /**
+     * * Removes the first element.
+     * @example remove.first([1, 2, 3]) => [2, 3]
+     * @template T The type of the items in the array.
+     * @param array The array.
+     */
+    first<T>(array: T[]): T[];
+    /**
+     * * Removes the last element.
+     * @example remove.last([1, 2, 3]) => [1, 2]
+     * @template T The type of the items in the array.
+     * @param array The array.
+     */
+    last<T>(array: T[]): T[];
+    /**
+     * * Removes all elements matching a query condition.
+     * @example remove.byMatch(users, 'Admin', 'exact', 'role')
+     * @template T The type of the items in the array.
+     * @param array The array.
+     * @param query The search query.
+     * @param mode The comparison mode ('exact', 'contains', 'startsWith', 'endsWith').
+     * @param key (Optional) The object key if it is an array of objects.
+     */
+    byMatch<T>(array: T[], query: string | number, mode?: MatchMode, key?: keyof T): T[];
+    /**
+     * * Removes the element at a specific index.
+     * * Mirrors object.remove.byKey.
+     * @example remove.byKey(['a', 'b', 'c'], 1) => ['a', 'c']
+     * @template T The type of the items in the array.
+     * @param array The source array.
+     * @param index The index (key) to remove.
+     * @returns A new array without the specified index.
+     */
+    byKey<T>(array: T[], index: number): T[];
+    /**
+     * * Removes all elements that match a specific value exactly (Strict Equality).
+     * * Mirrors object.remove.byValue.
+     * @example remove.byValue([1, 2, 1, 3], 1) => [2, 3]
+     * @template T The type of the items in the array.
+     * @param array The source array.
+     * @param value The value to remove.
+     * @returns A new array without the matching values.
+     */
+    byValue<T>(array: T[], value: T): T[];
+    /**
+     * * ALIAS for clear. Removes all elements.
+     * @param array The source array.
+     * @returns A new, empty array.
+     */
+    all<T>(array: T[]): T[];
+};
+/**
+ * * Searches for elements in the array.
+ */
+export declare const find: {
+    /**
+     * * Finds the index of the first match.
+     * @example find.at(['apple', 'banana', 'cherry'], 'an', 'contains') => 1
+     * @template T The type of the items in the array.
+     * @param array The array.
+     * @param query The search query.
+     * @param mode The comparison mode ('exact', 'contains', 'startsWith', 'endsWith').
+     * @param key (Optional) The object key if it is an array of objects.
+     * @returns Index or -1.
+     */
+    at<T>(array: T[], query: string | number, mode?: MatchMode, key?: keyof T): number;
+    /**
+     * * Returns all elements matching the condition (Filter).
+     * @example find.all(['apple', 'banana', 'cherry'], 'a', 'contains') => ['apple', 'banana']
+     * @template T The type of the items in the array.
+     * @param array The array.
+     * @param query The search query.
+     * @param mode The comparison mode ('exact', 'contains', 'startsWith', 'endsWith').
+     * @param key (Optional) The object key if it is an array of objects.
+     * @returns All matching elements or -1.
+     */
+    all<T>(array: T[], query: string | number, mode?: MatchMode, key?: keyof T): T[];
+    /**
+     * * Returns the first matching element (or undefined).
+     * @example find.first(['apple', 'banana', 'cherry'], 'a', 'contains') => 'apple'
+     * @template T The type of the items in the array.
+     * @param array The array.
+     * @param query The search query.
+     * @param mode The comparison mode ('exact', 'contains', 'startsWith', 'endsWith').
+     * @param key (Optional) The object key if it is an array of objects.
+     * @returns Index or -1.
+     */
+    first<T>(array: T[], query: string | number, mode?: MatchMode, key?: keyof T): T | undefined;
+    /**
+     * * Returns the last matching element (or undefined).
+     * @example find.last(['apple', 'banana', 'cherry'], 'a', 'contains') => 'banana'
+     * @template T The type of the items in the array.
+     * @param array The array.
+     * @param query The search query.
+     * @param mode The comparison mode ('exact', 'contains', 'startsWith', 'endsWith').
+     * @param key (Optional) The object key if it is an array of objects.
+     * @returns Index or -1.
+     */
+    last<T>(array: T[], query: string | number, mode?: MatchMode, key?: keyof T): T | undefined;
+    /**
+     * * Finds all indices (keys) matching the query.
+     * * Mirrors object.find.key(). For arrays, keys are the indices.
+     * @param array The array to search.
+     * @param query The search query.
+     * @param mode The comparison mode.
+     * @returns An array of matching indices as strings.
+     */
+    key<T>(array: T[], query: string, mode?: MatchMode): string[];
+    /**
+     * * Finds all values matching the query.
+     * * Mirrors object.find.value(). Identical to find.all() for flat arrays.
+     * @param array The array to search.
+     * @param query The search query.
+     * @param mode The comparison mode.
+     * @returns An array of matching values.
+     */
+    value<T>(array: T[], query: string, mode?: MatchMode): T[];
+    /**
+     * * Finds the key of the first match based on the query condition.
+     * @example find.byMatch(users, 'Admin', 'exact', 'role') => 0
+     * @template T The type of the items in the array.
+     * @param array The array.
+     * @param query The search query.
+     * @param mode The comparison mode ('exact', 'contains', 'startsWith', 'endsWith').
+     * @param key (Optional) The object key if it is an array of objects.
+     * @returns Index or -1.
+     */
+    byMatch<T>(array: T[], query: string | number, mode?: MatchMode, key?: keyof T): number | undefined;
+};
+//# sourceMappingURL=arrays.d.ts.map

dist/modules/data/arrays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrays.d.ts","sourceRoot":"","sources":["../../../src/modules/data/arrays.ts"],"names":[],"mappings":"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"}

dist/modules/data/index.d.ts

@@ -0,0 +1,227 @@
+/**
+ * @file src/modules/data/index.ts
+ * @version 2.1.0
+ * @since 2.0.0
+ * * @license GPL-3.0-or-later
+ * @copyright Sven Minio 2026
+ * @author Sven Minio <https://sven-minio.de>
+ * @category Data
+ * @description
+ * * Central entry point for data manipulation.
+ * * Features a dynamic, overloaded API router that automatically delegates
+ * * to array or object utilities based on the input type.
+ * @requires ./arrays
+ * * Array manipulation methods.
+ * @requires ./objects
+ * * Object manipulation methods.
+ */
+import * as arr from './arrays';
+import * as obj from './objects';
+import { MatchMode } from './types';
+/**
+ * * Splits an array or object into smaller chunks (batched processing).
+ * @param data The source array or object.
+ * @param size The maximum size/length of each chunk.
+ * @returns An array containing the chunked arrays or partial objects.
+ */
+declare function chunk<T>(array: T[], size: number): T[][];
+declare function chunk<T extends Record<string, any>>(object: T, size: number): Partial<T>[];
+/**
+ * * Merges multiple arrays (flat) or objects (deep merge) into a single structure.
+ * @param data The target array or object.
+ * @param args The source arrays or objects to merge.
+ * @returns The newly merged array or modified target object.
+ */
+declare function merge(...arrays: any[][]): any[];
+declare function merge(target: any, ...sources: any[]): any;
+/**
+ * * Safely adds an element/property at a specific index without mutating the original structure (Immutable).
+ * @param data The source array or object.
+ * @param arg1 The item to add (array) or the key to add (object).
+ * @param arg2 The index (array) or the value to add (object).
+ * @param arg3 The index (object only).
+ * @returns A new array or object including the added element.
+ */
+declare function add<T>(array: T[], item: T, index?: number): T[];
+declare function add<T extends Record<string, any>>(object: T, key: string, value: any, index?: number): T & Record<string, any>;
+/**
+ * * Clears the array or object and returns a new empty one (Immutable).
+ * @param data The array or object to clear.
+ * @returns A new empty array `[]` or object `{}`.
+ */
+declare function clear<T>(array: T[]): T[];
+declare function clear<T extends Record<string, any>>(object: T): Partial<T>;
+/**
+ * * Creates a new array or object containing ONLY the specified indices/keys (Allowlist).
+ * @param data The source array or object.
+ * @param keysOrIndices Array of keys (object) or indices (array) to keep.
+ * @returns A new filtered array or object.
+ */
+declare function pick<T>(array: T[], indices: number[]): T[];
+declare function pick<T extends object, K extends keyof T>(object: T, keys: K[]): Pick<T, K>;
+/**
+ * * Creates a new array or object containing all elements EXCEPT the specified indices/keys (Blocklist).
+ * @param data The source array or object.
+ * @param keysOrIndices Array of keys (object) or indices (array) to remove.
+ * @returns A new filtered array or object.
+ */
+declare function omit<T>(array: T[], indices: number[]): T[];
+declare function omit<T extends object, K extends keyof T>(object: T, keys: K[]): Omit<T, K>;
+/**
+ * * Safely retrieves a value from a nested array/object structure using dot-notation.
+ * @param data The source array or object.
+ * @param path The path string (e.g., 'settings.theme' or '0.profile.name').
+ * @returns The found value or undefined if any part is missing.
+ */
+declare function get(array: any[], path: string): any;
+declare function get(object: any, path: string): any;
+/**
+ * * Sets a value deeply within a nested structure. Creates missing objects/arrays automatically.
+ * @param data The array or object to modify.
+ * @param path The path string (e.g., 'settings.theme').
+ * @param value The value to set.
+ */
+declare function set(array: any[], path: string, value: any): void;
+declare function set(object: any, path: string, value: any): void;
+/**
+ * * Removes an entry/element at a specific index (Immutable).
+ * @param data The source array or object.
+ * @param index The index to remove (negative values count from the end).
+ * @returns A new array or object without the specified element.
+ */
+declare function removeAt<T>(array: T[], index: number): T[];
+declare function removeAt<T extends Record<string, any>>(object: T, index: number): Partial<T>;
+/**
+ * * Removes the first entry/element (Immutable).
+ * @param data The source array or object.
+ * @returns A new array or object without the first element.
+ */
+declare function removeFirst<T>(array: T[]): T[];
+declare function removeFirst<T extends Record<string, any>>(object: T): Partial<T>;
+/**
+ * * Removes the last entry/element (Immutable).
+ * @param data The source array or object.
+ * @returns A new array or object without the last element.
+ */
+declare function removeLast<T>(array: T[]): T[];
+declare function removeLast<T extends Record<string, any>>(object: T): Partial<T>;
+/**
+ * * Removes all entries/elements matching a query condition (Immutable). Acts as an inverse filter.
+ * @param data The source array or object.
+ * @param query The search term.
+ * @param mode Comparison mode ('exact', 'contains', 'startsWith', 'endsWith').
+ * @returns A new array or object containing only the non-matching elements.
+ */
+declare function removeByMatch<T>(array: T[], query: string | number, mode?: MatchMode, key?: keyof T): T[];
+declare function removeByMatch<T extends Record<string, any>>(object: T, query: string | number, mode?: MatchMode, searchBy?: 'key' | 'value'): Partial<T>;
+/**
+ * * Removes a specific element by its index (arrays) or key (objects) (Immutable).
+ * @param data The source array or object.
+ * @param keyOrIndex The index or key string to remove.
+ * @returns A new array or object without the specified property/element.
+ */
+declare function removeByKey<T>(array: T[], index: number): T[];
+declare function removeByKey<T extends Record<string, any>>(object: T, key: string): Partial<T>;
+/**
+ * * Removes all elements/entries that match a specific value exactly (Immutable).
+ * @param data The source array or object.
+ * @param value The exact value to remove (strict equality).
+ * @returns A new array or object without the matching values.
+ */
+declare function removeByValue<T>(array: T[], value: T): T[];
+declare function removeByValue<T extends Record<string, any>>(object: T, value: any): Partial<T>;
+/**
+ * * Arrays: Finds the index of the first match. Objects: Returns the n-th [key, value] tuple.
+ * @param data The array or object to search.
+ * @param arg1 Query term (array) or numeric index (object).
+ * @returns The index (array) or tuple (object), or undefined.
+ */
+declare function findAt<T>(array: T[], query: string | number, mode?: MatchMode, key?: keyof T): number;
+declare function findAt(object: any, index: number): [string, any] | undefined;
+/**
+ * * Returns ALL elements/entries matching the condition. Similar to filter().
+ * @param data The array or object to search.
+ * @param query The search term.
+ * @param mode Comparison mode ('exact', 'contains', 'startsWith', 'endsWith').
+ * @returns A new array or partial object containing the matching elements.
+ */
+declare function findAll<T>(array: T[], query: string | number, mode?: MatchMode, key?: keyof T): T[];
+declare function findAll<T extends Record<string, any>>(object: T, query: string | number, mode?: MatchMode, searchBy?: 'key' | 'value'): Partial<T>;
+/**
+ * * Returns the FIRST matching element (array) or [key, value] tuple (object).
+ * @param data The array or object to search.
+ * @param query The search term.
+ * @returns The found element/tuple or undefined.
+ */
+declare function findFirst<T>(array: T[], query: string | number, mode?: MatchMode, key?: keyof T): T | undefined;
+declare function findFirst(object: any, query: string | number, mode?: MatchMode, searchBy?: 'key' | 'value'): [string, any] | undefined;
+/**
+ * * Returns the LAST matching element (array) or [key, value] tuple (object). Searches in reverse.
+ * @param data The array or object to search.
+ * @param query The search term.
+ * @returns The found element/tuple or undefined.
+ */
+declare function findLast<T>(array: T[], query: string | number, mode?: MatchMode, key?: keyof T): T | undefined;
+declare function findLast(object: any, query: string | number, mode?: MatchMode, searchBy?: 'key' | 'value'): [string, any] | undefined;
+/**
+ * * Finds all matching indices (arrays) or keys (objects) based on the query.
+ * @param data The array or object to search.
+ * @param query The search term.
+ * @returns An array of matching stringified keys/indices.
+ */
+declare function findKey<T>(array: T[], query: string, mode?: MatchMode): string[];
+declare function findKey(object: any, query: string, mode?: MatchMode): string[];
+/**
+ * * Finds all matching values within the array or object.
+ * @param data The array or object to search.
+ * @param query The search term.
+ * @returns An array of matching values.
+ */
+declare function findValue<T>(array: T[], query: string, mode?: MatchMode): T[];
+declare function findValue(object: any, query: string, mode?: MatchMode): any[];
+/**
+ * * Finds the index (array) or key (object) of the first match based on the query condition.
+ * @param data The array or object to search.
+ * @param query The search term.
+ * @returns The matching index/key or undefined.
+ */
+declare function findByMatch<T>(array: T[], query: string | number, mode?: MatchMode, key?: keyof T): number | undefined;
+declare function findByMatch(object: any, query: string | number, mode?: MatchMode, searchBy?: 'key' | 'value'): string | undefined;
+/**
+ * * Central data utility object.
+ * * Dynamically routes to array or object methods based on input.
+ * * Backward compatibility for strict calls is maintained via `.arr` and `.obj`.
+ */
+export declare const data: {
+    arr: typeof arr;
+    obj: typeof obj;
+    chunk: typeof chunk;
+    merge: typeof merge;
+    add: typeof add;
+    clear: typeof clear;
+    empty: typeof clear;
+    pick: typeof pick;
+    omit: typeof omit;
+    get: typeof get;
+    set: typeof set;
+    remove: {
+        at: typeof removeAt;
+        first: typeof removeFirst;
+        last: typeof removeLast;
+        byKey: typeof removeByKey;
+        byValue: typeof removeByValue;
+        byMatch: typeof removeByMatch;
+        all: typeof clear;
+    };
+    find: {
+        at: typeof findAt;
+        all: typeof findAll;
+        first: typeof findFirst;
+        last: typeof findLast;
+        key: typeof findKey;
+        value: typeof findValue;
+        byMatch: typeof findByMatch;
+    };
+};
+export {};
+//# sourceMappingURL=index.d.ts.map

dist/modules/data/objects.d.ts

@@ -0,0 +1,223 @@
+/**
+ * @file src/modules/data/objects.ts
+ * @version 2.1.0
+ * @since 2.0.0
+ * @license GPL-3.0-or-later
+ * @copyright Sven Minio 2026
+ * @author Sven Minio <https://sven-minio.de>
+ * @category Data
+ * @description
+ * * Utility functions for object manipulation (e.g., deep merging, extension).
+ * @requires ./types
+ * * Depends on types.
+ * @requires src/utils
+ * * Depends on utility functions (e.g., each).
+ */
+import { MatchMode } from './types';
+/**
+ * * Recursively merges multiple objects (Deep Merge).
+ * @example mergeObjects({ a: 1, b: { x: 1 } }, { b: { y: 2 } }) => { a: 1, b: { x: 1, y: 2 } }
+ * @param target The target object (will be modified!).
+ * @param sources One or more source objects.
+ * @returns The modified target object.
+ */
+export declare function mergeObjects(target: any, ...sources: any[]): any;
+/**
+ * * ALIAS for mergeObjects (Consistency with array.mergeArray)
+ */
+export declare const merge: typeof mergeObjects;
+/**
+ * * Splits an object into an array of smaller objects (chunks). Ideal for batched processing.
+ * @example chunk({a: 1, b: 2, c: 3}, 2) => [{a: 1, b: 2}, {c: 3}]
+ * @param obj The source object.
+ * @param size The maximum number of keys per chunk.
+ * @returns An array of partial objects.
+ */
+export declare function chunk<T extends Record<string, any>>(obj: T, size: number): Partial<T>[];
+/**
+ * * Safely adds a key-value pair at a specific index without mutating the original object (Immutable).
+ * * Note: While JS object key order is generally insertion-based, relying on it is not always recommended.
+ * @example add({a: 1, c: 3}, 'b', 2, 1) => {a: 1, b: 2, c: 3}
+ * @param obj The object.
+ * @param key The key to add.
+ * @param value The value to add.
+ * @param index The position (default: end). Negative values count from the back.
+ * @returns A new object including the element at the specified position.
+ */
+export declare function add<T extends Record<string, any>>(obj: T, key: string, value: any, index?: number): T & Record<string, any>;
+/**
+ * * Clears the object and returns a new empty object (Immutable).
+ * @example clear({ a: 1, b: 2 }) => {}
+ * @template T The type of the object.
+ * @param obj The object to clear.
+ * @returns A new empty object.
+ */
+export declare function clear<T extends Record<string, any>>(obj: T): Partial<T>;
+/**
+ * * ALIAS for clear.
+ */
+export declare const empty: typeof clear;
+/**
+ * * Creates a new object containing only the specified keys (Allowlist).
+ * @example pick({ a: 1, b: 2, c: 3 }, ['a', 'c']) => { a: 1, c: 3 }
+ * @param obj The source object.
+ * @param keys Array of keys to keep.
+ * @returns A new object with selected keys.
+ */
+export declare function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+/**
+ * * Creates a new object containing all keys EXCEPT the specified ones (Blocklist).
+ * @example omit({ a: 1, b: 2, c: 3 }, ['b']) => { a: 1, c: 3 }
+ * @param obj The source object.
+ * @param keys Array of keys to remove.
+ * @returns A new object without the specified keys.
+ */
+export declare function omit<T, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+/**
+ * * Safely retrieves a value from a nested object (Safe Navigation).
+ * @example get(config, 'settings.theme.color') => Returns the value of config.settings.theme.color or undefined if any part is missing.
+ * @param obj The object.
+ * @param path The path as a dot-notation string.
+ * @returns The found value or undefined.
+ */
+export declare function get(obj: any, path: string): any;
+/**
+ * * Sets a value deeply within a nested object. Creates missing intermediate objects automatically.
+ * @example set(config, 'settings.theme.color', 'dark') => Sets config.settings.theme.color to 'dark', creating objects if needed.
+ * @param obj The object to modify.
+ * @param path The path as a string (e.g., 'settings.theme.color').
+ * @param value The value to set.
+ */
+export declare function set(obj: any, path: string, value: any): void;
+/**
+ * * Removes elements from an object based on index or match logic (Immutable).
+ * * Mirrors the array.remove API.
+ */
+export declare const remove: {
+    /**
+     * * Removes an entry at a specific index.
+     * @example remove.at({a: 1, b: 2, c: 3}, -1) => {a: 1, b: 2}
+     * @param obj The source object.
+     * @param index The index (negative values allowed).
+     * @returns A new object with the element removed.
+     */
+    at<T extends Record<string, any>>(obj: T, index: number): Partial<T>;
+    /**
+     * * Removes the first entry from the object.
+     * @param obj The source object.
+     * @returns A new object without the first entry.
+     */
+    first<T extends Record<string, any>>(obj: T): Partial<T>;
+    /**
+     * * Removes the last entry from the object.
+     * @param obj The source object.
+     * @returns A new object without the last entry.
+     */
+    last<T extends Record<string, any>>(obj: T): Partial<T>;
+    /**
+     * * Removes all entries matching a query condition.
+     * @example remove.byMatch(config, 'hidden', 'exact', 'key')
+     * @param obj The source object.
+     * @param query The search query.
+     * @param mode The comparison mode ('exact', 'contains', 'startsWith', 'endsWith').
+     * @param searchBy Whether to search by 'key' or 'value' (default: 'key').
+     * @returns A new object without the matching elements.
+     */
+    byMatch<T extends Record<string, any>>(obj: T, query: string | number, mode?: MatchMode, searchBy?: "key" | "value"): Partial<T>;
+    /**
+     * * Removes all entries that have a specific key.
+     * @example remove.byKey({ a: 1, b: 2, c: 3 }, 'b') => { a: 1, c: 3 }
+     * @param obj The source object.
+     * @param key The key to remove.
+     * @returns A new object without the specified key.
+     */
+    byKey<T extends Record<string, any>>(obj: T, key: string): Partial<T>;
+    /**
+     * * Removes all entries that match a specific value exactly (Strict Equality).
+     * @example remove.byValue({ a: 1, b: 2, c: 1 }, 1) => { b: 2 }
+     * @param obj The source object.
+     * @param value The value to remove.
+     * @returns A new object without the matching values.
+     */
+    byValue<T extends Record<string, any>>(obj: T, value: any): Partial<T>;
+    /**
+     * * ALIAS for clear. Removes all entries.
+     * @param obj The source object.
+     * @returns A new, empty object.
+     */
+    all<T extends Record<string, any>>(obj: T): Partial<T>;
+};
+/**
+ * * Searches keys or values in the object.
+ */
+export declare const find: {
+    /**
+     * * Returns the n-th entry of an object as a [key, value] pair. Supports negative indices.
+     * @example find.at({ a: 1, b: 2 }, 1) => ['b', 2]
+     * @param obj The object to search.
+     * @param index The index (0-based, negative counts from the back).
+     * @returns A [key, value] tuple or undefined.
+     */
+    at(obj: any, index: number): [string, any] | undefined;
+    /**
+     * * Returns a NEW OBJECT containing ALL elements matching the condition.
+     * * Mirrors array.find.all() but returns a partial object.
+     * @example find.all({a: 1, b: 2, c: 1}, 1, 'exact', 'value') => {a: 1, c: 1}
+     * @param obj The object to search.
+     * @param query The search query.
+     * @param mode The comparison mode ('exact', 'contains', 'startsWith', 'endsWith').
+     * @param searchBy Whether to search by 'key' or 'value' (default: 'key').
+     * @returns A new object with only the matching elements.
+     */
+    all<T extends Record<string, any>>(obj: T, query: string | number, mode?: MatchMode, searchBy?: "key" | "value"): Partial<T>;
+    /**
+     * * Finds the first entry where the key or value matches the query.
+     * @example find.first(config, 'admin', 'exact', 'key')
+     * @param obj The object to search.
+     * @param query The search query.
+     * @param mode The comparison mode ('exact', 'contains', 'startsWith', 'endsWith').
+     * @param searchBy Whether to search by 'key' or 'value'.
+     * @returns The first matching [key, value] pair or undefined.
+     */
+    first(obj: any, query: string | number, mode?: MatchMode, searchBy?: "key" | "value"): [string, any] | undefined;
+    /**
+     * * Finds the last entry where the key or value matches the query.
+     * @example find.last(config, '.php', 'endsWith', 'key')
+     * @param obj The object to search.
+     * @param query The search query.
+     * @param mode The comparison mode ('exact', 'contains', 'startsWith', 'endsWith').
+     * @param searchBy Whether to search by 'key' or 'value'.
+     * @returns The last matching [key, value] pair or undefined.
+     */
+    last(obj: any, query: string | number, mode?: MatchMode, searchBy?: "key" | "value"): [string, any] | undefined;
+    /**
+     * * Finds all keys matching the query.
+     * @example find.key(config, 'api_', 'startsWith')
+     * @param obj The object to search.
+     * @param query The search query.
+     * @param mode The comparison mode ('exact', 'contains', 'startsWith', 'endsWith').
+     * @returns An array of matching keys.
+     */
+    key(obj: any, query: string, mode?: MatchMode): string[];
+    /**
+     * * Finds all values matching the query.
+     * @example find.value(config, 'enabled', 'exact')
+     * @param obj The object to search.
+     * @param query The search query.
+     * @param mode The comparison mode ('exact', 'contains', 'startsWith', 'endsWith').
+     * @returns An array of matching values.
+     */
+    value(obj: any, query: string, mode?: MatchMode): any[];
+    /**
+     * * Finds the key of the first match based on the query condition.
+     * * Mirrors array.find.byMatch(). For objects, it returns the key instead of a numeric index.
+     * @example find.byMatch(config, 'admin', 'exact', 'value') => 'role'
+     * @param obj The object to search.
+     * @param query The search query.
+     * @param mode The comparison mode ('exact', 'contains', 'startsWith', 'endsWith').
+     * @param searchBy Whether to search by 'key' or 'value' (default: 'key').
+     * @returns The matched key as a string, or undefined if no match is found.
+     */
+    byMatch(obj: any, query: string | number, mode?: MatchMode, searchBy?: "key" | "value"): string | undefined;
+};
+//# sourceMappingURL=objects.d.ts.map

dist/modules/data/objects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"objects.d.ts","sourceRoot":"","sources":["../../../src/modules/data/objects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAapC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE,GAAG,GAAG,CAkBhE;AAED;;GAEG;AACH,eAAO,MAAM,KAAK,qBAAe,CAAC;AAElC;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAQvF;AAED;;;;;;;;;GASG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,GAAE,MAAgC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAKpJ;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEvE;AAED;;GAEG;AACH,eAAO,MAAM,KAAK,cAAQ,CAAC;AAE3B;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAMvF;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAMxE;AAED;;;;;;GAMG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAE/C;AAED;;;;;;GAMG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAS5D;AAED;;;GAGG;AACH,eAAO,MAAM,MAAM;IACf;;;;;;OAMG;OACA,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,SAAS,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IASpE;;;;OAIG;UACG,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAKxD;;;;OAIG;SACE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAKvD;;;;;;;;OAQG;YACK,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,SAAS,MAAM,GAAG,MAAM,SAAQ,SAAS,aAAsB,KAAK,GAAG,OAAO,GAAW,OAAO,CAAC,CAAC,CAAC;IAgBhJ;;;;;;OAMG;UACG,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAMrE;;;;;;OAMG;YACK,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,SAAS,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC;IAKtE;;;;OAIG;QACC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAGzD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,IAAI;IACb;;;;;;OAMG;YACK,GAAG,SAAS,MAAM,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAMtD;;;;;;;;;OASG;QACC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,SAAS,MAAM,GAAG,MAAM,SAAQ,SAAS,aAAsB,KAAK,GAAG,OAAO,GAAW,OAAO,CAAC,CAAC,CAAC;IAgB5I;;;;;;;;OAQG;eACQ,GAAG,SAAS,MAAM,GAAG,MAAM,SAAQ,SAAS,aAAsB,KAAK,GAAG,OAAO,GAAW,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAkBhI;;;;;;;;OAQG;cACO,GAAG,SAAS,MAAM,GAAG,MAAM,SAAQ,SAAS,aAAsB,KAAK,GAAG,OAAO,GAAW,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAkB/H;;;;;;;OAOG;aACM,GAAG,SAAS,MAAM,SAAQ,SAAS,GAAa,MAAM,EAAE;IAejE;;;;;;;OAOG;eACQ,GAAG,SAAS,MAAM,SAAQ,SAAS,GAAa,GAAG,EAAE;IAehE;;;;;;;;;OASG;iBACU,GAAG,SAAS,MAAM,GAAG,MAAM,SAAQ,SAAS,aAAsB,KAAK,GAAG,OAAO,GAAW,MAAM,GAAG,SAAS;CAmB9H,CAAC"}

dist/modules/data/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file src/modules/data/types.ts
+ * @version 2.0.3
+ * @since 2.0.0
+ * @license GPL-3.0-or-later
+ * @copyright Sven Minio 2026
+ * @author Sven Minio <https://sven-minio.de>
+ * @category Data
+ * @description
+ * * Type definitions and validation helpers for data structures.
+ */
+/**
+ * * Defines the matching modes for search operations.
+ */
+export type MatchMode = 'exact' | 'contains' | 'startsWith' | 'endsWith';
+//# sourceMappingURL=types.d.ts.map

dist/modules/data/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/data/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,CAAC"}