ts-gems 3.12.0 → 4.0.0

package/docs/api/readonly.md

@@ -0,0 +1,150 @@
+# Readonly
+
+Source: [`lib/readonly.d.ts`](../../lib/readonly.d.ts)
+
+Adds `readonly` modifiers — the mirror image of [Mutable](mutable.md). See
+[the `Deep*`/`Deeper*` convention](../api.md#the-deep--deeper-convention) and
+the runtime [`asReadonly` cast helpers](helpers.md#runtime-cast-helpers).
+
+## `ReadonlySome<T, K>`
+
+Marks only the properties named in `K` as `readonly`; every other property is
+untouched.
+
+```ts
+import type { ReadonlySome } from 'ts-gems';
+
+interface Row {
+  id: number;
+  name: string;
+}
+
+type LockedId = ReadonlySome<Row, 'id'>;
+// { readonly id: number; name: string }
+```
+
+## `DeepReadonly<T>`
+
+Makes every property `readonly`, recursively into nested objects. Array-typed
+properties are left exactly as-is — use `DeeperReadonly` to also make array
+elements readonly.
+
+```ts
+import type { DeepReadonly } from 'ts-gems';
+
+interface Config {
+  name: string;
+  server: { host: string; port: number };
+  tags: string[];
+}
+
+type FrozenConfig = DeepReadonly<Config>;
+// {
+//   readonly name: string;
+//   readonly server: { readonly host: string; readonly port: number };
+//   readonly tags: string[]; // untouched - it's an array
+// }
+```
+
+## `DeeperReadonly<T>`
+
+Like `DeepReadonly`, but also makes the element type of array-typed
+properties readonly. Tuples are left untouched.
+
+```ts
+import type { DeeperReadonly } from 'ts-gems';
+
+interface Config {
+  servers: { host: string }[];
+  range: [number, number]; // tuple
+}
+
+type FrozenConfig = DeeperReadonly<Config>;
+// {
+//   readonly servers: { readonly host: string }[];
+//   readonly range: [number, number]; // tuple - unchanged
+// }
+```
+
+> Note: `DeeperReadonly` makes the **property** and the **element type**
+> readonly; it does not turn the array itself into a `readonly T[]` — push/
+> pop on the array reference is still possible unless you also apply
+> `Readonly<...>` around the whole property yourself. This also means that
+> if the _input_ property was already a `readonly T[]`, `DeeperReadonly`
+> normalizes it back down to a plain `T[]` wrapper (only the element type's
+> readonly-ness is guaranteed, not the wrapper's).
+
+## `ReadonlyKeys<T>`
+
+Returns the union of property names in `T` that **are** `readonly`
+(`keyof PickReadonly<T>`).
+
+```ts
+import type { ReadonlyKeys } from 'ts-gems';
+
+interface Row {
+  readonly id: number;
+  name: string;
+}
+
+type Locked = ReadonlyKeys<Row>; // 'id'
+```
+
+## `PickReadonly<T>` / `OmitReadonly<T>`
+
+Pick (or omit) only the properties that **are** `readonly`.
+
+```ts
+import type { OmitReadonly, PickReadonly } from 'ts-gems';
+
+interface Row {
+  readonly id: number;
+  name: string;
+}
+
+type OnlyReadonly = PickReadonly<Row>; // { readonly id: number }
+type OnlyMutable = OmitReadonly<Row>; // { name: string }
+```
+
+## `DeepPickReadonly<T>` / `DeepOmitReadonly<T>`
+
+The deep versions of `PickReadonly`/`OmitReadonly` — nested objects are
+filtered the same way, recursively.
+
+```ts
+import type { DeepOmitReadonly } from 'ts-gems';
+
+interface Row {
+  readonly id: number;
+  meta: { readonly createdBy: string; label: string };
+}
+
+type Editable = DeepOmitReadonly<Row>;
+// { meta: { label: string } }
+```
+
+A mutable property is always kept by `DeepOmitReadonly`, no matter its value
+type — including `null`:
+
+```ts
+type I1 = { a: null; readonly b: null };
+type Result = DeepOmitReadonly<I1>; // { a: null }
+```
+
+## `DeeperPickReadonly<T>` / `DeeperOmitReadonly<T>`
+
+Like `DeepPickReadonly`/`DeepOmitReadonly`, but also recurses into array
+elements. Tuples are preserved as-is (never split into a homogeneous array).
+
+```ts
+import type { DeeperOmitReadonly } from 'ts-gems';
+
+interface Row {
+  readonly id: number;
+  tags: { readonly createdBy: string; label: string }[];
+  point: readonly [number, number];
+}
+
+type Editable = DeeperOmitReadonly<Row>;
+// { tags: { label: string }[]; point: readonly [number, number] }
+```

package/docs/api/required.md

@@ -0,0 +1,146 @@
+# Required
+
+Source: [`lib/required.d.ts`](../../lib/required.d.ts)
+
+Makes properties required (and strips `undefined` from their type). See
+[the `Deep*`/`Deeper*` convention](../api.md#the-deep--deeper-convention) and
+the runtime [`asRequired` cast helpers](helpers.md#runtime-cast-helpers).
+
+## `RequiredSome<T, K>`
+
+Marks only the properties named in `K` as required; the rest of `T` is left
+exactly as declared.
+
+```ts
+import type { RequiredSome } from 'ts-gems';
+
+interface UpdateUserInput {
+  name?: string;
+  email?: string;
+}
+
+type CreateUserInput = RequiredSome<UpdateUserInput, 'name'>;
+// { name: string; email?: string }
+```
+
+## `DeepRequired<T>`
+
+Like the built-in `Required<T>`, but also makes nested object properties
+required, recursively. Array-typed properties are left as-is.
+
+```ts
+import type { DeepRequired } from 'ts-gems';
+
+interface Config {
+  name?: string;
+  server?: { host?: string; port?: number };
+  tags?: string[];
+}
+
+type FullConfig = DeepRequired<Config>;
+// {
+//   name: string;
+//   server: { host: string; port: number };
+//   tags: string[]; // required now, but its element type is untouched
+// }
+```
+
+## `DeeperRequired<T>`
+
+Like `DeepRequired`, but also makes array element properties required.
+Tuples are left untouched.
+
+```ts
+import type { DeeperRequired } from 'ts-gems';
+
+interface Config {
+  servers?: { host?: string }[];
+  range?: [number, number]; // tuple
+}
+
+type FullConfig = DeeperRequired<Config>;
+// {
+//   servers: { host: string }[];
+//   range: [number, number]; // tuple - unchanged
+// }
+```
+
+`DeeperRequired` keeps its array-awareness through every level of nesting —
+an array several objects deep is still processed, not just one at the top:
+
+```ts
+interface Nested {
+  a?: { b?: { c?: number }[] };
+}
+
+type Result = DeeperRequired<Nested>;
+// { a: { b: { c: number }[] } }
+```
+
+## `RequiredKeys<T>`
+
+Returns the union of property names in `T` that are required
+(`keyof PickRequired<T>`).
+
+```ts
+import type { RequiredKeys } from 'ts-gems';
+
+interface Row {
+  id: number;
+  nickname?: string;
+}
+
+type Required = RequiredKeys<Row>; // 'id'
+```
+
+## `PickRequired<T>` / `OmitRequired<T>`
+
+Pick (or omit) only the properties that are required.
+
+```ts
+import type { OmitRequired, PickRequired } from 'ts-gems';
+
+interface Row {
+  id: number;
+  nickname?: string;
+}
+
+type OnlyRequired = PickRequired<Row>; // { id: number }
+type OnlyOptional = OmitRequired<Row>; // { nickname?: string }
+```
+
+## `DeepPickRequired<T>` / `DeepOmitRequired<T>`
+
+The deep versions of `PickRequired`/`OmitRequired`. A property is only ever
+recursed into when **it is itself optional** — a required property is
+dropped by `DeepOmitRequired` outright, without inspecting what's inside it
+(there would be nothing to "omit the required parts of", since the whole
+property is required in the first place).
+
+```ts
+import type { DeepOmitRequired } from 'ts-gems';
+
+interface Row {
+  id: number; // required -> dropped entirely
+  meta?: { label?: string; note: string }; // optional -> kept & recursed
+}
+
+type Optional = DeepOmitRequired<Row>;
+// { meta?: { label?: string } } - `note` was required, so it's dropped too
+```
+
+## `DeeperPickRequired<T>` / `DeeperOmitRequired<T>`
+
+Like `DeepPickRequired`/`DeepOmitRequired`, but also recurses into array
+elements. Tuples are preserved as-is.
+
+```ts
+import type { DeeperOmitRequired } from 'ts-gems';
+
+interface Row {
+  tags?: { label?: string; note: string }[];
+}
+
+type Optional = DeeperOmitRequired<Row>;
+// { tags?: { label?: string }[] }
+```

package/docs/api/type-check.md

@@ -0,0 +1,246 @@
+# Type Guards
+
+Source: [`lib/type-check.d.ts`](../../lib/type-check.d.ts)
+
+Every type below follows the same shape:
+
+```ts
+type IfX<T, Y = true, N = false> = /* ... */;
+```
+
+It checks a condition about `T` and resolves to `Y` when the condition holds,
+`N` otherwise. `Y`/`N` default to the literal types `true`/`false`, which lets
+you use them directly as compile-time assertions:
+
+```ts
+import type { IfNever } from 'ts-gems';
+
+type Check = IfNever<never>; // true
+type Check2 = IfNever<string>; // false
+```
+
+...or pass real types through `Y`/`N` to build a conditional transform:
+
+```ts
+type OrString<T> = IfNever<T, string, T>; // replace `never` with `string`
+```
+
+## The `*OrAny` variants
+
+`IfTupleOrAny`, `IfPrimitiveOrAny`, `IfObjectOrAny`, `IfFunctionOrAny`, and
+`IfClassOrAny` are convenience wrappers that treat `any` as an automatic
+match, since `any` would otherwise fail every structural check:
+
+```ts
+type IfXOrAny<T, Y = true, N = false> =
+  IfAny<T> extends true ? Y : IfX<T, Y, N>;
+```
+
+```ts
+import type { IfObject, IfObjectOrAny } from 'ts-gems';
+
+type A = IfObject<any>; // false - `any` doesn't structurally match "object"
+type B = IfObjectOrAny<any>; // true
+```
+
+## `IfAny<T, Y, N>`
+
+Detects the `any` type specifically — distinct from `unknown`, `never`, and
+every other type. Uses the well-known `0 extends 1 & T` trick, since `any` is
+the only type where this holds.
+
+```ts
+import type { IfAny } from 'ts-gems';
+
+type A = IfAny<any>; // true
+type B = IfAny<unknown>; // false
+type C = IfAny<never>; // false
+type D = IfAny<string>; // false
+```
+
+## `IfNever<T, Y, N>`
+
+```ts
+import type { IfNever } from 'ts-gems';
+
+type A = IfNever<never>; // true
+type B = IfNever<undefined>; // false
+type C = IfNever<any>; // false
+```
+
+## `IfUndefined<T, Y, N>` / `IfNull<T, Y, N>` / `IfUnknown<T, Y, N>`
+
+Exact-type checks for `undefined`, `null`, and `unknown` respectively, each
+implemented via [`IfEquals`](#ifequalst1-t2-y-n).
+
+```ts
+import type { IfNull, IfUndefined, IfUnknown } from 'ts-gems';
+
+type A = IfUndefined<undefined>; // true
+type B = IfUndefined<null>; // false
+
+type C = IfNull<null>; // true
+type D = IfNull<undefined>; // false
+
+type E = IfUnknown<unknown>; // true
+type F = IfUnknown<any>; // false - `any` is not `unknown`
+```
+
+## `IfNullish<T, Y, N>`
+
+`true` for `null` **or** `undefined`.
+
+```ts
+import type { IfNullish } from 'ts-gems';
+
+type A = IfNullish<null>; // true
+type B = IfNullish<undefined>; // true
+type C = IfNullish<0>; // false
+```
+
+## `IfSymbol<T, Y, N>`
+
+`true` only for the general `symbol` type — **not** for a specific `unique
+symbol` (e.g. the type of a `const x = Symbol('x')`), which is a distinct,
+narrower type.
+
+```ts
+import type { IfSymbol } from 'ts-gems';
+
+const uniqueSym = Symbol('x');
+
+type A = IfSymbol<symbol>; // true
+type B = IfSymbol<typeof uniqueSym>; // false - a *specific* unique symbol
+type C = IfSymbol<string>; // false
+```
+
+## `IfTuple<T, Y, N>`
+
+`true` for a fixed-length tuple (`[string, number]`, `[]`, ...); `false` for
+a variable-length array (`string[]`) or anything else. Distinguishes the two
+by checking whether `T['length']` is a literal number (tuple) or the general
+`number` type (array).
+
+```ts
+import type { IfTuple } from 'ts-gems';
+
+type A = IfTuple<[string, number]>; // true
+type B = IfTuple<[]>; // true
+type C = IfTuple<string[]>; // false
+type D = IfTuple<any>; // false
+```
+
+> This is the type that decides, throughout the whole library, whether a
+> tuple gets left untouched by `Deeper*` transforms instead of being
+> collapsed into a homogeneous array — see [the `Deep*`/`Deeper*`
+> convention](../api.md#the-deep--deeper-convention).
+
+## `IfPrimitive<T, Y, N>`
+
+`true` for any [`Primitive`](types.md#primitive): `string | number | bigint |
+boolean | symbol | null | undefined`, plus `any`. `false` for objects,
+arrays, functions, and classes.
+
+```ts
+import type { IfPrimitive } from 'ts-gems';
+
+type A = IfPrimitive<string>; // true
+type B = IfPrimitive<null>; // true
+type C = IfPrimitive<{}>; // false
+type D = IfPrimitive<Function>; // false
+```
+
+## `IfEmptyObject<T, Y, N>`
+
+`true` only for the exact type `{}`.
+
+```ts
+import type { IfEmptyObject } from 'ts-gems';
+
+type A = IfEmptyObject<{}>; // true
+type B = IfEmptyObject<{ x: 1 }>; // false
+type C = IfEmptyObject<undefined>; // false
+```
+
+## `IfObject<T, Y, N>`
+
+`true` for anything structurally an `object` that isn't a primitive,
+`Function`, or array (arrays get their own check via [`IfTuple`](#iftuplet-y-n)
+or a plain `T[]` test elsewhere in the library).
+
+```ts
+import type { IfObject } from 'ts-gems';
+
+type A = IfObject<{ x: 1 }>; // true
+type B = IfObject<object>; // true
+type C = IfObject<any[]>; // false
+type D = IfObject<Function>; // false
+type E = IfObject<null>; // false
+```
+
+## `IfFunction<T, Y, N>`
+
+`true` for any function type (including arrow functions), `false` for a
+constructor/class reference (see [`IfClass`](#ifclasst-y-n) for that case).
+
+```ts
+import type { IfFunction } from 'ts-gems';
+
+class Foo {}
+
+type A = IfFunction<() => void>; // true
+type B = IfFunction<(a: string) => boolean>; // true
+type C = IfFunction<typeof Foo>; // false - a constructor, not a plain function
+type D = IfFunction<Foo>; // false - an instance
+```
+
+## `IfClass<T, Y, N>`
+
+`true` when `T` is a constructor/class reference — i.e. it matches
+[`Type<any>`](types.md#typet--any) (`new (...args: any[]) => any`).
+
+```ts
+import type { IfClass } from 'ts-gems';
+
+class Foo {}
+function bar() {}
+
+type A = IfClass<typeof Foo>; // true
+type B = IfClass<typeof bar>; // false
+type C = IfClass<Foo>; // false - an instance is not a constructor
+```
+
+## `IfEquals<T1, T2, Y, N>`
+
+Exact, deeply-structural type equality — the classic
+[Matt McCutchen conditional-type trick](https://github.com/Microsoft/TypeScript/issues/27024#issuecomment-421529650),
+extended in this library to also compare object shapes recursively. Two
+types are equal only if they are mutually and exactly assignable, including
+modifiers (`?`, `readonly`).
+
+```ts
+import type { IfEquals } from 'ts-gems';
+
+type A = IfEquals<number, number>; // true
+type B = IfEquals<number, number | string>; // false
+type C = IfEquals<{ x: 1 }, { x?: 1 }>; // false - optionality differs
+type D = IfEquals<any, any>; // true
+type E = IfEquals<any, unknown>; // false
+```
+
+## `IfCompatible<T1, T2, Y, N>`
+
+A looser, one- or two-way _assignability_ check (unlike `IfEquals`, which
+requires exact equality). Used internally to compare function parameter/return
+compatibility, and handles `any`/`unknown`/`never`/`null`/`undefined`
+specially so they behave as you'd expect at the call site rather than by
+strict structural rules.
+
+```ts
+import type { IfCompatible } from 'ts-gems';
+
+type A = IfCompatible<number, number | string>; // true
+type B = IfCompatible<any, number>; // true
+type C = IfCompatible<{}, number>; // false
+type D = IfCompatible<() => void, (a: string) => void>; // true
+```