TypeScript Definition Utilities

Common errors

• Cannot find module 'tsdef' or its corresponding type declarations.

  cause The `tsdef` package was either not installed, installed incorrectly, or TypeScript is not configured to find type declaration files.
  fix Ensure `tsdef` is installed as a dev dependency: `npm install -D tsdef` or `yarn add -D tsdef`. Also, verify your `tsconfig.json` includes `"typeRoots": ["./node_modules/@types", "./node_modules"]` or similar settings to allow TypeScript to discover type declarations.

• Type 'null' is not assignable to type 'NonNull<string>'.

  cause Attempting to assign `null` (or `undefined` for `NonNil`) to a type that explicitly removes `null` (or `nil`) from its possible values. This is a correct type error, indicating a violation of the `NonNull` (or `NonNil`) constraint.
  fix Refactor your code to ensure that values assigned to `NonNull` types are indeed guaranteed to be non-null. This often involves null checks (`if (value !== null)`) or using optional chaining (`?.`) and nullish coalescing (`??`) operators before assignment or usage.

• Property 'someProperty' does not exist on type 'NonNilProps<MyType>'.

  cause When applying `NonNilProps` (or `NonNullProps`, `NonUndefinedProps`), if the original type `MyType` had optional properties, these `Props` utility types do not automatically make them required. They only ensure that *if* a property exists, its value is non-nil/non-null/non-undefined.
  fix If you intend for properties to be required *and* non-nil, combine `NonNilProps<T>` with `RequiredProps<T>` or directly use `Required<NonNilProps<T>>` to achieve the desired strictness.

Warnings

• gotcha tsdef is currently at version 0.0.14, indicating it is in a pre-1.0 development phase. This means that semantic versioning might not be strictly adhered to, and breaking changes could be introduced in minor or even patch releases without explicit major version bumps. Users should review changelogs carefully when upgrading.
  Fix: Pin the exact version of `tsdef` in your `package.json` (e.g., `"tsdef": "0.0.14"`) and manually review release notes before updating to new versions, especially for critical production applications.
• gotcha As a purely type-definition library, `tsdef` should always be installed as a development dependency (`-D` or `--save-dev`) as it produces no runtime code. Installing it as a regular dependency (`-S` or `--save`) will needlessly add it to your production bundle's dependency tree, although it won't increase the actual runtime bundle size.
  Fix: Ensure installation with `npm install -D tsdef` or `yarn add -D tsdef`. If already installed incorrectly, move it from `dependencies` to `devDependencies` in `package.json`.
• gotcha The extensive set of utility types provided by `tsdef` (and similar libraries like `ts-essentials` or `type-fest`) can sometimes lead to naming conflicts or overlap with built-in TypeScript utility types or those from other libraries if not managed carefully.
  Fix: Be mindful of potential naming collisions. If a conflict occurs, consider importing with an alias (e.g., `import { Nullable as TsdefNullable } from 'tsdef';`) or evaluating if a native TypeScript utility type serves the same purpose.

Install

• npm install tsdef npm
• yarn add tsdef yarn
• pnpm add tsdef pnpm

Imports

• Nullable
  wrong:

  const Nullable = require('tsdef').Nullable;

  correct:

  import { Nullable } from 'tsdef';

  tsdef exports only TypeScript types, not runtime values. CommonJS 'require' syntax for types is incorrect and will result in a runtime error or a TypeScript error depending on compiler settings.
• NonNull
  wrong:

  import NonNull from 'tsdef';

  correct:

  import { NonNull } from 'tsdef';

  All exports from tsdef are named exports; there is no default export. Incorrectly attempting a default import will result in a TypeScript error.
• AnyFunction

  import { AnyFunction } from 'tsdef';

  This type alias helps define variables that are expected to be any kind of function, improving clarity and type safety for function parameters or return types.

Quickstart

This quickstart demonstrates the usage of `Nullable`, `NonNull`, `MaybePromise`, and `MaybeArray` type utilities from `tsdef` to handle common TypeScript type patterns, showcasing how to define types that explicitly allow or disallow null/undefined, or encapsulate potential promises or arrays.

import { Nullable, NonNull, MaybePromise, MaybeArray } from 'tsdef';

// Define a string that can also be null or undefined
const nullableString: Nullable<string> = 'hello';
const anotherNullableString: Nullable<string> = null; // This is OK
// const invalidNullableString: Nullable<string> = undefined; // Also OK if 'nil' includes undefined

// Define a string that explicitly cannot be null
const nonNullString: NonNull<string | null> = 'world';
// const invalidNonNullString: NonNull<string | null> = null; // Type error: Type 'null' is not assignable to type 'string'.

// Define a value that might be a promise or the value itself
type User = { id: string; name: string };
const getUserSync = (): User => ({ id: '1', name: 'Alice' });
const getUserAsync = (): Promise<User> => Promise.resolve({ id: '2', name: 'Bob' });

const maybePromiseUser: MaybePromise<User> = getUserSync();
const anotherMaybePromiseUser: MaybePromise<User> = getUserAsync();

// Define a value that might be a single item or an array of items
const singleItem: MaybeArray<string> = 'item';
const multipleItems: MaybeArray<string> = ['item1', 'item2'];

console.log(nullableString); // Output: hello
console.log(nonNullString);  // Output: world