{"id":15248,"library":"tsdef","title":"TypeScript Definition Utilities","description":"tsdef is a TypeScript utility library that provides a curated collection of common type definitions and aliases to simplify complex type patterns and enhance code readability in TypeScript projects. It aims to reduce boilerplate and improve type safety by offering widely applicable utility types such as `Nullable`, `NonNull`, `MaybePromise`, and various `Props` modifiers (e.g., `NonNullProps`, `WritableProps`). The current stable version is 0.0.14. As a pre-1.0 release, its release cadence is likely irregular, and breaking changes might occur more frequently than with a semantically versioned stable library. It differentiates itself by being a pure type-only library, meaning it introduces zero runtime overhead and focuses exclusively on type-system improvements, making it suitable for projects that prioritize strict type integrity without adding to the JavaScript bundle size.","status":"maintenance","version":"0.0.14","language":"javascript","source_language":"en","source_url":"https://github.com/joonhocho/tsdef","tags":["javascript","TypeScript","common","patterns","shortcuts","snippets","definitions","utility","gist","typescript"],"install":[{"cmd":"npm install tsdef","lang":"bash","label":"npm"},{"cmd":"yarn add tsdef","lang":"bash","label":"yarn"},{"cmd":"pnpm add tsdef","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Nullable = require('tsdef').Nullable;","symbol":"Nullable","correct":"import { Nullable } from 'tsdef';"},{"note":"All exports from tsdef are named exports; there is no default export. Incorrectly attempting a default import will result in a TypeScript error.","wrong":"import NonNull from 'tsdef';","symbol":"NonNull","correct":"import { NonNull } from 'tsdef';"},{"note":"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.","symbol":"AnyFunction","correct":"import { AnyFunction } from 'tsdef';"}],"quickstart":{"code":"import { Nullable, NonNull, MaybePromise, MaybeArray } from 'tsdef';\n\n// Define a string that can also be null or undefined\nconst nullableString: Nullable<string> = 'hello';\nconst anotherNullableString: Nullable<string> = null; // This is OK\n// const invalidNullableString: Nullable<string> = undefined; // Also OK if 'nil' includes undefined\n\n// Define a string that explicitly cannot be null\nconst nonNullString: NonNull<string | null> = 'world';\n// const invalidNonNullString: NonNull<string | null> = null; // Type error: Type 'null' is not assignable to type 'string'.\n\n// Define a value that might be a promise or the value itself\ntype User = { id: string; name: string };\nconst getUserSync = (): User => ({ id: '1', name: 'Alice' });\nconst getUserAsync = (): Promise<User> => Promise.resolve({ id: '2', name: 'Bob' });\n\nconst maybePromiseUser: MaybePromise<User> = getUserSync();\nconst anotherMaybePromiseUser: MaybePromise<User> = getUserAsync();\n\n// Define a value that might be a single item or an array of items\nconst singleItem: MaybeArray<string> = 'item';\nconst multipleItems: MaybeArray<string> = ['item1', 'item2'];\n\nconsole.log(nullableString); // Output: hello\nconsole.log(nonNullString);  // Output: world","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The `tsdef` package was either not installed, installed incorrectly, or TypeScript is not configured to find type declaration files.","error":"Cannot find module 'tsdef' or its corresponding type declarations."},{"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.","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.","error":"Type 'null' is not assignable to type 'NonNull<string>'."},{"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.","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.","error":"Property 'someProperty' does not exist on type 'NonNilProps<MyType>'."}],"ecosystem":"npm"}