{"id":27648151,"url":"https://github.com/goldziher/type-predicates","last_synced_at":"2025-07-19T12:37:49.903Z","repository":{"id":57167180,"uuid":"391436899","full_name":"Goldziher/type-predicates","owner":"Goldziher","description":"A comprehensive collection of type-guards, type assertions and related utils","archived":false,"fork":false,"pushed_at":"2025-05-25T13:24:27.000Z","size":954,"stargazers_count":55,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-03T12:11:12.820Z","etag":null,"topics":["type-assertions","type-guards","typescript","utilities-library"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Goldziher.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-07-31T18:37:58.000Z","updated_at":"2025-05-29T08:03:07.000Z","dependencies_parsed_at":"2023-01-23T19:00:15.011Z","dependency_job_id":"6b4a679e-93d0-4b92-8514-800ce0dcb602","html_url":"https://github.com/Goldziher/type-predicates","commit_stats":null,"previous_names":["goldziher/type-predicates","tool-belt/type-predicates"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/Goldziher/type-predicates","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Goldziher%2Ftype-predicates","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Goldziher%2Ftype-predicates/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Goldziher%2Ftype-predicates/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Goldziher%2Ftype-predicates/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Goldziher","download_url":"https://codeload.github.com/Goldziher/type-predicates/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Goldziher%2Ftype-predicates/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265934248,"owners_count":23852092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["type-assertions","type-guards","typescript","utilities-library"],"created_at":"2025-04-24T02:33:12.182Z","updated_at":"2025-07-19T12:37:49.898Z","avatar_url":"https://github.com/Goldziher.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @tool-belt/type-predicates\n\n[![npm version](https://img.shields.io/npm/v/@tool-belt/type-predicates.svg)](https://www.npmjs.com/package/@tool-belt/type-predicates)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA comprehensive collection of performant type guards and assertions with excellent TypeScript support. This library serves as a drop-in replacement for Node.js's `util/types` module, while offering significantly better type inference, more extensive functionality, and cross-platform compatibility.\n\n## Features\n\n- 🚀 **Better TypeScript Support**: Advanced type inference with generics and precise type narrowing\n- 📦 **Zero Dependencies**: Lightweight and self-contained\n- 🌳 **Tree-Shakeable**: Full ESM support for optimal bundle sizes\n- 🌐 **Cross-Platform**: Works in browsers, Node.js, and any JavaScript environment\n- ✅ **Thorough Testing**: Comprehensive test coverage for both runtime behavior and type safety\n- 🔧 **Extensive API**: More comprehensive than Node.js built-in utilities\n- 🎯 **Type Guards \u0026 Assertions**: Every type check is available in both guard and assertion forms\n\n## Installation\n\n```bash\nnpm install @tool-belt/type-predicates\n```\n\n```bash\npnpm add @tool-belt/type-predicates\n```\n\n```bash\nyarn add @tool-belt/type-predicates\n```\n\n## Browser Support\n\nThis library works in all modern browsers and Node.js environments. It's compiled to ES modules and CommonJS, with full support for tree-shaking to minimize bundle size.\n\n## Key Differences from `node:util/types`\n\n### 1. Superior TypeScript Support\n\n```typescript\n// node:util/types\nimport { isArray } from 'util/types';\nconst arr: unknown = ['a', 'b', 'c'];\nif (isArray(arr)) {\n    // arr is typed as \"unknown[]\" - not very useful\n}\n\n// @tool-belt/type-predicates\nimport { isArray } from '@tool-belt/type-predicates';\nconst arr: unknown = ['a', 'b', 'c'];\nif (isArray\u003cstring\u003e(arr)) {\n    // arr is typed as \"string[]\" - much better!\n}\n```\n\n### 2. Type Assertions\n\n```typescript\nimport { assertIsString, assertIsArray } from '@tool-belt/type-predicates';\n\n// Throws TypeError if not a string\nassertIsString(value);\n// After this line, TypeScript knows 'value' is a string\n\n// With custom error messages\nassertIsArray(data, { message: 'Configuration must be an array' });\n\n// With nested validation\nassertIsArray\u003cnumber\u003e(data, {\n    valueValidator: (item) =\u003e typeof item === 'number',\n    message: 'Expected array of numbers',\n});\n```\n\n### 3. Composable Type Guards\n\n```typescript\nimport {\n    isUnion,\n    isString,\n    isNumber,\n    createTypeGuard,\n} from '@tool-belt/type-predicates';\n\n// Combine multiple type guards\nconst isStringOrNumber = isUnion(isString, isNumber);\n\n// Create custom type guards\nconst isPositiveNumber = createTypeGuard\u003cnumber\u003e(\n    (value) =\u003e isNumber(value) \u0026\u0026 value \u003e 0,\n);\n```\n\n## API Overview\n\n### Type Guards\n\nEvery guard returns a type predicate for TypeScript type narrowing:\n\n```typescript\nimport {\n    isArray,\n    isObject,\n    isString,\n    isNumber,\n    isBoolean,\n    isFunction,\n    isPromise,\n    isMap,\n    isSet,\n    isDate,\n    isRegExp,\n    isError,\n    isNull,\n    isUndefined,\n    isNullish,\n    isDefined,\n    // ... and many more\n} from '@tool-belt/type-predicates';\n\n// Use in conditionals\nif (isString(value)) {\n    // TypeScript knows 'value' is a string here\n    console.log(value.toUpperCase());\n}\n\n// Use with array methods\nconst strings = mixedArray.filter(isString);\n// strings is typed as string[]\n```\n\n### Type Assertions\n\nEvery guard has a corresponding assertion that throws on failure:\n\n```typescript\nimport {\n    assertIsArray,\n    assertIsObject,\n    assertIsString,\n    // ... all guards have assertion versions\n} from '@tool-belt/type-predicates';\n\nfunction processConfig(config: unknown) {\n    assertIsObject(config);\n    // TypeScript now knows config is an object\n\n    assertIsString(config.name, { message: 'Config name must be a string' });\n    // config.name is now typed as string\n}\n```\n\n### Advanced Features\n\n#### Deep Validation\n\n```typescript\nimport { isArray, isObject, isString } from '@tool-belt/type-predicates';\n\n// Validate array elements\nconst isStringArray = (value: unknown): value is string[] =\u003e\n    isArray(value, { valueValidator: isString });\n\n// Validate object values\nconst isStringRecord = (value: unknown): value is Record\u003cstring, string\u003e =\u003e\n    isObject(value, { valueValidator: isString });\n```\n\n#### Utility Functions\n\n```typescript\nimport { createTypeGuard, isUnion } from '@tool-belt/type-predicates';\n\n// Create custom guards\nconst isNonEmptyString = createTypeGuard\u003cstring\u003e(\n    (value) =\u003e isString(value) \u0026\u0026 value.length \u003e 0,\n);\n\n// Union types\nconst isNumberOrString = isUnion(isNumber, isString);\n```\n\n## Complete API Reference\n\n### Basic Types\n\n- `isString` / `assertIsString`\n- `isNumber` / `assertIsNumber`\n- `isBoolean` / `assertIsBoolean`\n- `isBigInt` / `assertIsBigInt`\n- `isSymbol` / `assertIsSymbol`\n- `isUndefined` / `assertIsUndefined`\n- `isNull` / `assertIsNull`\n- `isNullish` / `assertIsNullish`\n- `isDefined` / `assertIsDefined`\n- `isNotNull` / `assertIsNotNull`\n- `isNotNullish` / `assertIsNotNullish`\n\n### Object Types\n\n- `isObject` / `assertIsObject` - Checks if value is an object (not null)\n- `isPlainObject` / `assertIsPlainObject` - Checks if value is a plain object (not a class instance)\n- `isRecord` / `assertIsRecord` - Validates an object with specific key and value types\n- `isEmptyObject` / `assertIsEmptyObject` - Checks if object has no own properties\n- `isBoxedPrimitive` / `assertIsBoxedPrimitive` - Checks if value is a boxed primitive\n\n### Collection Types\n\n- `isArray` / `assertIsArray` - Validates arrays with optional element type checking\n- `isEmptyArray` / `assertIsEmptyArray` - Checks if array has length of 0\n- `isNonEmptyArray` / `assertIsNonEmptyArray` - Checks if array has length \u003e 0\n- `isMap` / `assertIsMap` - Validates Map objects with optional key/value type checking\n- `isSet` / `assertIsSet` - Validates Set objects with optional value type checking\n- `isWeakMap` / `assertIsWeakMap` - Checks if value is a WeakMap\n- `isWeakSet` / `assertIsWeakSet` - Checks if value is a WeakSet\n\n### Function Types\n\n- `isFunction` / `assertIsFunction` - Checks if value is a function\n- `isAsyncFunction` / `assertIsAsyncFunction` - Checks if value is an async function\n- `isGeneratorFunction` / `assertIsGeneratorFunction` - Checks if value is a generator function\n- `isAsyncGeneratorFunction` / `assertIsAsyncGeneratorFunction` - Checks if value is an async generator function\n\n### Iterator Types\n\n- `isIterable` / `assertIsIterable` - Validates iterable objects\n- `isIterator` / `assertIsIterator` - Validates iterator objects\n- `isGenerator` / `assertIsGenerator` - Checks if value is a generator\n- `isAsyncGenerator` / `assertIsAsyncGenerator` - Checks if value is an async generator\n- `isAsyncIterable` / `assertIsAsyncIterable` - Validates async iterable objects\n- `isMapIterator` / `assertIsMapIterator` - Checks if value is a Map iterator\n- `isSetIterator` / `assertIsSetIterator` - Checks if value is a Set iterator\n\n### Error Types\n\n- `isError` / `assertIsError` - Checks if value is an Error\n- `isNativeError` / `assertIsNativeError` - Checks if value is a native Error type\n\n### Number Utilities\n\n- `isNaN` / `assertIsNaN` - Checks if value is NaN\n- `isFinite` / `assertIsFinite` - Checks if value is a finite number\n- `isInteger` / `assertIsInteger` - Checks if value is an integer\n- `isSafeInteger` / `assertIsSafeInteger` - Checks if value is a safe integer\n\n### String Utilities\n\n- `isEmptyString` / `assertIsEmptyString` - Checks if string has length of 0\n- `isNonEmptyString` / `assertIsNonEmptyString` - Checks if string has length \u003e 0\n\n### Buffer and TypedArray Types\n\n- `isBuffer` / `assertIsBuffer` - Checks if value is a Buffer\n- `isArrayBuffer` / `assertIsArrayBuffer` - Checks if value is an ArrayBuffer\n- `isSharedArrayBuffer` / `assertIsSharedArrayBuffer` - Checks if value is a SharedArrayBuffer\n- `isAnyArrayBuffer` / `assertIsAnyArrayBuffer` - Checks if value is any kind of ArrayBuffer\n- `isArrayBufferView` / `assertIsArrayBufferView` - Checks if value is an ArrayBufferView\n- `isDataView` / `assertIsDataView` - Checks if value is a DataView\n- `isTypedArray` / `assertIsTypedArray` - Checks if value is any TypedArray\n- Various specific TypedArray checkers (Int8Array, Uint8Array, etc.)\n\n### Other Built-in Types\n\n- `isDate` / `assertIsDate` - Checks if value is a Date\n- `isRegExp` / `assertIsRegExp` - Checks if value is a RegExp\n- `isPromise` / `assertIsPromise` - Checks if value is a Promise\n- `isArgumentsObject` / `assertIsArgumentsObject` - Checks if value is an arguments object\n\n## Creating Custom Type Guards\n\nYou can create your own type guards using the `createTypeGuard` utility:\n\n```typescript\nimport { createTypeGuard, isNumber } from '@tool-belt/type-predicates';\n\n// Create a type guard for positive numbers\nconst isPositiveNumber = createTypeGuard\u003cnumber\u003e(\n    (value) =\u003e isNumber(value) \u0026\u0026 value \u003e 0,\n);\n\n// Use it like any other guard\nif (isPositiveNumber(value)) {\n    // TypeScript knows value is a number here\n    // Runtime has verified value \u003e 0\n}\n```\n\n## Error Handling Examples\n\n```typescript\nimport { isError } from '@tool-belt/type-predicates';\n\ntry {\n    // Your code that might throw\n} catch (error) {\n    // TypeScript types catch blocks as 'unknown'\n    if (isError(error)) {\n        console.error(error.message);\n        console.error(error.stack);\n    }\n}\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoldziher%2Ftype-predicates","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoldziher%2Ftype-predicates","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoldziher%2Ftype-predicates/lists"}