nhb-toolbox 4.12.26 → 4.12.27

package/CHANGELOG.md

@@ -6,6 +6,11 @@ All notable changes to this package will be documented in this file.
 
 ---
 
+## [4.12.27] - 2025-06-02
+
+- Updated [README](README.md).
+- Added new utility types, can be imported from `'nhb-toolbox/utils/types'`.
+
 ## [4.12.25-26] - 2025-06-02
 
 - Updated JSDoc for some `Chronos` methods and exposed `INTERNALS` Symbol

package/README.md

@@ -72,6 +72,8 @@ See [Changelog](CHANGELOG.md) for recent updates.
 
 The ultimate date/time manipulation class with 100+ methods for parsing, formatting, calculating, and comparing dates. Handles all edge cases and timezones safely.
 
+> 🧩 **Note**: Some methods in `Chronos` are available only through the [plugin system](https://nhb-toolbox.vercel.app/docs/classes/Chronos/plugins#-official-plugins). This modular design ensures the core bundle stays lightweight — plugins are loaded only when needed, reducing unnecessary code in your final build.
+
 ```typescript
 new Chronos('2025-01-01').addDays(3).format('YYYY-MM-DD'); // "2025-01-04"
 ```
@@ -134,6 +136,37 @@ getColorForInitial('Banana', 50); // '#00376E80' (50% opacity)
 
 [Documentation →](https://nhb-toolbox.vercel.app/docs/utilities/color/getColorForInitial)
 
+### FormData Preparation
+
+Convert JavaScript objects into `FormData` with extensive configuration options for handling nested structures, files, and data transformations.
+
+```typescript
+import { createFormData } from 'nhb-toolbox';
+
+const formData = createFormData({
+  user: {
+    name: ' John Doe ',
+    age: 30,
+    preferences: { theme: 'dark' }
+  },
+  files: [file1, file2]
+}, {
+  trimStrings: true,
+  lowerCaseValues: ['user.name'],
+  dotNotateNested: ['user.preferences'],
+  breakArray: ['files']
+});
+
+// Resulting FormData:
+// user.name=john doe
+// user.age=30
+// user.preferences.theme=dark
+// files[0]=[File1]
+// files[1]=[File2]
+```
+
+[Documentation →](https://nhb-toolbox.vercel.app/docs/utilities/form/createFormData)
+
 ### 🛡️ **Sanitize Data**
 
 Clean and normalize strings/objects by trimming whitespace, removing empty values, and applying customizable filters.

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

@@ -38,4 +38,163 @@ export interface PageListOptions {
     /** Number of siblings pages to show around the current page (default 1). */
     siblingCount?: number;
 }
+/**
+ * * Extracts the union of all property value types from a given object type.
+ *
+ * @example
+ * type Colors = { primary: string; secondary: string; id: number; };
+ * type ColorValues = ValueOf<Colors>; // string | number
+ */
+export type ValueOf<T> = T[keyof T];
+/**
+ * * Gets all keys from a union of object types.
+ *
+ * @example
+ * type A = { a: string };
+ * type B = { b: number };
+ * type Union = A | B;
+ * type Keys = KeysOfUnion<Union>; // "a" | "b"
+ */
+export type KeysOfUnion<T> = T extends T ? keyof T : never;
+/**
+ * * Recursively makes all properties in an object type optional.
+ *
+ * @example
+ * type Config = { a: string; nested: { b: number } };
+ * type PartialConfig = DeepPartial<Config>;
+ * // { a?: string; nested?: { b?: number } }
+ */
+export type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+/**
+ * * Removes `readonly` modifiers from all properties of an object type.
+ *
+ * @example
+ * type ReadonlyObj = { readonly id: number };
+ * type WritableObj = Mutable<ReadonlyObj>;
+ * // { id: number }
+ */
+export type Mutable<T> = {
+    -readonly [K in keyof T]: T[K];
+};
+/**
+ * * Recursively adds `readonly` to all properties of an object type.
+ *
+ * @example
+ * type State = { user: { id: number } };
+ * type ReadonlyState = Immutable<State>;
+ * // { readonly user: { readonly id: number } }
+ */
+export type Immutable<T> = {
+    readonly [K in keyof T]: Immutable<T[K]>;
+};
+/**
+ * * Combines two object types. In case of conflicts, keys from `U` override `T`.
+ *
+ * @example
+ * type A = { id: number; name: string };
+ * type B = { name: boolean; active: boolean };
+ * type Merged = Merge<A, B>;
+ * // { id: number; name: boolean; active: boolean }
+ */
+export type Merge<T, U> = {
+    [K in keyof T | keyof U]: K extends keyof U ? U[K] : K extends keyof T ? T[K] : never;
+};
+/**
+ * * Omits properties from an object type whose value types match `ValueType`.
+ *
+ * @example
+ * type Model = { id: number; name: string; hidden: boolean };
+ * type VisibleModel = OmitByValue<Model, boolean>;
+ * // { id: number; name: string }
+ */
+export type OmitByValue<T, ValueType> = {
+    [K in keyof T as T[K] extends ValueType ? never : K]: T[K];
+};
+/**
+ * * Makes only the specified keys in a type required; others remain optional.
+ *
+ * @example
+ * type User = { id?: number; name?: string };
+ * type UserWithId = RequireOnly<User, 'id'>;
+ * // { id: number; name?: string }
+ */
+export type RequireOnly<T, K extends keyof T> = Partial<T> & Required<Pick<T, K>>;
+/**
+ * * Forces TypeScript to simplify a complex or inferred type into a more readable flat object.
+ *
+ * *Useful when working with utility types like `Merge`, `Omit`, etc., that produce deeply nested or unresolved intersections.*
+ *
+ * @example
+ * type A = { a: number };
+ * type B = { b: string };
+ * type Merged = A & B;
+ * type Pretty = Prettify<Merged>;
+ * // Type will now display as: { a: number; b: string }
+ */
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * * Broadens a literal union (typically `string` or `number`) to also accept any other value of the base type, without losing IntelliSense autocomplete for the provided literals.
+ *
+ * *This is especially useful in API design where you want to provide suggestions for common options but still allow flexibility for custom user-defined values.*
+ *
+ * @example
+ * // ✅ String literal usage
+ * type Variant = LooseLiteral<'primary' | 'secondary'>;
+ * const v1: Variant = 'primary';  // suggested
+ * const v2: Variant = 'custom';   // also valid
+ *
+ * // ✅ Number literal usage
+ * type StatusCode = LooseLiteral<200 | 404 | 500>;
+ * const s1: StatusCode = 200;     // suggested
+ * const s2: StatusCode = 999;     // also valid
+ *
+ * // ✅ Mixed literal
+ * type Mixed = LooseLiteral<'one' | 2>;
+ * const m1: Mixed = 'one';        // ✅
+ * const m2: Mixed = 2;            // ✅
+ * const m3: Mixed = 'anything';   // ✅
+ * const m4: Mixed = 123;          // ✅
+ *
+ * @note Technically, this uses intersection with primitive base types (`string & {}` or `number & {}`) to retain IntelliSense while avoiding type narrowing.
+ */
+export type LooseLiteral<T extends string | number> = T | (T extends string ? string & {} : number & {});
+/**
+ * * Extracts an object type containing only the optional keys from `T`.
+ *
+ * @template T - The original object type
+ * @returns A new object type with only optional keys from `T`
+ * @example
+ * type Example = { a: string; b?: number; c?: boolean };
+ * type OptionalPart = OptionalShape<Example>;
+ * // { b?: number; c?: boolean }
+ */
+export type OptionalShape<T> = {
+    [K in keyof T as {} extends Pick<T, K> ? K : never]?: T[K];
+};
+/**
+ * * Extracts an object type containing only the required keys from `T`.
+ *
+ * @template T - The original object type
+ * @returns A new object type with only required keys from `T`
+ * @example
+ * type Example = { a: string; b?: number; c: boolean };
+ * type RequiredPart = RequiredShape<Example>;
+ * // { a: string; c: boolean }
+ */
+export type RequiredShape<T> = {
+    [K in keyof T as {} extends Pick<T, K> ? never : K]: T[K];
+};
+/**
+ * * Converts a readonly tuple to a union of its element types.
+ *
+ * @template T - A tuple type (must be readonly if using `as const`)
+ * @example
+ * const roles = ['admin', 'user', 'guest'] as const;
+ * type Role = TupleToUnion<typeof roles>; // "admin" | "user" | "guest"
+ */
+export type TupleToUnion<T extends readonly unknown[]> = T[number];
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAChC,iCAAiC;IACjC,UAAU,EAAE,OAAO,CAAC;IACpB,mDAAmD;IACnD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,yBAAyB;AACzB,MAAM,WAAW,aAAa;IAC7B,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,OAAO,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,MAAM,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;CACf;AAED,qCAAqC;AACrC,MAAM,MAAM,eAAe,GAAG,IAAI,CACjC,aAAa,EACb,YAAY,GAAG,cAAc,GAAG,aAAa,CAC7C,CAAC;AAEF,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC/B,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/utils/types.ts"],"names":[],"mappings":"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"}

package/package.json

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