ts-gems 3.12.0 → 4.0.0

package/README.md

@@ -1,18 +1,130 @@
+<p align="center">
+  <img src="docs/logo.svg" alt="ts-gems logo" width="200" height="200" />
+</p>
+
 # ts-gems
 
 [![NPM Version][npm-image]][npm-url]
 [![NPM Downloads][downloads-image]][downloads-url]
 [![CI Tests][ci-test-image]][ci-test-url]
 
+**Think of it as lodash — but every function operates on `types`, not values, and runs at compile time for free.**
+
+Quick question: what's the type of `Partial<{ user: { name: string } }>['user']`?
+
+If you guessed `{ name?: string }`, that's the intuitive answer — and it's wrong.
+TypeScript's built-in `Partial<T>` only reaches the *first* level. The real
+answer is `{ name: string }` — still fully required underneath, still ready
+to blow up at runtime the moment you try to build one incrementally.
+
+```ts
+type Config = { user: { name: string; age: number } };
+
+type Shallow = Partial<Config>;
+// { user?: { name: string; age: number } }   <- still required inside!
+
+type Deep = DeepPartial<Config>;
+// { user?: { name?: string; age?: number } }  <- actually usable
+```
+
+That one gap is the whole reason this library exists. `Partial`, `Required`,
+`Readonly`, and `Pick`/`Omit` all share the same blind spot: they stop at the
+surface. ts-gems finishes what TypeScript started — and then keeps going into
+places you didn't know needed a type yet.
+
+## A few things that might surprise you
+
+**Freeze a config tree, arrays included, in one line:**
+
+```ts
+import type { DeeperReadonly } from 'ts-gems';
+
+type FrozenConfig = DeeperReadonly<{
+  servers: { host: string; port: number }[];
+}>;
+// every level is readonly — including inside the array elements
+```
+
+**Turn any interface into an API-safe DTO — no functions, no symbols, recursively:**
+
+```ts
+import type { DTO } from 'ts-gems';
+
+class User {
+  name = '';
+  greet() {}
+  [Symbol.iterator]() {}
+}
+
+type UserResponse = DTO<User>;
+// { name: string } — methods and symbol keys are gone, nested objects too
+```
+
+**Stop mixing up two `number`s that were never meant to meet:**
+
+```ts
+import type { Opaque } from 'ts-gems';
+
+type UserId = Opaque<number, 'UserId'>;
+type OrderId = Opaque<number, 'OrderId'>;
+
+function cancelOrder(id: OrderId) {
+  /* ... */
+}
+
+declare const userId: UserId;
+cancelOrder(userId); // ✗ compile error — nominally different, even though both are `number`
+```
+
+**Merge types without the intersection trap:**
+
+```ts
+type A = { name: string };
+type B = { name: Date }; // overlapping key, different type
+
+type Bad = A & B; // name: string & Date — a type nothing can satisfy. Oops.
+type Good = Combine<A, B>; // { name: string } — A simply wins
+```
+
+None of this is magic. It's ~60 small, focused utility types, each solving
+one specific gap — composable, dependency-free, and fully documented with
+runnable examples.
+
+## Explore the full toolkit
+
+📖 **[Browse the complete API reference →](docs/api.md)**
+
+| Category | What it does |
+| --- | --- |
+| [`Deep*` / `Deeper*` family](docs/api.md#the-deep--deeper-convention) | `Mutable`, `Readonly`, `Partial`, `Required`, `Nullish` — that finally reach nested objects and arrays |
+| [`DTO` / `PartialDTO` / `PatchDTO`](docs/api/dto.md) | Turn any class or interface into a clean transfer-object shape |
+| [`Pick` / `Omit` family](docs/api/pick.md) | Select by key, by function-vs-data, or by matching value type |
+| [`Opaque`](docs/api/opaque.md) | Nominal typing / branded primitives for TypeScript's structural type system |
+| [`Combine`](docs/api/combine.md) | Merge types without the `&` intersection trap |
+| [20+ type guards](docs/api/type-check.md) | `IfAny`, `IfNever`, `IfEquals`, `IfTuple`, `IfCompatible`, and more, for building your own conditional types |
+| [`And` / `Or`](docs/api/logical.md) | Compile-time boolean logic to combine several guards into one |
+
 ## Installation
 
 ```bash
-$ npm install ts-gems --save
+npm install ts-gems --save
+```
+
+```ts
+import { DeepPartial, DTO, Opaque, StrictOmit } from 'ts-gems';
 ```
+
+Everything is exported from the package root — no sub-path imports, no
+runtime cost. It's types all the way down (with twelve tiny `as*` cast
+helpers thrown in, purely for ergonomics).
+
 ## Node Compatibility
+
 - node >= 16.x
+
 ## License
-ts-gems is available under [MIT](LICENSE) license.
+
+ts-gems is available under the [MIT](LICENSE) license.
 
 [npm-image]: https://img.shields.io/npm/v/ts-gems
 [npm-url]: https://npmjs.org/package/ts-gems

package/docs/api/combine.md

@@ -0,0 +1,48 @@
+# Combine
+
+Source: [`lib/combine.d.ts`](../../lib/combine.d.ts)
+
+## `Combine<T1, T2, T3 = {}, T4 = {}>`
+
+```ts
+type Combine<T1, T2, T3 = {}, T4 = {}> = T1 &
+  Omit<T2, keyof T1> &
+  Omit<T3, keyof T1 | keyof T2> &
+  Omit<T4, keyof T1 | keyof T2 | keyof T3>;
+```
+
+Merges up to four object types into one, **without** merging the types of
+overlapping properties — unlike a plain intersection (`T1 & T2`), which
+would combine both types of a shared key into `T1[K] & T2[K]`, `Combine`
+lets the earliest argument win outright for any key present in more than
+one input.
+
+```ts
+import type { Combine } from 'ts-gems';
+
+interface Base {
+  id: string;
+  name: string;
+}
+
+interface Timestamps {
+  name: Date; // overlaps with `Base.name` - Base wins
+  createdAt: Date;
+}
+
+type Entity = Combine<Base, Timestamps>;
+// { id: string; name: string; createdAt: Date }
+// (compare to `Base & Timestamps`, where `name` would be `string & Date` = `never`)
+```
+
+Precedence follows argument order — `T1` wins over `T2`, which wins over
+`T3`, which wins over `T4`:
+
+```ts
+type A = { x: 1 };
+type B = { x: 2; y: 2 };
+type C = { x: 3; y: 3; z: 3 };
+
+type Result = Combine<A, B, C>;
+// { x: 1; y: 2; z: 3 }
+```

package/docs/api/dto.md

@@ -0,0 +1,115 @@
+# DTO
+
+Source: [`lib/dto.d.ts`](../../lib/dto.d.ts)
+
+Turns any type into a plain Data Transfer Object shape: strips function
+properties and symbol-keyed properties, and always deep-processes nested
+objects and arrays (there's no shallow/`Deep` variant — `DTO` behaves like
+the `Deeper*` members of [the convention](../api.md#the-deep--deeper-convention)).
+Tuples are left untouched, same as everywhere else in the library.
+
+## `DTO<T, X = never>`
+
+```ts
+import type { DTO } from 'ts-gems';
+
+interface User {
+  name: string;
+  age?: number;
+  greet(): void; // function - removed
+  [Symbol.iterator]: () => Iterator<unknown>; // symbol key - removed
+}
+
+type UserDTO = DTO<User>;
+// { name: string; age?: number }
+```
+
+Nested objects and arrays are always processed, recursively:
+
+```ts
+interface Order {
+  id: string;
+  createdBy: { name: string; greet(): void };
+  items: { sku: string; validate(): boolean }[];
+}
+
+type OrderDTO = DTO<Order>;
+// {
+//   id: string;
+//   createdBy: { name: string };
+//   items: { sku: string }[];
+// }
+```
+
+### The `X` parameter
+
+The second type parameter, `X`, is unioned into **every** remaining
+property's value type (through `NonNullable<T[K] | X>`, applied at every
+nesting level). This is handy for tagging every field of the DTO with a
+shared extra type — for example, a sentinel used to represent "field
+explicitly not selected" in a partial-response GraphQL/RPC layer:
+
+```ts
+import type { DTO } from 'ts-gems';
+
+const NOT_SELECTED = Symbol('not-selected');
+type NotSelected = typeof NOT_SELECTED;
+
+interface User {
+  name: string;
+  age?: number;
+}
+
+type SparseUserDTO = DTO<User, NotSelected>;
+// { name: string | NotSelected; age?: number | NotSelected }
+```
+
+> Because `X` is combined via `NonNullable<T[K] | X>`, passing `null` or
+> `undefined` as `X` has no visible effect — both are immediately stripped
+> again. Use a non-nullish sentinel (a literal, a branded/[`Opaque`](opaque.md)
+> type, or a `unique symbol` as above) if you need one.
+
+## `PartialDTO<T, X = never>`
+
+```ts
+type PartialDTO<T, X = never> = DeeperPartial<DTO<T, X>>;
+```
+
+`DTO<T, X>` with every property (including nested ones and array elements)
+made optional via [`DeeperPartial`](partial.md#deeperpartialt) — a common
+shape for "create" endpoint request bodies where every field may be omitted.
+
+```ts
+import type { PartialDTO } from 'ts-gems';
+
+interface User {
+  name: string;
+  profile: { bio: string };
+}
+
+type CreateUserBody = PartialDTO<User>;
+// { name?: string; profile?: { bio?: string } }
+```
+
+## `PatchDTO<T, X = never>`
+
+```ts
+type PatchDTO<T, X = never> = DeeperNullish<DTO<T, X>>;
+```
+
+`DTO<T, X>` with every property (including nested ones and array elements)
+made optional **and** nullable via [`DeeperNullish`](nullish.md#deepernullisht)
+— a common shape for "patch"/"update" endpoint request bodies, where `null`
+means "clear this field" and omitting the key means "leave it unchanged".
+
+```ts
+import type { PatchDTO } from 'ts-gems';
+
+interface User {
+  name: string;
+  profile: { bio: string };
+}
+
+type UpdateUserBody = PatchDTO<User>;
+// { name?: string | null; profile?: { bio?: string | null } | null }
+```

package/docs/api/helpers.md

@@ -0,0 +1,97 @@
+# Helpers
+
+Source: [`lib/helpers.d.ts`](../../lib/helpers.d.ts)
+
+## `IfNoDeepValue<T>`
+
+```ts
+type IfNoDeepValue<T> = /* ... */; // true | false
+```
+
+`true` when `T` should be treated as a **leaf** by every `Deep*`/`Deeper*`
+transform in this library — i.e. left untouched instead of being recursed
+into. This is the type that defines "leaf" for [the `Deep*`/`Deeper*`
+convention](../api.md#the-deep--deeper-convention): `true` for `any`, every
+[`Builtin`](types.md#builtin) type, a [tuple](type-check.md#iftuplet-y-n), a
+`Function`, a class/constructor reference, `Map`/`ReadonlyMap`/`WeakMap`/
+`Set`/`ReadonlySet`/`WeakSet`, or any array; `false` for a plain object.
+
+```ts
+import type { IfNoDeepValue } from 'ts-gems';
+
+type A = IfNoDeepValue<string>; // true
+type B = IfNoDeepValue<any>; // true
+type C = IfNoDeepValue<[string, number]>; // true - a tuple
+type D = IfNoDeepValue<Date>; // true
+type E = IfNoDeepValue<Map<string, number>>; // true
+type F = IfNoDeepValue<{ a: string }>; // false - a plain object, gets recursed into
+```
+
+You'll rarely need this directly unless you're writing your own `Deep*`-style
+recursive type and want it to treat leaves consistently with the rest of the
+library.
+
+## `ValuesOf<T>`
+
+```ts
+type ValuesOf<T> = T[keyof T];
+```
+
+Returns the union of every property value type in `T` — the value-side
+equivalent of `keyof`.
+
+```ts
+import type { ValuesOf } from 'ts-gems';
+
+interface Row {
+  a: number;
+  b: string;
+  c?: boolean;
+}
+
+type Values = ValuesOf<Row>; // number | string | boolean | undefined
+```
+
+## Runtime cast helpers
+
+Twelve tiny runtime functions, declared in
+[`lib/index.d.ts`](../../lib/index.d.ts) and implemented as a no-op identity
+function at runtime (`lib/index.js`). They exist purely so you can _cast_ a
+value's static type without an `as` expression or reaching for a type
+import at the call site:
+
+```ts
+declare function asMutable<T>(x: T): Mutable<T>;
+declare function asDeepMutable<T>(x: T): DeepMutable<T>;
+declare function asDeeperMutable<T>(x: T): DeeperMutable<T>;
+
+declare function asReadonly<T>(x: T): Readonly<T>;
+declare function asDeepReadonly<T>(x: T): DeepReadonly<T>;
+declare function asDeeperReadonly<T>(x: T): DeeperReadonly<T>;
+
+declare function asPartial<T>(x: T): Partial<T>;
+declare function asDeepPartial<T>(x: T): DeepPartial<T>;
+declare function asDeeperPartial<T>(x: T): DeeperPartial<T>;
+
+declare function asRequired<T>(x: T): Required<T>;
+declare function asDeepRequired<T>(x: T): DeepRequired<T>;
+declare function asDeeperRequired<T>(x: T): DeeperRequired<T>;
+```
+
+```ts
+import { asMutable } from 'ts-gems';
+
+interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+function move(p: Point) {
+  const mutablePoint = asMutable(p); // same object reference, `Mutable<Point>` type
+  mutablePoint.x += 1; // ok - no cast needed, and no runtime cost
+}
+```
+
+Because these are real functions (not just types), they also work well with
+plain JavaScript editors/tools that only understand runtime code — the
+identity behavior at runtime means they're always safe to call.

package/docs/api/logical.md

@@ -0,0 +1,48 @@
+# Logical
+
+Source: [`lib/logical.d.ts`](../../lib/logical.d.ts)
+
+Compile-time boolean logic over up to six type-level "truthy" values, useful
+when composing several [type guards](type-check.md) into one condition. A
+value counts as "falsy" when it is `undefined`, `null`, or the literal type
+`false`; anything else (including `never`... see below) counts as "truthy".
+
+Unused trailing parameters default to the operator's identity value (`true`
+for `And`, `false` for `Or`), so you can pass anywhere from 2 to 6 arguments.
+
+## `And<T1, T2, T3?, T4?, T5?, T6?>`
+
+`true` only if every provided argument is truthy.
+
+```ts
+import type { And } from 'ts-gems';
+
+type A = And<true, true>; // true
+type B = And<true, false>; // false
+type C = And<true, true, true, true, true, true>; // true
+type D = And<true, never>; // false - `never` counts as falsy here
+```
+
+A common use is combining several `If*` guards:
+
+```ts
+import type { And, IfObject, IfNever } from 'ts-gems';
+
+type IsPlainRequiredObject<T> = And<IfObject<T>, IfNever<T, false, true>>;
+```
+
+## `Or<T1, T2, T3?, T4?, T5?, T6?>`
+
+`true` if **any** provided argument is truthy.
+
+```ts
+import type { Or } from 'ts-gems';
+
+type A = Or<false, false>; // false
+type B = Or<false, true>; // true
+type C = Or<false, false, false, false, false, true>; // true
+```
+
+This is the exact building block the [`Pick`](pick.md)/[`Omit`](omit.md)
+family uses internally to combine several exclusion criteria into one key
+filter — e.g. "omit this key if it's `never` **or** if it's a function".

package/docs/api/mutable.md

@@ -0,0 +1,164 @@
+# Mutable
+
+Source: [`lib/mutable.d.ts`](../../lib/mutable.d.ts)
+
+Strips `readonly` modifiers. See [the `Deep*`/`Deeper*` convention](../api.md#the-deep--deeper-convention)
+for what "deeply" means here, and the runtime [`asMutable` cast
+helpers](helpers.md#runtime-cast-helpers).
+
+## `Mutable<T>`
+
+Removes `readonly` from every top-level property. Properties whose value is
+`never` (after stripping `undefined`) are dropped, matching the rest of the
+library's "never means absent" convention.
+
+```ts
+import type { Mutable } from 'ts-gems';
+
+interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+type MutablePoint = Mutable<Point>;
+// { x: number; y: number }
+
+const p: MutablePoint = { x: 1, y: 2 };
+p.x = 3; // ok - no longer readonly
+```
+
+## `MutableSome<T, K>`
+
+Removes `readonly` from only the properties named in `K`; every other
+property is untouched.
+
+```ts
+import type { MutableSome } from 'ts-gems';
+
+interface Row {
+  readonly id: number;
+  readonly name: string;
+  readonly createdAt: Date;
+}
+
+type EditableRow = MutableSome<Row, 'name'>;
+// { readonly id: number; name: string; readonly createdAt: Date }
+```
+
+## `DeepMutable<T>`
+
+Like `Mutable`, but also strips `readonly` from nested object properties.
+Array-typed properties are left exactly as they are (see the convention
+table) — use `DeeperMutable` to also transform array element types.
+
+```ts
+import type { DeepMutable } from 'ts-gems';
+
+interface Config {
+  readonly name: string;
+  readonly server: {
+    readonly host: string;
+    readonly port: number;
+  };
+  readonly tags: string[];
+}
+
+type MutableConfig = DeepMutable<Config>;
+// {
+//   name: string;
+//   server: { host: string; port: number };
+//   tags: string[]; // untouched - it's an array
+// }
+```
+
+## `DeeperMutable<T>`
+
+Like `DeepMutable`, but also makes the element type of array-typed
+properties mutable. Tuples are left untouched (their fixed shape is
+preserved as-is).
+
+```ts
+import type { DeeperMutable } from 'ts-gems';
+
+interface Config {
+  readonly server: { readonly host: string };
+  readonly servers: { readonly host: string }[];
+  readonly range: readonly [number, number]; // tuple
+}
+
+type MutableConfig = DeeperMutable<Config>;
+// {
+//   server: { host: string };
+//   servers: { host: string }[]; // element type made mutable too
+//   range: readonly [number, number]; // tuple - unchanged
+// }
+```
+
+## `MutableKeys<T>`
+
+Returns the union of property names in `T` that are **not** `readonly`.
+
+```ts
+import type { MutableKeys } from 'ts-gems';
+
+interface Row {
+  readonly id: number;
+  name: string;
+}
+
+type Editable = MutableKeys<Row>; // 'name'
+```
+
+## `PickMutable<T>` / `OmitMutable<T>`
+
+Pick (or omit) only the properties that are **not** `readonly`. These are
+implemented in terms of [`OmitReadonly`/`PickReadonly`](readonly.md), since
+"mutable" and "readonly" partition every property into exactly two sets.
+
+```ts
+import type { OmitMutable, PickMutable } from 'ts-gems';
+
+interface Row {
+  readonly id: number;
+  name: string;
+}
+
+type OnlyMutable = PickMutable<Row>; // { name: string }
+type OnlyReadonly = OmitMutable<Row>; // { readonly id: number }
+```
+
+## `DeepPickMutable<T>` / `DeepOmitMutable<T>`
+
+The deep versions of `PickMutable`/`OmitMutable` — nested objects are
+filtered the same way, recursively. Delegates to
+[`DeepOmitReadonly`/`DeepPickReadonly`](readonly.md).
+
+```ts
+import type { DeepPickMutable } from 'ts-gems';
+
+interface Row {
+  readonly id: number;
+  meta: { readonly createdBy: string; label: string };
+}
+
+type Editable = DeepPickMutable<Row>;
+// { meta: { label: string } }
+```
+
+## `DeeperPickMutable<T>` / `DeeperOmitMutable<T>`
+
+Like `DeepPickMutable`/`DeepOmitMutable`, but also recurses into array
+elements. Delegates to
+[`DeeperOmitReadonly`/`DeeperPickReadonly`](readonly.md).
+
+```ts
+import type { DeeperPickMutable } from 'ts-gems';
+
+interface Row {
+  readonly id: number;
+  tags: { readonly createdBy: string; label: string }[];
+}
+
+type Editable = DeeperPickMutable<Row>;
+// { tags: { label: string }[] }
+```

package/docs/api/non-nullable.md

@@ -0,0 +1,68 @@
+# UnNullish
+
+Source: [`lib/non-nullable.d.ts`](../../lib/non-nullable.d.ts)
+
+Removes `null` and `undefined` from every property's value type (via
+`NonNullable`), and drops the key entirely if nothing is left afterwards.
+See [the `Deep*`/`Deeper*` convention](../api.md#the-deep--deeper-convention).
+
+## `UnNullish<T>`
+
+**Shallow** — only top-level properties are un-nullished. Nested `null`/
+`undefined` values, inside an object or array property, are left exactly as
+they are. Use [`DeepUnNullish`](#deepunnullisht) or
+[`DeeperUnNullish`](#deeperunnullisht) to reach into nested structures too.
+
+```ts
+import type { UnNullish } from 'ts-gems';
+
+type MyType = {
+  a: string | null;
+  b?: number | null;
+  nested: { c: string | null } | null;
+};
+
+type Result = UnNullish<MyType>;
+// {
+//   a: string;
+//   b?: number;
+//   nested: { c: string | null }; // the outer `| null` is gone, the inner one isn't
+// }
+```
+
+## `DeepUnNullish<T>`
+
+Like `UnNullish`, but also un-nullishes nested object properties,
+recursively. Array-typed properties are left as-is.
+
+```ts
+import type { DeepUnNullish } from 'ts-gems';
+
+type MyType = {
+  nested: { c: string | null } | null;
+  list: { c: string | null }[] | null;
+};
+
+type Result = DeepUnNullish<MyType>;
+// {
+//   nested: { c: string };
+//   list: { c: string | null }[]; // untouched - it's an array
+// }
+```
+
+## `DeeperUnNullish<T>`
+
+Like `DeepUnNullish`, but also recurses into array elements. Tuples are
+preserved as-is (their own `| null` is still stripped).
+
+```ts
+import type { DeeperUnNullish } from 'ts-gems';
+
+type MyType = {
+  list: { c: string | null }[] | null;
+  pair: [string, number] | null; // tuple
+};
+
+type Result = DeeperUnNullish<MyType>;
+// { list: { c: string }[]; pair: [string, number] } - tuple untouched
+```