nhb-toolbox 4.26.66 → 4.26.69

package/CHANGELOG.md

@@ -6,6 +6,13 @@ All notable changes to the package will be documented here.
 
 ---
 
+## [4.26.69] - 2025-11-18
+
+- **Updated** *return type* of `sanitizeData` utility:
+  - **Fixed** *return type* when keys are ignored by *removing those keys* using `SanitizedData`, `OmitPath` and other new `type helpers`.
+  - **Fixed** the *return type* when it is called with `_return = 'partial'` parameter by *making all the nested properties optional*.
+    - **Created** new *utility type* `$DeepPartial` to satisfy this *return type*.
+
 ## [4.26.66] - 2025-11-17
 
 - **Changed** the signature of `Chronos` `get()` method to `get<Unit extends TimeUnit>(unit: Unit): TimeUnitValue<Unit>` to align with `set()` method.

package/dist/dts/object/sanitize.d.ts

@@ -1,5 +1,5 @@
-import type { Any, FlattenPartial, PartialOrRequired } from '../types/index';
-import type { GenericObject, SanitizeOptions } from './types';
+import type { Any, PartialOrRequired } from '../types/index';
+import type { DotNotationKey, GenericObject, SanitizedData, SanitizeOptions } from './types';
 /**
  * * Trims all the words in a string.
  *
@@ -23,7 +23,7 @@ export declare function sanitizeData(input: string[]): string[];
  * @param _return - By default return type is as it is, passing this parameter `true` makes the return type `Partial<T>`.
  * @returns A new object with the specified modifications.
  */
-export declare function sanitizeData<T extends GenericObject, B extends PartialOrRequired = 'required'>(object: T, options?: SanitizeOptions<T>, _return?: B): B extends 'partial' ? FlattenPartial<T> : T;
+export declare function sanitizeData<Data extends GenericObject, Ignored extends DotNotationKey<Data> = never, PoR extends PartialOrRequired = 'required'>(object: Data, options?: SanitizeOptions<Data, Ignored>, _return?: PoR): SanitizedData<Data, Ignored, PoR>;
 /**
  * * Sanitizes a deeply nested array that may contain arrays, objects or other (mixed) data types.
  * * Preserves structure while removing empty values and trimming strings and other operations.
@@ -33,7 +33,7 @@ export declare function sanitizeData<T extends GenericObject, B extends PartialO
  * @param _return - By default return type is as it is, passing this parameter `partial` makes the return type `Partial<T>`.
  * @returns A new sanitized array with the specified modifications.
  */
-export declare function sanitizeData<T extends GenericObject, B extends PartialOrRequired = 'required'>(array: T[], options?: SanitizeOptions<T>, _return?: B): B extends 'partial' ? FlattenPartial<T>[] : T[];
+export declare function sanitizeData<Data extends GenericObject, Ignored extends DotNotationKey<Data> = never, PoR extends PartialOrRequired = 'required'>(array: Data[], options?: SanitizeOptions<Data, Ignored>, _return?: PoR): Array<SanitizedData<Data, Ignored, PoR>>;
 /**
  * * Parse an object of stringified values into their appropriate primitive types.
  *

package/dist/dts/object/types.d.ts

@@ -1,5 +1,5 @@
-import type { AdvancedTypes, NormalPrimitive, ValidArray } from '../types/index';
-import type { $UnionToIntersection, Prettify, Split, Tuple } from '../utils/types';
+import type { AdvancedTypes, NormalPrimitive, PartialOrRequired, ValidArray } from '../types/index';
+import type { $DeepPartial, $UnionToIntersection, Prettify, Split, Tuple } from '../utils/types';
 import type { COUNTRIES } from './countries';
 /** - Generic object with `unknown` value */
 export type StrictObject = Record<string, unknown>;
@@ -103,13 +103,13 @@ export type DeepKeys<T extends GenericObject> = T extends AdvancedTypes ? never
 /** - Converts the union of keys from {@link DeepKeys<T>} into a tuple. */
 export type DeepKeysTuple<T extends GenericObject> = Tuple<DeepKeys<T>>;
 /** - Options for `sanitizeData` utility. */
-export interface SanitizeOptions<T> {
+export interface SanitizeOptions<T, Ignored extends DotNotationKey<T>> {
     /**
      * An array of dot-notation keys to exclude from the sanitized output.
      * This is only applicable when sanitizing plain objects or arrays of objects.
      * When applied to nested or irregular array structures, behavior may be inconsistent or partially ignored.
      */
-    keysToIgnore?: DotNotationKey<T>[];
+    keysToIgnore?: Ignored[];
     /** Whether to trim string values. Defaults to `true`. */
     trimStrings?: boolean;
     /** Whether to exclude nullish (`null` or `undefined`) values. Defaults to `false`. */
@@ -125,6 +125,85 @@ export interface SanitizeOptions<T> {
      */
     requiredKeys?: '*' | DotNotationKey<T>[];
 }
+/**
+ * * Produces sanitized output data by omitting keys in `keysToIgnore` from {@link SanitizeOptions} and optionally applying partial deep nesting based on `_return` parameter.
+ *
+ * @remarks
+ * - When `PoR` is `'partial'`, all nested properties become optional after path omission.
+ * - When `PoR` is `'required'`, the resulting type keeps full property requirements.
+ * - Intended for return type of `sanitizeData` utility.
+ */
+export type SanitizedData<Data extends GenericObject, Ignored extends DotNotationKey<Data>, PoR extends PartialOrRequired> = PoR extends 'partial' ? $DeepPartial<OmitPath<Data, Ignored>> : OmitPath<Data, Ignored>;
+/**
+ * * Extracts only the string keys from an object type.
+ *
+ * @remarks
+ * - Useful when iterating over object keys inside template-literal-based utility types,
+ * because TypeScript may include `symbol` keys in `keyof T`, which cannot be used in
+ * template literal types.
+ * - By filtering to `string`, all keys become safe for path operations.
+ *
+ * @example
+ * type A = { a: number; b: string; 1: boolean; [Symbol.iterator]: () => void };
+ * type Keys = ExtractStringKey<A>;
+ * // Result: "a" | "b"
+ */
+export type ExtractStringKey<T> = Extract<keyof T, string>;
+/**
+ * * Joins a parent key and a child key into a dot-notation path.
+ *
+ * @remarks
+ * - If the parent path is an empty string, the child key is returned as-is.
+ * - Otherwise, the function produces `"parent.child"` formatting.
+ *
+ * @example
+ * type A = $JoinDotKey<'', 'user'>;          // "user"
+ * type B = $JoinDotKey<'settings', 'theme'>; // "settings.theme"
+ */
+export type $JoinDotKey<Parent extends string, Key extends string> = Parent extends '' ? Key : `${Parent}.${Key}`;
+/**
+ * * Checks whether a dot-notation path starts with the specified prefix.
+ *
+ * @remarks
+ * A path is considered a match if it is **exactly equal** to the prefix, or begins with `"prefix."`.
+ *
+ * @example
+ * type A = $DoesPathStartWith<'settings.timeout', 'settings'>; // true
+ * type B = $DoesPathStartWith<'settings', 'settings'>;         // true
+ * type C = $DoesPathStartWith<'user.name', 'settings'>;        // false
+ */
+export type $DoesPathStartWith<Path extends string, Prefix extends string> = Path extends Prefix | `${Prefix}.${string}` ? true : false;
+/** Recursive utility that removes a specific dot-notation path from an object. */
+type $OmitPath<T extends GenericObject, I extends string, P extends string = ''> = Prettify<{
+    [K in ExtractStringKey<T> as $DoesPathStartWith<$JoinDotKey<P, K>, I> extends true ? never : K]: T[K] extends GenericObject ? T[K] extends AdvancedTypes ? T[K] : $OmitPath<T[K], I, $JoinDotKey<P, K>> : T[K];
+}>;
+/**
+ * * Removes a dot-notation path from an object type while preserving its original shape.
+ *
+ * @remarks
+ * - It excludes the specified dot path, but **retains the full structure** of the parent object.
+ * - Only the targeted property is removed.
+ *
+ * @example
+ * type Input = {
+ *   settings: {
+ *     timeout: number;
+ *     theme: string;
+ *   };
+ *   version: string;
+ * };
+ *
+ * type Clean = OmitPath<Input, "settings.timeout">;
+ *
+ * // Result:
+ * // {
+ * //   settings: {
+ * //     theme: string;
+ * //   };
+ * //   version: string;
+ * // }
+ */
+export type OmitPath<Object extends GenericObject, Ignored extends DotNotationKey<Object>> = $OmitPath<Object, Ignored>;
 /** Options for `convertObjectValues` utility */
 export interface ConvertObjectOptions<T extends GenericObject, Key extends NumericDotKey<T>, C extends 'string' | 'number'> {
     /** Array of keys (properties) to convert to `number` or `string` */

package/dist/dts/utils/types.d.ts

@@ -75,28 +75,45 @@ export type KeysOfUnion<T> = T extends T ? keyof T : never;
  * * Recursively makes all potential standard js object properties optional.
  *
  * @remarks
- * - It excludes complex types like `Array`, `Map`, `File`, `Date`, `Chronos` etc. from being recursively partial.
- * - Please, refer to {@link AdvancedTypes} to learn more about these complex types.
+ * - It excludes keys of complex types like `Array`, `Map`, `File`, `Date`, `Chronos` etc. from being recursively partial.
+ * - Please, refer to {@link AdvancedTypes} to allow these complex types.
+ * - Also refer to {@link $DeepPartial} for less strict version.
  *
  * @example
  * type Config = { a: string; nested: { b: number } };
  * type PartialConfig = DeepPartial<Config>;
  * // { a?: string; nested?: { b?: number } }
  */
-export type DeepPartial<T> = {
+export type DeepPartial<T> = Prettify<{
     [K in keyof T]?: T[K] extends AdvancedTypes ? T[K] : T[K] extends object ? DeepPartial<T[K]> : T[K];
-};
+}>;
+/**
+ * * Recursively makes all potential standard js object (also object in array) properties optional.
+ *
+ * @remarks
+ * - It excludes keys of complex types like `Map`, `File`, `Date`, `Chronos` etc. from being recursively partial.
+ * - Please, refer to {@link AdvancedTypes} to allow these complex types.
+ * - Also refer to {@link DeepPartial} for more strict version.
+ *
+ * @example
+ * type Config = { a: string; nested: { b: number }[] };
+ * type PartialConfig = $DeepPartial<Config>;
+ * // { a?: string; nested?: { b?: number; }[]; }
+ */
+export type $DeepPartial<T> = Prettify<{
+    [K in keyof T]?: T[K] extends Array<infer El> ? Array<$DeepPartial<El>> : T[K] extends AdvancedTypes ? T[K] : $DeepPartial<T[K]>;
+}>;
 /**
  * * Recursively makes all properties in any object or array type optional.
  *
  * @example
  * type Config = { a: string; nested: { b: number } };
- * type PartialConfig = DeepPartial<Config>;
+ * type PartialConfig = DeepPartialAll<Config>;
  * // { a?: string; nested?: { b?: number } }
  */
-export type DeepPartialAll<T> = T extends Array<infer El> ? Array<DeepPartialAll<El>> : {
+export type DeepPartialAll<T> = T extends Array<infer El> ? Array<DeepPartialAll<El>> : Prettify<{
     [K in keyof T]?: DeepPartialAll<T[K]>;
-};
+}>;
 /**
  * * Removes `readonly` modifiers from all properties of an object type.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.26.66",
+  "version": "4.26.69",
   "description": "A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",