@lucasbernardosn/ts-utils 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Bernardo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# @lucasbernardosn/ts-utils
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Funções e helpers de tipo em TypeScript puro, sem React e sem dependências. Serve a qualquer
+projeto TypeScript e é a base do [`@lucasbernardosn/react-ui`](https://www.npmjs.com/package/@lucasbernardosn/react-ui)
+e do [`@lucasbernardosn/react-table`](https://www.npmjs.com/package/@lucasbernardosn/react-table).
+
+Substitui o `@lucasbernardosn/utils`: a troca é só do nome no import.
+
+## Instalação
+
+```bash
+pnpm add @lucasbernardosn/ts-utils
+```
+
+Tudo sai da raiz do pacote:
+
+```ts
+import { getInitials, isDeepEqual, type DeepPartial } from '@lucasbernardosn/ts-utils';
+```
+
+## Funções
+
+| Função | Para quê |
+| ------ | -------- |
+| `composeEventHandlers` | Junta vários handlers num só, chamados em sequência com os mesmos argumentos; os `undefined` são ignorados |
+| `createSplitProps` | Separa um objeto de props em dois pela lista de chaves, que precisa cobrir todas as chaves do tipo pedido |
+| `getInitials` | As iniciais de um nome, em maiúsculas: a do primeiro e a do último nome |
+| `isDeepEqual` | Igualdade estrutural, inclusive de `Map`, `Set`, `Date`, `RegExp` e arrays tipados |
+| `isNotNullish` | Guard que tira `null` e `undefined` do tipo, para usar no `filter` |
+| `mergeBooleansAnd`, `mergeBooleansOr` | Combinam booleanos com E e OU, ignorando os `null` e `undefined` |
+| `toPascalCase` | Converte texto para PascalCase, separando em `-`, `_` e espaços |
+| `sleep` | Promise que resolve depois de um tempo, opcionalmente com um valor (para testes e protótipos) |
+
+## Tipos
+
+| Tipo | Para quê |
+| ---- | -------- |
+| `DeepPartial`, `DeepReadonly` | `Partial` e `Readonly` em todos os níveis |
+| `DeepKeys`, `DeepKeysFlat`, `DeepValue` | Os caminhos de um objeto (`'a.b.c'`) e o tipo do valor em cada um |
+| `KeysOfType`, `PickByValue`, `OmitByValue` | Chaves e recortes de um objeto pelo tipo do valor |
+| `MergeOverride` | Junta dois tipos, com as chaves do segundo substituindo as do primeiro |
+| `Optional`, `RequiredExcept` | Torna opcionais só as chaves pedidas, ou obrigatórias todas menos elas |
+| `Recompose` | Achata uma interseção num objeto só, para o editor mostrar o tipo final |
+| `ValueOf`, `ArrayElement`, `NonEmptyArray` | O tipo dos valores de um objeto, o elemento de um array e um array com ao menos um item |
+| `Nullish`, `EnsureString`, `PascalCase` | `null` ou `undefined`, o tipo que só aceita `string` e o PascalCase de um literal |
+| `SerializableValue`, `StrictEmptyObject` | Um valor que sobrevive ao `JSON.stringify` e o objeto sem chaves |
+| `AnyType`, `UnknownType` e variantes | Os `any` e `unknown` nomeados (`AnyObject`, `UnknownFunction`…), para o uso ser explícito |
+
+O JSDoc de cada função e tipo, no editor, traz os detalhes e os exemplos.
+
+## Licença
+
+MIT.

package/dist/dev/index.d.ts

@@ -0,0 +1,2 @@
+import { sleep } from "./sleep.js";
+export { sleep };

package/dist/dev/index.js

@@ -0,0 +1,2 @@
+import { sleep } from "./sleep.js";
+export { sleep };

package/dist/dev/sleep.d.ts

@@ -0,0 +1,32 @@
+//#region src/dev/sleep.d.ts
+/**
+ * Opções de configuração do {@link sleep}.
+ */
+type SleepOptions = {
+  /** Sinal para cancelar o delay (útil em testes e para testar unmount). */
+  signal?: AbortSignal;
+  /** Chance de simular um erro randômico, de 0.0 a 1.0 (ex.: 0.3 = 30% de chance de falha). */
+  failureRate?: number;
+  /** Mensagem de erro customizada caso ocorra a falha simulada. */
+  errorMessage?: string;
+};
+/**
+ * Opções do {@link sleep} que resolve com um valor.
+ */
+type SleepOptionsWithValue<T> = SleepOptions & {
+  /** Valor que será retornado após o delay (útil para mockar respostas de API). */
+  resolveWith: T;
+};
+/**
+ * Função utilitária para desenvolvimento que pausa a execução por um tempo.
+ * Excelente para mockar latência de rede, testar estados de loading e simular falhas.
+ *
+ * @param ms Tempo em milissegundos ou um range `[min, max]` para latência aleatória. Padrão é 1000ms.
+ * @param options Opções adicionais (cancelamento, valor de resolução e simulação de falha).
+ * @returns Promise resolvida com `options.resolveWith` após o delay, rejeitada em caso de
+ * abort (com `signal.reason`) ou de falha simulada (com `errorMessage`).
+ */
+export declare function sleep(ms?: number | [min: number, max: number], options?: SleepOptions): Promise<void>;
+export declare function sleep<T>(ms: number | [min: number, max: number], options: SleepOptionsWithValue<T>): Promise<T>;
+//#endregion
+//# sourceMappingURL=sleep.d.ts.map

package/dist/dev/sleep.js

@@ -0,0 +1,42 @@
+//#region src/dev/sleep.ts
+/**
+* Calcula o delay em milissegundos a partir do parâmetro `ms` do {@link sleep}.
+* Se `ms` for um range `[min, max]`, sorteia um valor inteiro dentro do intervalo (inclusive).
+*/
+const resolveDelay = (ms) => {
+	if (!Array.isArray(ms)) return ms;
+	const [min, max] = ms;
+	return Math.floor(Math.random() * (max - min + 1) + min);
+};
+/**
+* Sobrecarga, e por isso `function`: com `resolveWith`, a promise resolve com o tipo dele; sem, com
+* `void`. Uma assinatura só com o valor opcional resolveria `undefined` como se fosse `T`.
+*/
+function sleep(ms = 1e3, options) {
+	const delay = resolveDelay(ms);
+	const { signal, failureRate = 0, errorMessage = "Simulated sleep failure" } = options ?? {};
+	const resolveWith = options && "resolveWith" in options ? options.resolveWith : void 0;
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		const handleAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", handleAbort);
+			if (failureRate > 0 && Math.random() < failureRate) {
+				reject(new Error(errorMessage));
+				return;
+			}
+			resolve(resolveWith);
+		}, delay);
+		signal?.addEventListener("abort", handleAbort, { once: true });
+	});
+}
+//#endregion
+export { sleep };
+
+//# sourceMappingURL=sleep.js.map

package/dist/dev/sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.js","names":[],"sources":["../../src/dev/sleep.ts"],"sourcesContent":["/**\n * Opções de configuração do {@link sleep}.\n */\ntype SleepOptions = {\n  /** Sinal para cancelar o delay (útil em testes e para testar unmount). */\n  signal?: AbortSignal;\n  /** Chance de simular um erro randômico, de 0.0 a 1.0 (ex.: 0.3 = 30% de chance de falha). */\n  failureRate?: number;\n  /** Mensagem de erro customizada caso ocorra a falha simulada. */\n  errorMessage?: string;\n};\n\n/**\n * Opções do {@link sleep} que resolve com um valor.\n */\ntype SleepOptionsWithValue<T> = SleepOptions & {\n  /** Valor que será retornado após o delay (útil para mockar respostas de API). */\n  resolveWith: T;\n};\n\n/**\n * Calcula o delay em milissegundos a partir do parâmetro `ms` do {@link sleep}.\n * Se `ms` for um range `[min, max]`, sorteia um valor inteiro dentro do intervalo (inclusive).\n */\nconst resolveDelay = (ms: number | [min: number, max: number]): number => {\n  if (!Array.isArray(ms)) {\n    return ms;\n  }\n\n  const [min, max] = ms;\n  return Math.floor(Math.random() * (max - min + 1) + min);\n};\n\n/**\n * Função utilitária para desenvolvimento que pausa a execução por um tempo.\n * Excelente para mockar latência de rede, testar estados de loading e simular falhas.\n *\n * @param ms Tempo em milissegundos ou um range `[min, max]` para latência aleatória. Padrão é 1000ms.\n * @param options Opções adicionais (cancelamento, valor de resolução e simulação de falha).\n * @returns Promise resolvida com `options.resolveWith` após o delay, rejeitada em caso de\n * abort (com `signal.reason`) ou de falha simulada (com `errorMessage`).\n */\nexport function sleep(\n  ms?: number | [min: number, max: number],\n  options?: SleepOptions,\n): Promise<void>;\nexport function sleep<T>(\n  ms: number | [min: number, max: number],\n  options: SleepOptionsWithValue<T>,\n): Promise<T>;\n/**\n * Sobrecarga, e por isso `function`: com `resolveWith`, a promise resolve com o tipo dele; sem, com\n * `void`. Uma assinatura só com o valor opcional resolveria `undefined` como se fosse `T`.\n */\nexport function sleep<T>(\n  ms: number | [min: number, max: number] = 1000,\n  options?: SleepOptions | SleepOptionsWithValue<T>,\n): Promise<T | undefined> {\n  const delay = resolveDelay(ms);\n  const {\n    signal,\n    failureRate = 0,\n    errorMessage = 'Simulated sleep failure',\n  } = options ?? {};\n  const resolveWith =\n    options && 'resolveWith' in options ? options.resolveWith : undefined;\n\n  return new Promise((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(signal.reason);\n      return;\n    }\n\n    const handleAbort = () => {\n      clearTimeout(timer);\n      reject(signal?.reason);\n    };\n\n    const timer = setTimeout(() => {\n      // Remove o listener de abort: o timer já completou, cancelar não faz mais sentido.\n      signal?.removeEventListener('abort', handleAbort);\n\n      // Simulação de chaos (falhas de API).\n      if (failureRate > 0 && Math.random() < failureRate) {\n        reject(new Error(errorMessage));\n        return;\n      }\n\n      resolve(resolveWith);\n    }, delay);\n\n    // Permite cancelamento externo enquanto o timer está pendente.\n    signal?.addEventListener('abort', handleAbort, { once: true });\n  });\n}\n"],"mappings":";;;;;AAwBA,MAAM,gBAAgB,OAAoD;CACxE,IAAI,CAAC,MAAM,QAAQ,EAAE,GACnB,OAAO;CAGT,MAAM,CAAC,KAAK,OAAO;CACnB,OAAO,KAAK,MAAM,KAAK,OAAO,KAAK,MAAM,MAAM,KAAK,GAAG;AACzD;;;;;AAuBA,SAAgB,MACd,KAA0C,KAC1C,SACwB;CACxB,MAAM,QAAQ,aAAa,EAAE;CAC7B,MAAM,EACJ,QACA,cAAc,GACd,eAAe,8BACb,WAAW,CAAC;CAChB,MAAM,cACJ,WAAW,iBAAiB,UAAU,QAAQ,cAAc,KAAA;CAE9D,OAAO,IAAI,SAAS,SAAS,WAAW;EACtC,IAAI,QAAQ,SAAS;GACnB,OAAO,OAAO,MAAM;GACpB;EACF;EAEA,MAAM,oBAAoB;GACxB,aAAa,KAAK;GAClB,OAAO,QAAQ,MAAM;EACvB;EAEA,MAAM,QAAQ,iBAAiB;GAE7B,QAAQ,oBAAoB,SAAS,WAAW;GAGhD,IAAI,cAAc,KAAK,KAAK,OAAO,IAAI,aAAa;IAClD,OAAO,IAAI,MAAM,YAAY,CAAC;IAC9B;GACF;GAEA,QAAQ,WAAW;EACrB,GAAG,KAAK;EAGR,QAAQ,iBAAiB,SAAS,aAAa,EAAE,MAAM,KAAK,CAAC;CAC/D,CAAC;AACH"}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { sleep } from "./dev/sleep.js";
+import { AnyArray, AnyFunction, AnyLooseValue, AnyObject, AnyType } from "./types/any.js";
+import { ArrayElement, NonEmptyArray } from "./types/array.js";
+import { DeepKeys } from "./types/deep-keys.js";
+import { DeepKeysFlat } from "./types/deep-keys-flat.js";
+import { DeepPartial } from "./types/deep-partial.js";
+import { DeepReadonly } from "./types/deep-readonly.js";
+import { DeepValue } from "./types/deep-value.js";
+import { EnsureString } from "./types/ensure-string.js";
+import { KeysOfType } from "./types/keys-of-type.js";
+import { MergeOverride } from "./types/merge-override.js";
+import { Nullish } from "./types/nullish.js";
+import { OmitByValue } from "./types/omit-by-value.js";
+import { Optional } from "./types/optional.js";
+import { PickByValue } from "./types/pick-by-value.js";
+import { Recompose } from "./types/recompose.js";
+import { RequiredExcept } from "./types/required-except.js";
+import { SerializableValue } from "./types/serializable-value.js";
+import { StrictEmptyObject } from "./types/strict-empty-object.js";
+import { UnknownArray, UnknownFunction, UnknownLooseValue, UnknownObject, UnknownType } from "./types/unknown.js";
+import { ValueOf } from "./types/value-of.js";
+import { composeEventHandlers } from "./utils/compose-event-handlers.js";
+import { createSplitProps } from "./utils/create-split-props.js";
+import { getInitials } from "./utils/get-initials.js";
+import { isDeepEqual } from "./utils/is-deep-equal.js";
+import { isNotNullish } from "./utils/is-not-nullish.js";
+import { mergeBooleansAnd, mergeBooleansOr } from "./utils/merge-booleans.js";
+import { PascalCase, toPascalCase } from "./utils/to-pascal-case.js";
+export { AnyArray, AnyFunction, AnyLooseValue, AnyObject, AnyType, ArrayElement, DeepKeys, DeepKeysFlat, DeepPartial, DeepReadonly, DeepValue, EnsureString, KeysOfType, MergeOverride, NonEmptyArray, Nullish, OmitByValue, Optional, PascalCase, PickByValue, Recompose, RequiredExcept, SerializableValue, StrictEmptyObject, UnknownArray, UnknownFunction, UnknownLooseValue, UnknownObject, UnknownType, ValueOf, composeEventHandlers, createSplitProps, getInitials, isDeepEqual, isNotNullish, mergeBooleansAnd, mergeBooleansOr, sleep, toPascalCase };

package/dist/index.js

@@ -0,0 +1,9 @@
+import { sleep } from "./dev/sleep.js";
+import { composeEventHandlers } from "./utils/compose-event-handlers.js";
+import { createSplitProps } from "./utils/create-split-props.js";
+import { getInitials } from "./utils/get-initials.js";
+import { isDeepEqual } from "./utils/is-deep-equal.js";
+import { isNotNullish } from "./utils/is-not-nullish.js";
+import { mergeBooleansAnd, mergeBooleansOr } from "./utils/merge-booleans.js";
+import { toPascalCase } from "./utils/to-pascal-case.js";
+export { composeEventHandlers, createSplitProps, getInitials, isDeepEqual, isNotNullish, mergeBooleansAnd, mergeBooleansOr, sleep, toPascalCase };

package/dist/types/any.d.ts

@@ -0,0 +1,33 @@
+//#region src/types/any.d.ts
+/** biome-ignore-all lint/suspicious/noExplicitAny: "any" é usado para criar tipos genéricos */
+/**
+ * Tipo genérico que representa qualquer valor possível no TipoScript.
+ * Utilizado como base para criação de estruturas de dados dinâmicas
+ * onde o tipo específico não é conhecido antecipadamente.
+ */
+export type AnyType = any;
+/**
+ * Tipo que representa um objeto genérico com chaves string e valores dinâmicos.
+ * Útil para modelar estruturas de dados flexíveis como payloads de API,
+ * configurações dinâmicas ou objetos com propriedades variáveis.
+ */
+export type AnyObject = Record<string, AnyType>;
+/**
+ * Tipo que representa um array genérico contendo elementos de qualquer tipo.
+ * Pode ser utilizado para modelar listas ou coleções onde o tipo dos elementos
+ * não é conhecido ou pode variar.
+ */
+export type AnyArray = AnyType[];
+/**
+ * Tipo que representa uma função genérica, aceitando qualquer quantidade
+ * de argumentos e retornando um valor de qualquer tipo.
+ */
+export type AnyFunction = (...args: AnyType[]) => AnyType;
+/**
+ * Tipo que representa um valor frouxamente tipado, podendo ser um primitivo,
+ * `null`, `undefined`, um objeto ou array dinâmico. Útil para modelar
+ * valores de origem incerta que ainda assim têm um conjunto limitado de formas possíveis.
+ */
+export type AnyLooseValue = string | number | boolean | AnyObject | AnyArray | null | undefined;
+//#endregion
+//# sourceMappingURL=any.d.ts.map

package/dist/types/array.d.ts

@@ -0,0 +1,33 @@
+//#region src/types/array.d.ts
+/**
+ * Tipo utilitário que extrai o tipo do elemento de um array.
+ * Retorna `never` caso `TArray` não seja um array.
+ *
+ * @template TArray - O tipo do array a ser avaliado.
+ *
+ * @example
+ *
+ * type Numeros = number[];
+ * type Numero = ArrayElement<Numeros>; // number
+ *
+ * type Strings = string[];
+ * type Str = ArrayElement<Strings>; // string
+ */
+export type ArrayElement<TArray> = TArray extends (infer TElement)[] ? TElement : never;
+/**
+ * Tipo utilitário que representa um array com pelo menos um elemento.
+ * Garante em tempo de compilação que o array não está vazio.
+ *
+ * @template TElement - Tipo dos elementos do array.
+ *
+ * @example
+ *
+ * type OpcoesSelecionadas = NonEmptyArray<string>;
+ *
+ * const valido: OpcoesSelecionadas = ['opcao1'];            // OK
+ * const tambemValido: OpcoesSelecionadas = ['a', 'b', 'c']; // OK
+ * const invalido: OpcoesSelecionadas = [];                  // Erro de compilação
+ */
+export type NonEmptyArray<TElement> = [TElement, ...TElement[]];
+//#endregion
+//# sourceMappingURL=array.d.ts.map

package/dist/types/deep-keys-flat.d.ts

@@ -0,0 +1,36 @@
+import { AnyFunction } from "./any.js";
+//#region src/types/deep-keys-flat.d.ts
+/**
+ * Implementação recursiva de {@link DeepKeysFlat}, carregando o acumulador de
+ * profundidade `TDepth` para interromper a recursão ao atingir `TMaxDepth`.
+ */
+type DeepKeysFlatImpl<TBase, TMaxDepth extends number, TDepth extends readonly unknown[]> = TDepth['length'] extends TMaxDepth ? never : NonNullable<TBase> extends AnyFunction | Date ? never : NonNullable<TBase> extends readonly (infer TElement)[] ? DeepKeysFlatImpl<TElement, TMaxDepth, [...TDepth, unknown]> : NonNullable<TBase> extends object ? { [Key in Extract<keyof NonNullable<TBase>, string>]-?: Key | `${Key}.${DeepKeysFlatImpl<NonNullable<TBase>[Key], TMaxDepth, [...TDepth, unknown]>}`; }[Extract<keyof NonNullable<TBase>, string>] : never;
+/**
+ * Tipo utilitário que extrai as chaves de um objeto em notação de ponto,
+ * achatando arrays de objetos ao estilo do TanStack Table: um caminho para
+ * dentro de um array não recebe índice numérico.
+ *
+ * Difere de `DeepKeys`, que trata arrays como folha. Use `DeepKeysFlat` quando
+ * precisar de paridade com `DeepKeys` do TanStack Table (definição de colunas).
+ *
+ * Atenção: `DeepValue` não resolve caminhos que atravessam arrays achatados —
+ * ele é o par de `DeepKeys` (folha), não de `DeepKeysFlat`.
+ *
+ * A recursão é limitada por `TMaxDepth` (padrão: 5).
+ *
+ * @template TBase - Tipo do objeto a ser inspecionado.
+ * @template TMaxDepth - Profundidade máxima de recursão. Padrão: 5.
+ *
+ * @example
+ *
+ * type Pedido = {
+ *   id: string;
+ *   itens: { produto: string; preco: number }[];
+ * };
+ *
+ * type Chaves = DeepKeysFlat<Pedido>;
+ * // 'id' | 'itens' | 'itens.produto' | 'itens.preco'
+ */
+export type DeepKeysFlat<TBase, TMaxDepth extends number = 5> = DeepKeysFlatImpl<TBase, TMaxDepth, []>;
+//#endregion
+//# sourceMappingURL=deep-keys-flat.d.ts.map

package/dist/types/deep-keys.d.ts

@@ -0,0 +1,57 @@
+import { AnyArray, AnyFunction } from "./any.js";
+//#region src/types/deep-keys.d.ts
+/**
+ * Determina se um tipo deve ser tratado como um registro navegável
+ * (objeto com propriedades acessíveis via dot notation).
+ *
+ * Retorna `false` para `Date`, arrays e funções — mesmo que sejam objetos
+ * em tempo de execução, não fazem sentido como ramo de navegação de chaves.
+ *
+ * @template TValue - Tipo a ser avaliado.
+ */
+type IsRecord<TValue> = NonNullable<TValue> extends AnyArray | AnyFunction | Date ? false : NonNullable<TValue> extends object ? true : false;
+/**
+ * Implementação recursiva de {@link DeepKeys}, carregando o acumulador de
+ * profundidade `TDepth` para interromper a recursão ao atingir `TMaxDepth`.
+ */
+type DeepKeysImpl<TBase, TMaxDepth extends number, TDepth extends readonly unknown[]> = TDepth['length'] extends TMaxDepth ? never : TBase extends AnyArray | AnyFunction | Date ? never : TBase extends object ? { [Key in Extract<keyof TBase, string>]-?: IsRecord<TBase[Key]> extends true ? Key | `${Key}.${DeepKeysImpl<NonNullable<TBase[Key]>, TMaxDepth, [...TDepth, unknown]>}` : Key; }[Extract<keyof TBase, string>] : never;
+/**
+ * Tipo utilitário que extrai todas as chaves de um objeto em notação de ponto
+ * (dot notation), navegando recursivamente por objetos aninhados.
+ *
+ * Arrays são tratados como folha: `DeepKeys` para na chave do array e não
+ * gera caminhos para dentro dos elementos (`itens`, nunca `itens.0.preco`).
+ * Para achatar arrays de objetos ao estilo do TanStack Table
+ * (`itens.preco`), use `DeepKeysFlat`.
+ *
+ * A recursão é limitada por `TMaxDepth` (padrão: 5) para evitar explosão de
+ * união em entidades grandes e travamento do compilador.
+ *
+ * @template TBase - Tipo do objeto a ser inspecionado.
+ * @template TMaxDepth - Profundidade máxima de recursão. Padrão: 5.
+ *
+ * @example
+ *
+ * type Pedido = {
+ *   id: string;
+ *   cliente: {
+ *     nome: string;
+ *     documento?: { cpf: string };
+ *   };
+ *   itens: { produto: string }[];
+ * };
+ *
+ * type Chaves = DeepKeys<Pedido>;
+ * // 'id'
+ * // | 'cliente'
+ * // | 'cliente.nome'
+ * // | 'cliente.documento'
+ * // | 'cliente.documento.cpf'
+ * // | 'itens'
+ *
+ * type ChavesRasas = DeepKeys<Pedido, 1>;
+ * // 'id' | 'cliente' | 'itens'
+ */
+export type DeepKeys<TBase, TMaxDepth extends number = 5> = DeepKeysImpl<TBase, TMaxDepth, []>;
+//#endregion
+//# sourceMappingURL=deep-keys.d.ts.map

package/dist/types/deep-partial.d.ts

@@ -0,0 +1,39 @@
+import { AnyFunction } from "./any.js";
+//#region src/types/deep-partial.d.ts
+/**
+ * Tipo utilitário que torna todas as propriedades de um tipo recursivamente opcionais,
+ * incluindo propriedades aninhadas em objetos e elementos de arrays.
+ * Funções são preservadas sem modificação.
+ *
+ * @template TBase - Tipo base a ser transformado.
+ *
+ * @example
+ *
+ * type Endereco = {
+ *   rua: string;
+ *   cidade: string;
+ * };
+ *
+ * type Usuario = {
+ *   id: number;
+ *   nome: string;
+ *   endereco: Endereco;
+ *   tags: string[];
+ * };
+ *
+ * type UsuarioParcial = DeepPartial<Usuario>;
+ *
+ * // Resultado:
+ * // {
+ * //   id?: number;
+ * //   nome?: string;
+ * //   endereco?: {
+ * //     rua?: string;
+ * //     cidade?: string;
+ * //   };
+ * //   tags?: string[];
+ * // }
+ */
+export type DeepPartial<TBase> = TBase extends AnyFunction ? TBase : TBase extends Array<infer TElement> ? DeepPartial<TElement>[] : TBase extends object ? { [Key in keyof TBase]?: DeepPartial<TBase[Key]>; } : TBase;
+//#endregion
+//# sourceMappingURL=deep-partial.d.ts.map

package/dist/types/deep-readonly.d.ts

@@ -0,0 +1,39 @@
+import { AnyFunction } from "./any.js";
+//#region src/types/deep-readonly.d.ts
+/**
+ * Tipo utilitário que torna todas as propriedades de um tipo recursivamente somente-leitura,
+ * incluindo propriedades aninhadas em objetos. Arrays se tornam `ReadonlyArray`.
+ * Funções são preservadas sem modificação.
+ *
+ * @template TBase - Tipo base a ser transformado.
+ *
+ * @example
+ *
+ * type Endereco = {
+ *   rua: string;
+ *   cidade: string;
+ * };
+ *
+ * type Usuario = {
+ *   id: number;
+ *   nome: string;
+ *   endereco: Endereco;
+ *   tags: string[];
+ * };
+ *
+ * type UsuarioImutavel = DeepReadonly<Usuario>;
+ *
+ * // Resultado:
+ * // {
+ * //   readonly id: number;
+ * //   readonly nome: string;
+ * //   readonly endereco: {
+ * //     readonly rua: string;
+ * //     readonly cidade: string;
+ * //   };
+ * //   readonly tags: ReadonlyArray<string>;
+ * // }
+ */
+export type DeepReadonly<TBase> = TBase extends AnyFunction ? TBase : TBase extends Array<infer TElement> ? readonly DeepReadonly<TElement>[] : TBase extends object ? { readonly [Key in keyof TBase]: DeepReadonly<TBase[Key]>; } : TBase;
+//#endregion
+//# sourceMappingURL=deep-readonly.d.ts.map

package/dist/types/deep-value.d.ts

@@ -0,0 +1,32 @@
+//#region src/types/deep-value.d.ts
+/**
+ * Tipo utilitário que resolve o tipo do valor apontado por um caminho em
+ * notação de ponto (dot notation). É o par de `DeepKeys`: qualquer chave
+ * produzida por `DeepKeys<T>` é resolvível por `DeepValue<T, chave>`.
+ *
+ * Propriedades opcionais no meio do caminho são atravessadas (o `undefined`
+ * intermediário é ignorado). O `undefined` da propriedade final é preservado,
+ * refletindo o valor real em tempo de execução.
+ *
+ * Não resolve caminhos que atravessam arrays (ver `DeepKeysFlat`).
+ *
+ * @template TBase - Tipo do objeto raiz.
+ * @template TPath - Caminho em notação de ponto.
+ *
+ * @example
+ *
+ * type Pedido = {
+ *   id: string;
+ *   cliente: {
+ *     nome: string;
+ *     documento?: { cpf: string };
+ *   };
+ * };
+ *
+ * type Id = DeepValue<Pedido, 'id'>;                       // string
+ * type Nome = DeepValue<Pedido, 'cliente.nome'>;           // string
+ * type Cpf = DeepValue<Pedido, 'cliente.documento.cpf'>;   // string | undefined
+ */
+export type DeepValue<TBase, TPath extends string> = TPath extends `${infer Key}.${infer Rest}` ? Key extends keyof NonNullable<TBase> ? DeepValue<NonNullable<TBase>[Key], Rest> | Extract<TBase, null | undefined> : never : TPath extends keyof NonNullable<TBase> ? NonNullable<TBase>[TPath] | Extract<TBase, null | undefined> : never;
+//#endregion
+//# sourceMappingURL=deep-value.d.ts.map

package/dist/types/ensure-string.d.ts

@@ -0,0 +1,19 @@
+//#region src/types/ensure-string.d.ts
+/**
+ * Tipo utilitário que garante que um tipo genérico seja uma string,
+ * retornando o próprio tipo se for string ou never se não for.
+ * Útil para validação de tipos em contextos onde apenas strings são aceitas.
+ *
+ * @template TString - Tipo a ser validado como string.
+ *
+ * @example
+ *
+ * // Quando o tipo é string, mantém string
+ * type S1 = EnsureString<string> // string
+ *
+ * // Quando o tipo não é string, resulta em never
+ * type S2 = EnsureString<number> // never
+ */
+export type EnsureString<TString> = TString extends string ? TString : never;
+//#endregion
+//# sourceMappingURL=ensure-string.d.ts.map

package/dist/types/index.d.ts

@@ -0,0 +1,21 @@
+import { AnyArray, AnyFunction, AnyLooseValue, AnyObject, AnyType } from "./any.js";
+import { ArrayElement, NonEmptyArray } from "./array.js";
+import { DeepKeys } from "./deep-keys.js";
+import { DeepKeysFlat } from "./deep-keys-flat.js";
+import { DeepPartial } from "./deep-partial.js";
+import { DeepReadonly } from "./deep-readonly.js";
+import { DeepValue } from "./deep-value.js";
+import { EnsureString } from "./ensure-string.js";
+import { KeysOfType } from "./keys-of-type.js";
+import { MergeOverride } from "./merge-override.js";
+import { Nullish } from "./nullish.js";
+import { OmitByValue } from "./omit-by-value.js";
+import { Optional } from "./optional.js";
+import { PickByValue } from "./pick-by-value.js";
+import { Recompose } from "./recompose.js";
+import { RequiredExcept } from "./required-except.js";
+import { SerializableValue } from "./serializable-value.js";
+import { StrictEmptyObject } from "./strict-empty-object.js";
+import { UnknownArray, UnknownFunction, UnknownLooseValue, UnknownObject, UnknownType } from "./unknown.js";
+import { ValueOf } from "./value-of.js";
+export { AnyArray, AnyFunction, AnyLooseValue, AnyObject, AnyType, ArrayElement, DeepKeys, DeepKeysFlat, DeepPartial, DeepReadonly, DeepValue, EnsureString, KeysOfType, MergeOverride, NonEmptyArray, Nullish, OmitByValue, Optional, PickByValue, Recompose, RequiredExcept, SerializableValue, StrictEmptyObject, UnknownArray, UnknownFunction, UnknownLooseValue, UnknownObject, UnknownType, ValueOf };

package/dist/types/keys-of-type.d.ts

@@ -0,0 +1,26 @@
+//#region src/types/keys-of-type.d.ts
+/**
+ * Tipo utilitário que extrai as chaves de um objeto cujos valores estendem um tipo específico.
+ *
+ * @template TBase - Tipo base a ser inspecionado.
+ * @template TValue - Tipo dos valores que serão selecionados.
+ *
+ * @example
+ *
+ * type Usuario = {
+ *   id: number;
+ *   nome: string;
+ *   email: string;
+ *   ativo: boolean;
+ *   idade: number;
+ * };
+ *
+ * type ChavesString = KeysOfType<Usuario, string>;
+ * // Resultado: 'nome' | 'email'
+ *
+ * type ChavesNumericas = KeysOfType<Usuario, number>;
+ * // Resultado: 'id' | 'idade'
+ */
+export type KeysOfType<TBase, TValue> = { [Key in keyof TBase]: TBase[Key] extends TValue ? Key : never; }[keyof TBase];
+//#endregion
+//# sourceMappingURL=keys-of-type.d.ts.map

package/dist/types/merge-override.d.ts

@@ -0,0 +1,34 @@
+//#region src/types/merge-override.d.ts
+/**
+ * Tipo utilitário que combina dois tipos, substituindo as propriedades do tipo base
+ * pelas propriedades do tipo sobrescritor quando houver conflito de chaves.
+ *
+ * @template TBase - Tipo base a ser combinado.
+ * @template TOverride - Tipo cujas propriedades substituem as de TBase quando há conflito.
+ *
+ * @example
+ *
+ * type User = {
+ *   id: number;
+ *   name: string;
+ * };
+ *
+ * type NewUser = {
+ *   id: string;
+ *   login: string;
+ *   age?: number;
+ * };
+ *
+ * type MergedUser = MergeOverride<User, NewUser>;
+ *
+ * // Resultado:
+ * // {
+ * //   id: string;
+ * //   name: string;
+ * //   login: string;
+ * //   age?: number;
+ * // }
+ */
+export type MergeOverride<TBase, TOverride> = Omit<TBase, keyof TOverride> & TOverride;
+//#endregion
+//# sourceMappingURL=merge-override.d.ts.map

package/dist/types/nullish.d.ts

@@ -0,0 +1,25 @@
+//#region src/types/nullish.d.ts
+/**
+ * Tipo utilitário que torna todas as propriedades de um tipo opcionais
+ * e permite que sejam nulas, mantendo o tipo original ou permitindo null.
+ *
+ * @template TBase - Tipo base de referência.
+ *
+ * @example
+ *
+ * type Usuario = {
+ *   id: number;
+ *   nome: string;
+ *   ativo: boolean;
+ * };
+ *
+ * type UsuarioNullish = Nullish<Usuario>;
+ *
+ * // Exemplos de valores válidos
+ * const u1: UsuarioNullish = {};
+ * const u2: UsuarioNullish = { id: null };
+ * const u3: UsuarioNullish = { nome: 'Maria', ativo: null };
+ */
+export type Nullish<TBase> = { [Key in keyof TBase]?: TBase[Key] | null; };
+//#endregion
+//# sourceMappingURL=nullish.d.ts.map