ts-gems 3.12.0 → 4.0.0

package/docs/api/nullish.md

@@ -0,0 +1,66 @@
+# Nullish
+
+Source: [`lib/nullish.d.ts`](../../lib/nullish.d.ts)
+
+Makes properties optional **and** nullable (`T[K] | null`) — useful for
+"patch"-style inputs where a client can send `null` to explicitly clear a
+field, as opposed to omitting the key to leave it unchanged. See [the
+`Deep*`/`Deeper*` convention](../api.md#the-deep--deeper-convention) and
+[`PatchDTO`](dto.md#patchdtot-x--never) which builds on `DeeperNullish`.
+
+## `NullishObject<T>`
+
+```ts
+import type { NullishObject } from 'ts-gems';
+
+interface User {
+  name: string;
+  age: number;
+}
+
+type PatchUser = NullishObject<User>;
+// { name?: string | null; age?: number | null }
+```
+
+## `DeepNullish<T>`
+
+Like `NullishObject`, but also makes nested object properties optional and
+nullable, recursively. Array-typed properties are left as-is (only wrapped
+in `| null` at their own level).
+
+```ts
+import type { DeepNullish } from 'ts-gems';
+
+interface Config {
+  name: string;
+  server: { host: string; port: number };
+  tags: string[];
+}
+
+type PatchConfig = DeepNullish<Config>;
+// {
+//   name?: string | null;
+//   server?: { host?: string | null; port?: number | null } | null;
+//   tags?: string[] | null;
+// }
+```
+
+## `DeeperNullish<T>`
+
+Like `DeepNullish`, but also recurses into array elements. Tuples are
+preserved as-is (only wrapped in `| null`).
+
+```ts
+import type { DeeperNullish } from 'ts-gems';
+
+interface Config {
+  servers: { host: string }[];
+  range: [number, number]; // tuple
+}
+
+type PatchConfig = DeeperNullish<Config>;
+// {
+//   servers?: ({ host?: string | null }[]) | null;
+//   range?: [number, number] | null; // tuple - unchanged, just nullable
+// }
+```

package/docs/api/omit-never.md

@@ -0,0 +1,62 @@
+# OmitNever
+
+Source: [`lib/omit-never.d.ts`](../../lib/omit-never.d.ts)
+
+Removes properties whose value type is `never` — handy after a chain of
+conditional-type transforms leaves some properties resolved to `never`
+(which should behave like "this key doesn't exist"). See [the `Deep*`/
+`Deeper*` convention](../api.md#the-deep--deeper-convention).
+
+## `OmitNever<T>`
+
+```ts
+import type { OmitNever } from 'ts-gems';
+
+type MyType = {
+  a: string;
+  b: number;
+  c?: never;
+};
+
+type Result = OmitNever<MyType>;
+// { a: string; b: number }
+```
+
+## `DeepOmitNever<T>`
+
+Like `OmitNever`, but also applies the same removal recursively to nested
+object properties. Array-typed properties are left as-is.
+
+```ts
+import type { DeepOmitNever } from 'ts-gems';
+
+type MyType = {
+  a: string;
+  nested: { b: number; c: never };
+  list: { b: number; c: never }[];
+};
+
+type Result = DeepOmitNever<MyType>;
+// {
+//   a: string;
+//   nested: { b: number };
+//   list: { b: number; c: never }[]; // untouched - it's an array
+// }
+```
+
+## `DeeperOmitNever<T>`
+
+Like `DeepOmitNever`, but also recurses into array elements. Tuples are
+preserved as-is.
+
+```ts
+import type { DeeperOmitNever } from 'ts-gems';
+
+type MyType = {
+  list: { b: number; c: never }[];
+  pair: [string, never];
+};
+
+type Result = DeeperOmitNever<MyType>;
+// { list: { b: number }[]; pair: [string, never] } - tuple untouched
+```

package/docs/api/omit-undefined.md

@@ -0,0 +1,60 @@
+# OmitUndefined
+
+Source: [`lib/omit-undefined.d.ts`](../../lib/omit-undefined.d.ts)
+
+Removes properties whose value type is exactly `undefined` (properties
+typed `T | undefined`, i.e. optional-looking-but-not-`?`, are narrowed
+rather than removed unless the whole type collapses to `never`). See
+[the `Deep*`/`Deeper*` convention](../api.md#the-deep--deeper-convention).
+
+## `OmitUndefined<T>`
+
+```ts
+import type { OmitUndefined } from 'ts-gems';
+
+type MyType = {
+  a?: number;
+  b: string;
+  c: undefined;
+};
+
+type Result = OmitUndefined<MyType>;
+// { a?: number; b: string } - `c` (exactly `undefined`) is dropped
+```
+
+## `DeepOmitUndefined<T>`
+
+Like `OmitUndefined`, but also applies the same removal recursively to
+nested object properties. Array-typed properties are left as-is.
+
+```ts
+import type { DeepOmitUndefined } from 'ts-gems';
+
+type MyType = {
+  nested: { a?: string; b: undefined };
+  list: { a?: string; b: undefined }[];
+};
+
+type Result = DeepOmitUndefined<MyType>;
+// {
+//   nested: { a?: string };
+//   list: { a?: string; b: undefined }[]; // untouched - it's an array
+// }
+```
+
+## `DeeperOmitUndefined<T>`
+
+Like `DeepOmitUndefined`, but also recurses into array elements. Tuples are
+preserved as-is.
+
+```ts
+import type { DeeperOmitUndefined } from 'ts-gems';
+
+type MyType = {
+  list: { a?: string; b: undefined }[];
+  pair: [string, undefined];
+};
+
+type Result = DeeperOmitUndefined<MyType>;
+// { list: { a?: string }[]; pair: [string, undefined] } - tuple untouched
+```

package/docs/api/omit.md

@@ -0,0 +1,99 @@
+# Omit
+
+Source: [`lib/omit.d.ts`](../../lib/omit.d.ts)
+
+Removing properties by key, by kind (function vs. data), or by value type.
+See [Pick](pick.md) for the inverse operations, and [the `Deep*`/`Deeper*`
+convention](../api.md#the-deep--deeper-convention) for `DeepOmitTypes`/
+`DeeperOmitTypes`.
+
+## `StrictOmit<T, X>`
+
+Like the built-in `Omit<T, K>`, but also drops any remaining key whose value
+type is `never` (after stripping `undefined`) — symmetric with
+[`StrictPick`](pick.md#strictpickt-x), so picking and omitting the same key
+set never disagree about `never`-typed properties.
+
+```ts
+import type { StrictOmit } from 'ts-gems';
+
+interface Row {
+  a?: number;
+  b: string;
+  c: never;
+}
+
+type Result = StrictOmit<Row, 'b'>;
+// { a?: number } - `c` is dropped too, it's `never`
+```
+
+## `OmitFunctions<T>`
+
+Removes every property whose value is a function — the inverse of
+[`PickFunctions`](pick.md#pickfunctionst).
+
+```ts
+import type { OmitFunctions } from 'ts-gems';
+
+interface Service {
+  name: string;
+  start(): void;
+}
+
+type Data = OmitFunctions<Service>;
+// { name: string }
+```
+
+## `OmitTypes<T, X>`
+
+Removes properties whose value type is assignable to or from `X`, and
+narrows the remaining properties' types by excluding `X` from their union
+(via `Exclude<T[K], X>`) — the inverse of
+[`PickTypes`](pick.md#picktypest-x).
+
+```ts
+import type { OmitTypes } from 'ts-gems';
+
+interface Row {
+  a: number;
+  b: boolean;
+  c: string | number | boolean;
+}
+
+type Result = OmitTypes<Row, number>;
+// { b: boolean; c: string | boolean } - `a` is dropped, `number` removed from `c`
+```
+
+## `DeepOmitTypes<T, X>`
+
+Like `OmitTypes`, but also applies the same removal recursively to nested
+object properties. Array-typed properties are left as-is.
+
+```ts
+import type { DeepOmitTypes } from 'ts-gems';
+
+interface Row {
+  a: number;
+  nested: { a: number; b: string };
+}
+
+type Result = DeepOmitTypes<Row, number>;
+// { nested: { b: string } }
+```
+
+## `DeeperOmitTypes<T, X>`
+
+Like `DeepOmitTypes`, but also recurses into array elements. Tuples are
+preserved as-is.
+
+```ts
+import type { DeeperOmitTypes } from 'ts-gems';
+
+interface Row {
+  items: { a: number; b: string }[];
+  pair: [string, number]; // tuple
+}
+
+type Result = DeeperOmitTypes<Row, number>;
+// { items: { b: string }[]; pair: [string, number] } - tuple untouched
+```

package/docs/api/opaque.md

@@ -0,0 +1,56 @@
+# Opaque
+
+Source: [`lib/opaque.d.ts`](../../lib/opaque.d.ts)
+
+## `Opaque<T, N extends string>`
+
+```ts
+type Opaque<T, N extends string> = T & {
+  readonly [Symbols.base]: N;
+  readonly [Symbols.brand]: N;
+};
+```
+
+Creates a _branded_ type: structurally still based on `T`, but tagged with a
+unique string literal `N` so that two `Opaque` types built from the same
+base `T` are no longer interchangeable by accident. This is the classic
+["nominal typing" workaround](https://michalzalecki.com/nominal-typing-in-typescript/)
+for a structurally-typed language — useful for IDs, currency amounts, or any
+primitive that shouldn't be swappable with another primitive of the same
+underlying type.
+
+```ts
+import type { Opaque } from 'ts-gems';
+
+type UserId = Opaque<number, 'UserId'>;
+type ProductId = Opaque<number, 'ProductId'>;
+
+function getUser(id: UserId) {
+  /* ... */
+}
+
+declare const userId: UserId;
+declare const productId: ProductId;
+declare const rawNumber: number;
+
+getUser(userId); // ok
+getUser(productId); // type error - different brand, even though both are `number`
+getUser(rawNumber); // type error - a plain number isn't branded at all
+```
+
+Because `Opaque<T, N>` is an intersection with `T`, a branded value is still
+usable _as_ its base type — the restriction only goes one way:
+
+```ts
+const id = 1 as UserId;
+const n: number = id; // ok - a UserId structurally satisfies `number`
+```
+
+You create a branded value with a type assertion (there's no runtime
+wrapping — the brand only exists at the type level):
+
+```ts
+function toUserId(id: number): UserId {
+  return id as UserId;
+}
+```

package/docs/api/partial.md

@@ -0,0 +1,135 @@
+# Partial
+
+Source: [`lib/partial.d.ts`](../../lib/partial.d.ts)
+
+Makes properties optional. See [the `Deep*`/`Deeper*`
+convention](../api.md#the-deep--deeper-convention) and the runtime
+[`asPartial` cast helpers](helpers.md#runtime-cast-helpers).
+
+## `PartialSome<T, K>`
+
+Marks only the properties named in `K` as optional; the rest of `T` is
+required exactly as declared.
+
+```ts
+import type { PartialSome } from 'ts-gems';
+
+interface CreateUserInput {
+  name: string;
+  email: string;
+  role: string;
+}
+
+type UpdateUserInput = PartialSome<CreateUserInput, 'email' | 'role'>;
+// { name: string; email?: string; role?: string }
+```
+
+## `DeepPartial<T>`
+
+Like the built-in `Partial<T>`, but also makes nested object properties
+optional, recursively. Array-typed properties are left as-is.
+
+```ts
+import type { DeepPartial } from 'ts-gems';
+
+interface Config {
+  name: string;
+  server: { host: string; port: number };
+  tags: string[];
+}
+
+type PartialConfig = DeepPartial<Config>;
+// {
+//   name?: string;
+//   server?: { host?: string; port?: number };
+//   tags?: string[]; // untouched - it's an array
+// }
+```
+
+## `DeeperPartial<T>`
+
+Like `DeepPartial`, but also makes array element properties optional.
+Tuples are left untouched.
+
+```ts
+import type { DeeperPartial } from 'ts-gems';
+
+interface Config {
+  servers: { host: string }[];
+  range: [number, number]; // tuple
+}
+
+type PartialConfig = DeeperPartial<Config>;
+// {
+//   servers?: { host?: string }[];
+//   range?: [number, number]; // tuple - unchanged
+// }
+```
+
+## `OptionalKeys<T>`
+
+Returns the union of property names in `T` that are optional.
+
+```ts
+import type { OptionalKeys } from 'ts-gems';
+
+interface Row {
+  id: number;
+  nickname?: string;
+}
+
+type Optional = OptionalKeys<Row>; // 'nickname'
+```
+
+## `PickOptional<T>` / `OmitOptional<T>`
+
+Pick (or omit) only the properties that are optional. Implemented in terms
+of [`OmitRequired`/`PickRequired`](required.md), since "optional" and
+"required" partition every property into exactly two sets.
+
+```ts
+import type { OmitOptional, PickOptional } from 'ts-gems';
+
+interface Row {
+  id: number;
+  nickname?: string;
+}
+
+type OnlyOptional = PickOptional<Row>; // { nickname?: string }
+type OnlyRequired = OmitOptional<Row>; // { id: number }
+```
+
+## `DeepPickOptional<T>` / `DeepOmitOptional<T>`
+
+The deep versions of `PickOptional`/`OmitOptional` — nested objects are
+filtered the same way, recursively. Delegates to
+[`DeepOmitRequired`/`DeepPickRequired`](required.md).
+
+```ts
+import type { DeepOmitOptional } from 'ts-gems';
+
+interface Row {
+  id: number;
+  meta: { label?: string; note: string };
+}
+
+type Required = DeepOmitOptional<Row>;
+// { id: number; meta: { note: string } }
+```
+
+## `DeeperPickOptional<T>` / `DeeperOmitOptional<T>`
+
+Like `DeepPickOptional`/`DeepOmitOptional`, but also recurses into array
+elements. Delegates to
+[`DeeperOmitRequired`/`DeeperPickRequired`](required.md).
+
+```ts
+import type { DeeperOmitOptional } from 'ts-gems';
+
+interface Row {
+  tags: { label?: string; note: string }[];
+}
+
+type Required = DeeperOmitOptional<Row>;
+// { tags: { note: string }[] }
+```

package/docs/api/pick.md

@@ -0,0 +1,115 @@
+# Pick
+
+Source: [`lib/pick.d.ts`](../../lib/pick.d.ts)
+
+Selecting properties by key, by kind (function vs. data), or by value type.
+See [Omit](omit.md) for the inverse operations.
+
+## `StrictPick<T, X>`
+
+Like the built-in `Pick<T, K>`, but also drops any selected key whose value
+type is `never` (after stripping `undefined`) — consistent with how the rest
+of the library treats `never`-typed properties as "absent".
+
+```ts
+import type { StrictPick } from 'ts-gems';
+
+interface Row {
+  a?: number;
+  b: string;
+  c: never;
+}
+
+type Result = StrictPick<Row, 'a' | 'c'>;
+// { a?: number } - `c` is dropped, it's `never`
+```
+
+## `PickFunctions<T>`
+
+Keeps only the properties whose value is a function.
+
+```ts
+import type { PickFunctions } from 'ts-gems';
+
+interface Service {
+  name: string;
+  start(): void;
+  stop(): void;
+}
+
+type Methods = PickFunctions<Service>;
+// { start(): void; stop(): void }
+```
+
+## `PickTypes<T, X>`
+
+Keeps properties whose value type is assignable to or from `X` (a
+bidirectional compatibility check, not exact equality — useful for grabbing
+every property that is "roughly" of a given type, unions included).
+
+```ts
+import type { PickTypes } from 'ts-gems';
+
+interface Row {
+  a: number;
+  b: string;
+  c: string | number | boolean;
+}
+
+type NumberLike = PickTypes<Row, number>;
+// { a: number; c: string | number | boolean }
+```
+
+## `StrictPickTypes<T, X>`
+
+Like `PickTypes`, but additionally excludes properties typed `unknown`,
+`any`, or `{}` from matching — useful when you want type-based filtering
+without accidentally sweeping up untyped/loosely-typed properties.
+
+```ts
+import type { StrictPickTypes } from 'ts-gems';
+
+interface Row {
+  a: number;
+  b: unknown;
+  c: any;
+}
+
+type NumberLike = StrictPickTypes<Row, number>;
+// { a: number } - `b` and `c` are excluded even though they're compatible
+```
+
+## `FunctionKeys<T>` / `NonFunctionKeys<T>`
+
+Returns the union of property names whose value is (or isn't) a function.
+
+```ts
+import type { FunctionKeys, NonFunctionKeys } from 'ts-gems';
+
+interface Service {
+  name: string;
+  start(): void;
+}
+
+type Methods = FunctionKeys<Service>; // 'start'
+type Data = NonFunctionKeys<Service>; // 'name'
+```
+
+## `KeysOfTypes<T, X>` / `StrictKeysOfTypes<T, X>`
+
+Returns the union of property names matching `X`, per the same rules as
+[`PickTypes`](#picktypest-x)/[`StrictPickTypes`](#strictpicktypest-x)
+respectively.
+
+```ts
+import type { KeysOfTypes, StrictKeysOfTypes } from 'ts-gems';
+
+interface Row {
+  a: number;
+  b: string;
+  c: unknown;
+}
+
+type Keys = KeysOfTypes<Row, number>; // 'a' | 'c' - `unknown` matches everything
+type StrictKeys = StrictKeysOfTypes<Row, number>; // 'a' - `c` (unknown) excluded
+```