@alessiofrittoli/type-utils 1.10.1 → 2.1.0

package/README.md

@@ -1,43 +1,76 @@
-# Type Utils ❇️
+<h1 align="center">Type Utils ❇️</h1>
+<h2 align="center">
+  Lightweight TypeScript types utilities
+</h2>
+<p align="center">
+  <a href="https://npmjs.org/package/@alessiofrittoli/type-utils">
+    <img src="https://img.shields.io/npm/v/@alessiofrittoli/type-utils" alt="Latest version"/>
+  </a>
+  <a href="https://socket.dev/npm/package/@alessiofrittoli/type-utils/overview">
+    <img src="https://socket.dev/api/badge/npm/package/@alessiofrittoli/type-utils" alt="Socket Security score"/>
+  </a>
+  <a href="https://npmjs.org/package/@alessiofrittoli/type-utils">
+    <img src="https://img.shields.io/npm/dm/@alessiofrittoli/type-utils.svg" alt="npm downloads"/>
+  </a>
+  <a href="https://bundlephobia.com/package/@alessiofrittoli/type-utils">
+    <img src="https://badgen.net/bundlephobia/dependency-count/@alessiofrittoli/type-utils" alt="Dependencies"/>
+  </a>
+  <a href="https://libraries.io/npm/%40alessiofrittoli%2Ftype-utils">
+    <img src="https://img.shields.io/librariesio/release/npm/@alessiofrittoli/type-utils" alt="Dependencies status"/>
+  </a>
+</p>
+<p align="center">
+  <a href="https://bundlephobia.com/package/@alessiofrittoli/type-utils">
+    <img src="https://badgen.net/bundlephobia/min/@alessiofrittoli/type-utils" alt="minified"/>
+  </a>
+  <a href="https://bundlephobia.com/package/@alessiofrittoli/type-utils">
+    <img src="https://badgen.net/bundlephobia/minzip/@alessiofrittoli/type-utils" alt="minizipped"/>
+  </a>
+  <a href="https://bundlephobia.com/package/@alessiofrittoli/type-utils">
+    <img src="https://badgen.net/bundlephobia/tree-shaking/@alessiofrittoli/type-utils" alt="Tree shakable"/>
+  </a>
+</p>
+<p align="center">
+  <a href="https://github.com/sponsors/alessiofrittoli">
+    <img src="https://img.shields.io/static/v1?label=Fund%20this%20package&message=%E2%9D%A4&logo=GitHub&color=%23DB61A2" alt="Fund this package"/>
+  </a>
+</p>
 
-[![NPM Latest Version][version-badge]][npm-url] [![Socket Status][socket-badge]][socket-url] [![NPM Monthly Downloads][downloads-badge]][npm-url] [![Dependencies][deps-badge]][deps-url]
-
-[![GitHub Sponsor][sponsor-badge]][sponsor-url]
-
-[version-badge]: https://img.shields.io/npm/v/%40alessiofrittoli%2Ftype-utils
-[npm-url]: https://npmjs.org/package/%40alessiofrittoli%2Ftype-utils
-[socket-badge]: https://socket.dev/api/badge/npm/package/@alessiofrittoli/type-utils
-[socket-url]: https://socket.dev/npm/package/@alessiofrittoli/type-utils/overview
-[downloads-badge]: https://img.shields.io/npm/dm/%40alessiofrittoli%2Ftype-utils.svg
-[deps-badge]: https://img.shields.io/librariesio/release/npm/%40alessiofrittoli%2Ftype-utils
-[deps-url]: https://libraries.io/npm/%40alessiofrittoli%2Ftype-utils
 [sponsor-badge]: https://img.shields.io/static/v1?label=Fund%20this%20package&message=%E2%9D%A4&logo=GitHub&color=%23DB61A2
 [sponsor-url]: https://github.com/sponsors/alessiofrittoli
 
-## Lightweight TypeScript types utilities
-
-### Table of Contents
+### Table of Content
 
 - [Getting started](#getting-started)
+  - [Utility types usage](#utility-types-usage)
+  - [Global extenders setup](#global-extenders-setup)
+- [Development](#development)
+  - [Local development](#local-development)
+  - [Production build](#production-build)
+  - [Lint](#lint)
+  - [Contributing](#contributing)
+  - [Security](#security)
 - [Utility types](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md)
   - [ValueOf](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md#valueof)
   - [ValueOfKey](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md#valueofkey)
   - [OptionalKey](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md#optionalkey)
+  - [ReadOnly](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md#readonly)
   - [Writeable](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md#writeable)
   - [RenameKey](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md#renamekey)
-  - [ArgumentTypes](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md#argumenttypes)
+  - [DeepPartial](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md#deeppartial)
+  - [Full](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md#full)
+  - [DeepFull](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md#deepfull)
+  - [NonNullableFields](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md#nonnullablefields)
+  - [MergedEnumValue](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md#mergedenumvalue)
+  - [UnflatDotKeys](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md#unflatdotkeys)
+  - [RecursivelyUnflatDotKeys](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md#recursivelyunflatdotkeys)
+  - [ArgumentTypes](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md#argumenttypes) (deprecated)
 - [Extenders types](https://github.com/alessiofrittoli/type-utils/blob/master/docs/extenders/README.md)
   - [JSON](https://github.com/alessiofrittoli/type-utils/blob/master/docs/extenders/README.md#json)
     - [JSON.stringify\<T\>()](https://github.com/alessiofrittoli/type-utils/blob/master/docs/extenders/README.md#jsonstringifyt)
     - [JSON.parse\<T\>()](https://github.com/alessiofrittoli/type-utils/blob/master/docs/extenders/README.md#jsonparset)
   - [Body](https://github.com/alessiofrittoli/type-utils/blob/master/docs/extenders/README.md#body)
     - [Body.json\<T\>()](https://github.com/alessiofrittoli/type-utils/blob/master/docs/extenders/README.md#bodyjsont)
-- [Development](#development)
-  - [Install dependencies](#install-dependencies)
-  - [Build the source code](#build-the-source-code)
-  - [ESLint](#eslint)
-- [Contributing](#contributing)
-- [Security](#security)
 - [Credits](#made-with-)
 
 ---
@@ -56,64 +89,94 @@ or using `pnpm`
 pnpm i @alessiofrittoli/type-utils
 ```
 
-This tiny library defines some global types which are not imported in your IDE by default.\
-After installation a `postinstall` script is executed to create the `alessiofrittoli-env.d.ts` file at the root of your project.
-This script will try to update your `tsconfig.json` file.
+#### Utility types usage
+
+Utility types are exported from the package entry point and can be imported where needed:
+
+```ts
+import type { DeepPartial, ValueOf } from '@alessiofrittoli/type-utils'
+```
 
-If that fail, please, make sure to add `alessiofrittoli-env.d.ts` in the array of the "include" property in your `tsconfig.json`.
+See the [Utility types docs](https://github.com/alessiofrittoli/type-utils/blob/master/docs/utils/README.md) for the full list.
+
+#### Global extenders setup
+
+[Extenders types](https://github.com/alessiofrittoli/type-utils/blob/master/docs/extenders/README.md) augment built-in global interfaces (such as `JSON` and `Body`) and they are the only global types defined by this library. Global types are not loaded by your IDE by default.
+
+After installation a `postinstall` script is executed to create (or update) the `globals.d.ts` file at the root of your project, adding the following globals types reference:
+
+```ts
+/// <reference types="@alessiofrittoli/type-utils/globals" />
+```
+
+If the file get ignored by the TypeScript program of your project, please, manually add `globals.d.ts` in the array of the "include" property in your `tsconfig.json`.
 
 ```json
 {
     "compilerOptions": {
         ...
     },
-    "include": [ ..., "alessiofrittoli-env.d.ts" ],
+    "include": [ ..., "globals.d.ts" ],
 }
 ```
 
 You can skip this process if `*.ts` is already in your "include" array.
 
-⚠️ If the `alessiofrittoli-env.d.ts` file creation fails you can run the following command to manually execute the script:
+⚠️ If the `globals.d.ts` file creation fails you can run the following command to manually execute the script:
 
 ```bash
-node node_modules/@alessiofrittoli/type-utils/scripts/postinstall/index.js
+node node_modules/@alessiofrittoli/type-utils/scripts/postinstall/index.cjs
 ```
 
+💡 If you don't want to use the global extenders, simply remove the reference above from your `globals.d.ts` file. Utility types will keep working since they are imported explicitly.
+
 ---
 
 ### Development
 
-#### Install dependencies
+Run the following to start development
 
-```bash
-npm install
+```shell
+nvm use
+
+pnpm i
 ```
 
-or using `pnpm`
+#### Local development
 
-```bash
-pnpm i
+Run the following
+
+```shell
+pnpm dev
 ```
 
-#### Build the source code
+This will generate unminified output code, sourcemaps and will enable source file watcher.
 
-Run the following command to test and build code for distribution.
+---
 
-```bash
+#### Production build
+
+Run the following to create a local production build
+
+```shell
 pnpm build
 ```
 
-#### [ESLint](https://www.npmjs.com/package/eslint)
+This will lint and type-check the source code, then generate minified output code without sourcemaps.
 
-Run warnings and errors checks.
+---
 
-```bash
+#### Lint
+
+Run warnings and errors checks with [oxlint](https://oxc.rs/docs/guide/usage/linter):
+
+```shell
 pnpm lint
 ```
 
 ---
 
-### Contributing
+#### Contributing
 
 Contributions are truly welcome!
 
@@ -125,10 +188,12 @@ Help keep this project up to date with [GitHub Sponsor][sponsor-url].
 
 ---
 
-### Security
+#### Security
 
 If you believe you have found a security vulnerability, we encourage you to **_responsibly disclose this and NOT open a public issue_**. We will investigate all legitimate reports. Email `security@alessiofrittoli.it` to disclose any security vulnerabilities.
 
+---
+
 ### Made with ☕
 
 <table style='display:flex;gap:20px;'>

package/dist/globals/index.d.cts

@@ -0,0 +1,17 @@
+declare class Stringified<T> extends String {
+  private ___stringified;
+}
+declare global {
+  interface JSON {
+    stringify<T>(value: T, replacer?: (this: {
+      '': T;
+    } | T, key: string, value: T) => any, space?: string | number): T extends Date ? string : string & Stringified<T>;
+    stringify<T>(value: T, replacer?: (T extends object ? (keyof T)[] : (number | string)[]) | null, space?: string | number): T extends Date ? string : string & Stringified<T>;
+    parse<T, U extends keyof T = keyof T>(text: string | Stringified<T>, reviver?: (key: U, value: T[U]) => any): T;
+    parse(text: string, reviver?: (key: any, value: any) => any): any;
+  }
+  interface Body {
+    json<T = any>(): Promise<T>;
+  }
+}
+export {};

package/dist/globals/index.d.mts

@@ -0,0 +1,17 @@
+declare class Stringified<T> extends String {
+  private ___stringified;
+}
+declare global {
+  interface JSON {
+    stringify<T>(value: T, replacer?: (this: {
+      '': T;
+    } | T, key: string, value: T) => any, space?: string | number): T extends Date ? string : string & Stringified<T>;
+    stringify<T>(value: T, replacer?: (T extends object ? (keyof T)[] : (number | string)[]) | null, space?: string | number): T extends Date ? string : string & Stringified<T>;
+    parse<T, U extends keyof T = keyof T>(text: string | Stringified<T>, reviver?: (key: U, value: T[U]) => any): T;
+    parse(text: string, reviver?: (key: any, value: any) => any): any;
+  }
+  interface Body {
+    json<T = any>(): Promise<T>;
+  }
+}
+export {};

package/dist/globals/index.mjs

@@ -0,0 +1 @@
+export{};

package/dist/index.d.cts

@@ -1,104 +1,204 @@
-//#region src/globals/extenders/json.d.ts
-declare class Stringified<T> extends String {
-  private ___stringified;
-}
-declare global {
-  interface JSON {
-    stringify<T>(value: T, replacer?: (this: {
-      '': T;
-    } | T, key: string, value: T) => any, space?: string | number): T extends Date ? string : string & Stringified<T>;
-    stringify<T>(value: T, replacer?: (T extends object ? (keyof T)[] : (number | string)[]) | null, space?: string | number): T extends Date ? string : string & Stringified<T>;
-    parse<T, U extends keyof T = keyof T>(text: string | Stringified<T>, reviver?: (key: U, value: T[U]) => any): T;
-    parse(text: string, reviver?: (key: any, value: any) => any): any;
-  }
-  interface Body {
-    json<T = any>(): Promise<T>;
-  }
-}
-//#endregion
-//#region src/globals/utils/index.d.ts
-declare global {
-  /**
-   * Get the Type of the Value of a object/array property.
-   */
-  type ValueOf<T> = T[keyof T];
-  /**
-   * Get the Type of the Value of object/array specific property.
-   */
-  type ValueOfKey<T, P extends keyof T> = T[P];
-  /**
-   * Make a specific property optional.
-   */
-  type OptionalKey<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
-  /**
-   * Make read-only properties of an object recursively writeable.
-   */
-  type ReadOnly<T> = keyof T extends never ? T : { readonly [P in keyof T]: Writeable<T[P]>; };
-  /**
-   * Make read-only properties of an object recursively writeable.
-   */
-  type Writeable<T> = keyof T extends never ? T : { -readonly [P in keyof T]: Writeable<T[P]>; };
-  /**
-   * Renames a property while inheriting its type.
-   */
-  type RenameKey<T, K extends keyof T, R extends PropertyKey> = Omit<T, K> & { [P in R]: T[K]; };
-  /** Get the Type of a function arguments. */
-  type ArgumentTypes<F extends Function> = F extends ((...args: infer A) => any) ? A : never;
-  /**
-   * Makes all 1st level properties of a type required.
-   */
-  type Full<T> = { [P in keyof T]-?: T[P]; };
-  /**
-   * Recursively makes all properties of a type required at all nested levels.
-   */
-  type DeepFull<T> = { [P in keyof T]-?: DeepFull<T[P]>; };
-  /**
-   * Removes `null` and `undefined` from all properties of a type.
-   */
-  type NonNullableFields<T> = { [P in keyof T]: NonNullable<T[P]>; };
-  /**
-   * Get the type of the value of merged enums.
-   *
-   * @example
-   *
-   * ```ts
-   * enum Mammals {
-   * 	Humans,
-   * 	Bats,
-   * 	Dolphins
-   * }
-   *
-   * enum Reptiles {
-   * 	Snakes,
-   * 	Alligators,
-   * 	Lizards
-   * }
-   *
-   * // merged enums.
-   * const Animals = { Mammals, Reptiles }
-   * type Animals = typeof Animals
-   *
-   * type Animal = MergedEnumValueType<typeof Animals>
-   *
-   * const testAnimal: Animal = 0 as any
-   *
-   * switch ( testAnimal ) {
-   * 	case Animals.Mammals.Humans:
-   * 	case Animals.Mammals.Bats:
-   * 	case Animals.Mammals.Dolphins:
-   * 	case Animals.Reptiles.Snakes:
-   * 	case Animals.Reptiles.Alligators:
-   * 	case Animals.Reptiles.Lizards:
-   * 		break
-   * 	default: {
-   * 		const invalid = testAnimal // `testAnimal` is type of never
-   * 	}
-   * }
-   * ```
-   */
-  type MergedEnumValue<T> = { [K in keyof T]: { [K2 in keyof T[K]]: T[K][K2]; }[keyof T[K]]; }[keyof T];
-}
-//#endregion
-//#region src/index.d.ts
-export type DoNotUse = never;
-//#endregion
+type RequiredKey<T> = { [K in keyof T]-?: object extends Pick<T, K> ? never : K; }[keyof T];
+type Head<K> = K extends `${infer H}.${string}` ? H : never;
+/**
+ * Picks the `${P}.*` keys of `T`, stripping the `${P}.` prefix. When `P` is `never`, `T` is returned as is.
+ *
+ * __INTERNAL__
+ */
+type PickDotKeys<T, P extends string> = [P] extends [never] ? T : { [K in keyof T as K extends `${P}.${infer R}` ? R : never]: T[K]; };
+/**
+ * When `Deep` is `true`, unflattens plain object values, leaving functions, arrays and primitives untouched.
+ *
+ * __INTERNAL__
+ */
+type UnflatValue<V, Deep extends boolean> = Deep extends false ? V : V extends ((...args: any[]) => unknown) | readonly unknown[] ? V : V extends object ? Unflat<V, Deep> : V;
+/**
+ * Turns dotted keys into nested objects. A nested object is required when at least one of its keys is required.
+ *
+ * __INTERNAL__
+ */
+type Unflat<T, Deep extends boolean> = { [K in keyof T as K extends `${string}.${string}` ? never : K]: UnflatValue<T[K], Deep>; } & { [H in Head<Extract<RequiredKey<T>, string>>]: Unflat<PickDotKeys<T, H>, Deep>; } & { [H in Exclude<Head<keyof T>, Head<Extract<RequiredKey<T>, string>>>]?: Unflat<PickDotKeys<T, H>, Deep>; };
+/**
+ * Turns dotted keys (`"a.b"?: T`) into nested objects (`a?: { b?: T }`).
+ *
+ * @template T The object interface to work with.
+ * @template K The object interface specific key to work with (`${P}.*`).
+ */
+type UnflatDotKeys<T, K extends string = never> = Unflat<PickDotKeys<T, K>, false>;
+/**
+ * Same as {@link UnflatDotKeys}, but dotted keys of nested object values are unflattened too.
+ *
+ * @template T The object interface to work with.
+ * @template K The object interface specific key to work with (`${K}.*`).
+ */
+type RecursivelyUnflatDotKeys<T, K extends string = never> = Unflat<PickDotKeys<T, K>, true>;
+/**
+ * Get the Type of the Value of a object/array property.
+ *
+ */
+export type ValueOf<T> = T[keyof T];
+/**
+ * Get the Type of the Value of object/array specific property.
+ *
+ */
+export type ValueOfKey<T, P extends keyof T> = T[P];
+/**
+ * Make a specific property optional.
+ *
+ */
+export type OptionalKey<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
+/**
+ * Recursively set to `readonly` all properties of the given type/interface.
+ *
+ * @template T The type/interface where each property will be set to `readonly`.
+ */
+export type ReadOnly<T> = keyof T extends never ? T : { readonly [k in keyof T]: ReadOnly<T[k]>; };
+/**
+ * Make read-only properties of an object recursively writeable.
+ *
+ */
+export type Writeable<T> = keyof T extends never ? T : { -readonly [P in keyof T]: Writeable<T[P]>; };
+/**
+ * Renames a property while inheriting its type and modifiers (`?` and `readonly`).
+ *
+ * @example
+ * ```ts
+ * interface User {
+ * 	// the user name
+ * 	name?: string
+ * 	// the user age
+ * 	age: number
+ * }
+ *
+ * type ModifiedUser = RenameKey<User, 'name', 'username'>
+ * // { username?: string, age: number }
+ * ```
+ */
+export type RenameKey<T, K extends keyof T, R extends PropertyKey> = { [P in keyof T as P extends K ? R : P]: T[P]; };
+/**
+ * Get the Type of a function arguments.
+ *
+ * @deprecated use `Parameters` instead.
+ */
+export type ArgumentTypes<F extends Function> = F extends ((...args: infer A) => any) ? A : never;
+/**
+ * Recursively convert to optional all properties of the given type/interface.
+ *
+ * @template T The type/interface where each property will be set as optional.
+ */
+export type DeepPartial<T> = T extends ((...args: any[]) => unknown) ? T : T extends object ? { [P in keyof T]?: DeepPartial<T[P]>; } : T;
+/**
+ * Makes all 1st level properties of a type required.
+ *
+ */
+export type Full<T> = { [P in keyof T]-?: T[P]; };
+/**
+ * Recursively makes all properties of a type required at all nested levels.
+ *
+ */
+export type DeepFull<T> = { [P in keyof T]-?: DeepFull<T[P]>; };
+/**
+ * Removes `null` and `undefined` from all properties of a type.
+ *
+ */
+export type NonNullableFields<T> = { [P in keyof T]: NonNullable<T[P]>; };
+/**
+ * Get the type of the value of merged enums.
+ *
+ * @example
+ *
+ * ```ts
+ * enum Mammals {
+ * 	Humans,
+ * 	Bats,
+ * 	Dolphins
+ * }
+ *
+ * enum Reptiles {
+ * 	Snakes,
+ * 	Alligators,
+ * 	Lizards
+ * }
+ *
+ * // merged enums.
+ * const Animals = { Mammals, Reptiles }
+ * type Animals = typeof Animals
+ *
+ * type Animal = MergedEnumValueType<typeof Animals>
+ *
+ * const testAnimal: Animal = 0 as any
+ *
+ * switch ( testAnimal ) {
+ * 	case Animals.Mammals.Humans:
+ * 	case Animals.Mammals.Bats:
+ * 	case Animals.Mammals.Dolphins:
+ * 	case Animals.Reptiles.Snakes:
+ * 	case Animals.Reptiles.Alligators:
+ * 	case Animals.Reptiles.Lizards:
+ * 		break
+ * 	default: {
+ * 		const invalid = testAnimal // `testAnimal` is type of never
+ * 	}
+ * }
+ * ```
+ */
+export type MergedEnumValue<T> = { [K in keyof T]: { [K2 in keyof T[K]]: T[K][K2]; }[keyof T[K]]; }[keyof T];
+/**
+ * Builds a discriminated union of `[event, args]` tuples from an event map.
+ *
+ * Each key of the given map becomes a tuple whose first element is the event name
+ * and whose second element is its payload type. Since the tuples are discriminated
+ * by the event name, checking `event` narrows `args` to the matching payload.
+ *
+ * @template M The event map, where each key is an event name and each value is its payload type.
+ *
+ * @example
+ * ```ts
+ * interface Events {
+ * 	play: { position: number }
+ * 	error: Error
+ * }
+ *
+ * type OnEventHandler = (...args: MappedArgs<Events>) => void
+ *
+ * const onEvent: OnEventHandler = (event, args): void => {
+ * 	if (event === 'play') {
+ * 		console.log(args.position) // `args` is narrowed to `{ position: number }`
+ * 	}
+ * 	if (event === 'error') {
+ * 		console.log(args) // `args` is narrowed to `Error`
+ * 	}
+ * }
+ *
+ * onEvent('play', { position: 0 })
+ * onEvent('error', new Error())
+ * ```
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * interface Events {
+ * 	play: [data: { position: number }]
+ * 	error: [error: Error]
+ * }
+ *
+ * type OnEventHandler = (...args: MappedArgs<Events>) => void
+ *
+ * const onEvent: OnEventHandler = (event, args): void => {
+ * 	if (event === 'play') {
+ * 		const [payload] = args
+ * 		console.log(payload.position) // `args` is narrowed to [`{ position: number }`]
+ * 	}
+ * 	if (event === 'error') {
+ * 		const [error] = args // `args` is narrowed to [`Error`]
+ * 		console.log(error)
+ * 	}
+ * }
+ *
+ * onEvent('play', [{ position: 0 }])
+ * onEvent('error', [new Error()])
+ * ```
+ */
+export type MappedArgs<M> = { [K in keyof M]: [event: K, args: M[K]]; }[keyof M];
+export type { RecursivelyUnflatDotKeys, UnflatDotKeys };

package/dist/index.d.mts

@@ -1,104 +1,204 @@
-//#region src/globals/extenders/json.d.ts
-declare class Stringified<T> extends String {
-  private ___stringified;
-}
-declare global {
-  interface JSON {
-    stringify<T>(value: T, replacer?: (this: {
-      '': T;
-    } | T, key: string, value: T) => any, space?: string | number): T extends Date ? string : string & Stringified<T>;
-    stringify<T>(value: T, replacer?: (T extends object ? (keyof T)[] : (number | string)[]) | null, space?: string | number): T extends Date ? string : string & Stringified<T>;
-    parse<T, U extends keyof T = keyof T>(text: string | Stringified<T>, reviver?: (key: U, value: T[U]) => any): T;
-    parse(text: string, reviver?: (key: any, value: any) => any): any;
-  }
-  interface Body {
-    json<T = any>(): Promise<T>;
-  }
-}
-//#endregion
-//#region src/globals/utils/index.d.ts
-declare global {
-  /**
-   * Get the Type of the Value of a object/array property.
-   */
-  type ValueOf<T> = T[keyof T];
-  /**
-   * Get the Type of the Value of object/array specific property.
-   */
-  type ValueOfKey<T, P extends keyof T> = T[P];
-  /**
-   * Make a specific property optional.
-   */
-  type OptionalKey<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
-  /**
-   * Make read-only properties of an object recursively writeable.
-   */
-  type ReadOnly<T> = keyof T extends never ? T : { readonly [P in keyof T]: Writeable<T[P]>; };
-  /**
-   * Make read-only properties of an object recursively writeable.
-   */
-  type Writeable<T> = keyof T extends never ? T : { -readonly [P in keyof T]: Writeable<T[P]>; };
-  /**
-   * Renames a property while inheriting its type.
-   */
-  type RenameKey<T, K extends keyof T, R extends PropertyKey> = Omit<T, K> & { [P in R]: T[K]; };
-  /** Get the Type of a function arguments. */
-  type ArgumentTypes<F extends Function> = F extends ((...args: infer A) => any) ? A : never;
-  /**
-   * Makes all 1st level properties of a type required.
-   */
-  type Full<T> = { [P in keyof T]-?: T[P]; };
-  /**
-   * Recursively makes all properties of a type required at all nested levels.
-   */
-  type DeepFull<T> = { [P in keyof T]-?: DeepFull<T[P]>; };
-  /**
-   * Removes `null` and `undefined` from all properties of a type.
-   */
-  type NonNullableFields<T> = { [P in keyof T]: NonNullable<T[P]>; };
-  /**
-   * Get the type of the value of merged enums.
-   *
-   * @example
-   *
-   * ```ts
-   * enum Mammals {
-   * 	Humans,
-   * 	Bats,
-   * 	Dolphins
-   * }
-   *
-   * enum Reptiles {
-   * 	Snakes,
-   * 	Alligators,
-   * 	Lizards
-   * }
-   *
-   * // merged enums.
-   * const Animals = { Mammals, Reptiles }
-   * type Animals = typeof Animals
-   *
-   * type Animal = MergedEnumValueType<typeof Animals>
-   *
-   * const testAnimal: Animal = 0 as any
-   *
-   * switch ( testAnimal ) {
-   * 	case Animals.Mammals.Humans:
-   * 	case Animals.Mammals.Bats:
-   * 	case Animals.Mammals.Dolphins:
-   * 	case Animals.Reptiles.Snakes:
-   * 	case Animals.Reptiles.Alligators:
-   * 	case Animals.Reptiles.Lizards:
-   * 		break
-   * 	default: {
-   * 		const invalid = testAnimal // `testAnimal` is type of never
-   * 	}
-   * }
-   * ```
-   */
-  type MergedEnumValue<T> = { [K in keyof T]: { [K2 in keyof T[K]]: T[K][K2]; }[keyof T[K]]; }[keyof T];
-}
-//#endregion
-//#region src/index.d.ts
-export type DoNotUse = never;
-//#endregion
+type RequiredKey<T> = { [K in keyof T]-?: object extends Pick<T, K> ? never : K; }[keyof T];
+type Head<K> = K extends `${infer H}.${string}` ? H : never;
+/**
+ * Picks the `${P}.*` keys of `T`, stripping the `${P}.` prefix. When `P` is `never`, `T` is returned as is.
+ *
+ * __INTERNAL__
+ */
+type PickDotKeys<T, P extends string> = [P] extends [never] ? T : { [K in keyof T as K extends `${P}.${infer R}` ? R : never]: T[K]; };
+/**
+ * When `Deep` is `true`, unflattens plain object values, leaving functions, arrays and primitives untouched.
+ *
+ * __INTERNAL__
+ */
+type UnflatValue<V, Deep extends boolean> = Deep extends false ? V : V extends ((...args: any[]) => unknown) | readonly unknown[] ? V : V extends object ? Unflat<V, Deep> : V;
+/**
+ * Turns dotted keys into nested objects. A nested object is required when at least one of its keys is required.
+ *
+ * __INTERNAL__
+ */
+type Unflat<T, Deep extends boolean> = { [K in keyof T as K extends `${string}.${string}` ? never : K]: UnflatValue<T[K], Deep>; } & { [H in Head<Extract<RequiredKey<T>, string>>]: Unflat<PickDotKeys<T, H>, Deep>; } & { [H in Exclude<Head<keyof T>, Head<Extract<RequiredKey<T>, string>>>]?: Unflat<PickDotKeys<T, H>, Deep>; };
+/**
+ * Turns dotted keys (`"a.b"?: T`) into nested objects (`a?: { b?: T }`).
+ *
+ * @template T The object interface to work with.
+ * @template K The object interface specific key to work with (`${P}.*`).
+ */
+type UnflatDotKeys<T, K extends string = never> = Unflat<PickDotKeys<T, K>, false>;
+/**
+ * Same as {@link UnflatDotKeys}, but dotted keys of nested object values are unflattened too.
+ *
+ * @template T The object interface to work with.
+ * @template K The object interface specific key to work with (`${K}.*`).
+ */
+type RecursivelyUnflatDotKeys<T, K extends string = never> = Unflat<PickDotKeys<T, K>, true>;
+/**
+ * Get the Type of the Value of a object/array property.
+ *
+ */
+export type ValueOf<T> = T[keyof T];
+/**
+ * Get the Type of the Value of object/array specific property.
+ *
+ */
+export type ValueOfKey<T, P extends keyof T> = T[P];
+/**
+ * Make a specific property optional.
+ *
+ */
+export type OptionalKey<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
+/**
+ * Recursively set to `readonly` all properties of the given type/interface.
+ *
+ * @template T The type/interface where each property will be set to `readonly`.
+ */
+export type ReadOnly<T> = keyof T extends never ? T : { readonly [k in keyof T]: ReadOnly<T[k]>; };
+/**
+ * Make read-only properties of an object recursively writeable.
+ *
+ */
+export type Writeable<T> = keyof T extends never ? T : { -readonly [P in keyof T]: Writeable<T[P]>; };
+/**
+ * Renames a property while inheriting its type and modifiers (`?` and `readonly`).
+ *
+ * @example
+ * ```ts
+ * interface User {
+ * 	// the user name
+ * 	name?: string
+ * 	// the user age
+ * 	age: number
+ * }
+ *
+ * type ModifiedUser = RenameKey<User, 'name', 'username'>
+ * // { username?: string, age: number }
+ * ```
+ */
+export type RenameKey<T, K extends keyof T, R extends PropertyKey> = { [P in keyof T as P extends K ? R : P]: T[P]; };
+/**
+ * Get the Type of a function arguments.
+ *
+ * @deprecated use `Parameters` instead.
+ */
+export type ArgumentTypes<F extends Function> = F extends ((...args: infer A) => any) ? A : never;
+/**
+ * Recursively convert to optional all properties of the given type/interface.
+ *
+ * @template T The type/interface where each property will be set as optional.
+ */
+export type DeepPartial<T> = T extends ((...args: any[]) => unknown) ? T : T extends object ? { [P in keyof T]?: DeepPartial<T[P]>; } : T;
+/**
+ * Makes all 1st level properties of a type required.
+ *
+ */
+export type Full<T> = { [P in keyof T]-?: T[P]; };
+/**
+ * Recursively makes all properties of a type required at all nested levels.
+ *
+ */
+export type DeepFull<T> = { [P in keyof T]-?: DeepFull<T[P]>; };
+/**
+ * Removes `null` and `undefined` from all properties of a type.
+ *
+ */
+export type NonNullableFields<T> = { [P in keyof T]: NonNullable<T[P]>; };
+/**
+ * Get the type of the value of merged enums.
+ *
+ * @example
+ *
+ * ```ts
+ * enum Mammals {
+ * 	Humans,
+ * 	Bats,
+ * 	Dolphins
+ * }
+ *
+ * enum Reptiles {
+ * 	Snakes,
+ * 	Alligators,
+ * 	Lizards
+ * }
+ *
+ * // merged enums.
+ * const Animals = { Mammals, Reptiles }
+ * type Animals = typeof Animals
+ *
+ * type Animal = MergedEnumValueType<typeof Animals>
+ *
+ * const testAnimal: Animal = 0 as any
+ *
+ * switch ( testAnimal ) {
+ * 	case Animals.Mammals.Humans:
+ * 	case Animals.Mammals.Bats:
+ * 	case Animals.Mammals.Dolphins:
+ * 	case Animals.Reptiles.Snakes:
+ * 	case Animals.Reptiles.Alligators:
+ * 	case Animals.Reptiles.Lizards:
+ * 		break
+ * 	default: {
+ * 		const invalid = testAnimal // `testAnimal` is type of never
+ * 	}
+ * }
+ * ```
+ */
+export type MergedEnumValue<T> = { [K in keyof T]: { [K2 in keyof T[K]]: T[K][K2]; }[keyof T[K]]; }[keyof T];
+/**
+ * Builds a discriminated union of `[event, args]` tuples from an event map.
+ *
+ * Each key of the given map becomes a tuple whose first element is the event name
+ * and whose second element is its payload type. Since the tuples are discriminated
+ * by the event name, checking `event` narrows `args` to the matching payload.
+ *
+ * @template M The event map, where each key is an event name and each value is its payload type.
+ *
+ * @example
+ * ```ts
+ * interface Events {
+ * 	play: { position: number }
+ * 	error: Error
+ * }
+ *
+ * type OnEventHandler = (...args: MappedArgs<Events>) => void
+ *
+ * const onEvent: OnEventHandler = (event, args): void => {
+ * 	if (event === 'play') {
+ * 		console.log(args.position) // `args` is narrowed to `{ position: number }`
+ * 	}
+ * 	if (event === 'error') {
+ * 		console.log(args) // `args` is narrowed to `Error`
+ * 	}
+ * }
+ *
+ * onEvent('play', { position: 0 })
+ * onEvent('error', new Error())
+ * ```
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * interface Events {
+ * 	play: [data: { position: number }]
+ * 	error: [error: Error]
+ * }
+ *
+ * type OnEventHandler = (...args: MappedArgs<Events>) => void
+ *
+ * const onEvent: OnEventHandler = (event, args): void => {
+ * 	if (event === 'play') {
+ * 		const [payload] = args
+ * 		console.log(payload.position) // `args` is narrowed to [`{ position: number }`]
+ * 	}
+ * 	if (event === 'error') {
+ * 		const [error] = args // `args` is narrowed to [`Error`]
+ * 		console.log(error)
+ * 	}
+ * }
+ *
+ * onEvent('play', [{ position: 0 }])
+ * onEvent('error', [new Error()])
+ * ```
+ */
+export type MappedArgs<M> = { [K in keyof M]: [event: K, args: M[K]]; }[keyof M];
+export type { RecursivelyUnflatDotKeys, UnflatDotKeys };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alessiofrittoli/type-utils",
-  "version": "1.10.1",
+  "version": "2.1.0",
   "description": "Lightweight TypeScript types utilities",
   "type": "module",
   "author": {
@@ -63,30 +63,30 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@alessiofrittoli/chain-functions": "^2.7.0",
-    "@alessiofrittoli/node-scripts": "^4.0.0-alpha.5"
+    "@alessiofrittoli/chain-functions": "^2.8.0",
+    "@alessiofrittoli/node-scripts": "^4.2.0"
   },
   "devDependencies": {
-    "@alessiofrittoli/chain-functions": "^2.7.0",
-    "@alessiofrittoli/node-scripts": "^4.0.0-alpha.5",
-    "@alessiofrittoli/package-configs": "^1.6.0",
+    "@alessiofrittoli/chain-functions": "^2.8.0",
+    "@alessiofrittoli/node-scripts": "^4.2.0",
+    "@alessiofrittoli/package-configs": "^1.9.0",
     "@types/node": "^24.19.1",
-    "@vitest/coverage-v8": "^5.0.3",
-    "concurrently": "^9.2.1",
+    "@vitest/coverage-v8": "^5.0.5",
+    "concurrently": "^10.0.6",
     "http-server": "^14.1.1",
-    "oxlint": "^1.86.0",
-    "prettier": "^3.9.9",
+    "oxlint": "^1.89.0",
+    "oxlint-tsgolint": "^7.0.2005",
+    "prettier": "^3.9.10",
     "prettier-plugin-sort-imports": "^1.8.11",
-    "tsdown": "^0.23.0",
-    "typescript": "^6.0.3",
-    "vite": "^8.3.2"
+    "tsdown": "^0.23.2",
+    "typescript": "^6.0.3"
   },
   "scripts": {
     "//1a": "*********************************************************************",
     "//1b": "******************** DEV - BUILD - LINT - RELEASE *******************",
     "//1c": "*********************************************************************",
     "dev": "tsdown --watch",
-    "build": "pnpm lint && pnpm tsc && pnpm tsdown",
+    "build": "pnpm lint && pnpm tsdown",
     "lint": "oxlint --report-unused-disable-directives --max-warnings 0",
     "release": "node scripts/release.ts --verbose --npm",
     "//2a": "*********************************************************************",

package/scripts/postinstall/index.cjs

@@ -13,4 +13,5 @@ const lastChainLink = () => () => {
 /** @type {import( '@alessiofrittoli/chain-functions/types' ).ChainFactory<() => void | Promise<void>>} */
 const chain = [tsSetup, lastChainLink]
 
+// oxlint-disable-next-line typescript/no-floating-promises
 Chain.functions(chain)()

package/scripts/postinstall/ts-setup.cjs

@@ -1,14 +1,14 @@
-const { addTypesReference } = require( '@alessiofrittoli/node-scripts/postinstall' )
-const project = require( '../../package.json' )
+const { addTypesReference } = require('@alessiofrittoli/node-scripts/postinstall')
+const project = require('../../package.json')
 
 /** @type {import( '@alessiofrittoli/chain-functions/types' ).ChainLink<() => void | Promise<void>>} */
 const tsSetup = next => () => {
-	
-	addTypesReference( {
+	addTypesReference({
 		name: project.name,
-	} )
+		scopes: [`${project.name}/globals`],
+	})
 
 	return next()
 }
 
-module.exports = tsSetup
+module.exports = tsSetup