# πŸ§ͺ pp-is > πŸ”Ž Tiny, fast, zero-dependency type checking for JavaScript. [![npm version](https://img.shields.io/npm/v/pp-is.svg)](https://www.npmjs.com/package/pp-is) [![license](https://img.shields.io/npm/l/pp-is.svg)](./LICENSE.txt) [![bundle size](https://img.shields.io/bundlephobia/minzip/pp-is)](https://bundlephobia.com/package/pp-is) **43 functions** to validate everything β€” from primitives to DOM, emails to UUIDs. Zero dependencies. Works everywhere. ```js ppIs.isEmail('hello@world.com') // βœ… true ppIs.isInteger(42) // βœ… true ppIs.isUUID('550e8400-e29b...') // βœ… true ppIs.isAlpha('Hello') // βœ… true ``` --- ## ⚑ Quick Start ### πŸ“¦ Install ```bash npm i pp-is ``` ### 🌐 CDN ```html ``` ### πŸš€ First Use ```html ``` ```js // Or as ES module import ppIs from 'pp-is' ppIs.isString('hello') // true ppIs.isNull(null) // true ``` --- ## 🎯 Why pp-is? | Feature | pp-is | lodash | validator.js | |---------|:-----:|:------:|:------------:| | Bundle size (min+gz) | **~2KB** | ~7KB | ~30KB | | Zero dependencies | βœ… | βœ… | ❌ | | Callback system | βœ… | ❌ | ❌ | | DOM checks | βœ… | ❌ | ❌ | | ES Modules | βœ… | partial | ❌ | | TypeScript friendly | βœ… | βœ… | βœ… | | Functions count | **43** | ~15 | ~50 | --- ## πŸ“¦ What's Inside? | Category | Functions | What it covers | |----------|-----------|----------------| | 🧱 **Primitives** | `isArray` `isString` `isNumber` `isBoolean` `isFunction` `isObject` `isDate` `isNull` `isUndefined` `isRegExp` `isPromise` `isSymbol` `isBigInt` | Type checks for all JS primitives | | πŸ”’ **Numbers** | `isInteger` `isFinite` `isPositive` `isNegative` `isNaN` | Numeric validation | | πŸ“ **Strings** | `isAlpha` `isAlphanumeric` `isNumericString` `isLowercase` `isUppercase` `isBlank` | String content checks | | 🌐 **Format** | `isEmail` `isUrl` `isJSON` `isUUID` `isIPv4` `isHexColor` | Format validation with regex | | βš™οΈ **Behavior** | `isIterable` `isTruthy` `isFalsy` `isCallable` `isAsyncFunction` `isPromiseLike` | Runtime behavior checks | | 🏠 **DOM** | `isElement` `isNodeList` `isHTMLCollection` | Browser DOM nodes | | 🧩 **Composition** | `isNil` `isEmpty` | Combine multiple checks | | πŸ”’ **Object State** | `isFrozen` `isSealed` | Object mutability checks | --- ## πŸ” API Reference ### 🧱 Primitives | Function | Description | Example | |----------|-------------|---------| | `isArray(value)` | Is it an array? | `ppIs.isArray([1,2]) β†’ true` | | `isString(value)` | Is it a string? | `ppIs.isString('hi') β†’ true` | | `isNumber(value)` | Is it a number (not NaN)? | `ppIs.isNumber(42) β†’ true` | | `isBoolean(value)` | Is it true, false, or a Boolean? | `ppIs.isBoolean(true) β†’ true` | | `isFunction(value)` | Is it a function? | `ppIs.isFunction(()=>{}) β†’ true` | | `isObject(value)` | Is it a plain object? | `ppIs.isObject({}) β†’ true` | | `isDate(value)` | Is it a Date instance? | `ppIs.isDate(new Date()) β†’ true` | | `isNull(value)` | Is it null? | `ppIs.isNull(null) β†’ true` | | `isUndefined(value)` | Is it undefined? | `ppIs.isUndefined(undefined) β†’ true` | | `isRegExp(value)` | Is it a RegExp? | `ppIs.isRegExp(/abc/) β†’ true` | | `isPromise(value)` | Is it a Promise? | `ppIs.isPromise(Promise.resolve()) β†’ true` | | `isSymbol(value)` | Is it a Symbol? | `ppIs.isSymbol(Symbol('x')) β†’ true` | | `isBigInt(value)` | Is it a BigInt? | `ppIs.isBigInt(42n) β†’ true` | --- ### πŸ”’ Numbers | Function | Description | Example | |----------|-------------|---------| | `isInteger(value)` | Is it an integer? | `ppIs.isInteger(42) β†’ true` | | `isFinite(value)` | Is it finite (not Infinity)? | `ppIs.isFinite(42) β†’ true` | | `isPositive(value)` | Is it greater than zero? | `ppIs.isPositive(5) β†’ true` | | `isNegative(value)` | Is it less than zero? | `ppIs.isNegative(-5) β†’ true` | | `isNaN(value)` | Is it NOT a valid number? | `ppIs.isNaN('abc') β†’ true` | --- ### πŸ“ Strings | Function | Description | Example | |----------|-------------|---------| | `isAlpha(value)` | Only letters (a-z, A-Z)? | `ppIs.isAlpha('Hello') β†’ true` | | `isAlphanumeric(value)` | Letters and numbers only? | `ppIs.isAlphanumeric('abc123') β†’ true` | | `isNumericString(value)` | Digits only (0-9)? | `ppIs.isNumericString('12345') β†’ true` | | `isLowercase(value)` | All lowercase? | `ppIs.isLowercase('hello') β†’ true` | | `isUppercase(value)` | All uppercase? | `ppIs.isUppercase('HELLO') β†’ true` | | `isBlank(value)` | Empty or whitespace only? | `ppIs.isBlank(' ') β†’ true` | | `isEmpty(value)` | Empty string, array, or object? | `ppIs.isEmpty('') β†’ true` | --- ### 🌐 Format Validation | Function | Description | Example | |----------|-------------|---------| | `isEmail(value)` | Valid email address? | `ppIs.isEmail('a@b.com') β†’ true` | | `isUrl(value)` | Valid URL? | `ppIs.isUrl('https://google.com') β†’ true` | | `isJSON(value)` | Valid JSON string? | `ppIs.isJSON('{"a":1}') β†’ true` | | `isUUID(value)` | Valid UUID (v1-v5)? | `ppIs.isUUID('550e8400-e29b-41d4-a716-446655440000') β†’ true` | | `isIPv4(value)` | Valid IPv4 address? | `ppIs.isIPv4('192.168.1.1') β†’ true` | | `isHexColor(value)` | Valid hex color? | `ppIs.isHexColor('#FF5733') β†’ true` | --- ### βš™οΈ Behavior | Function | Description | Example | |----------|-------------|---------| | `isIterable(value)` | Has Symbol.iterator? | `ppIs.isIterable([1,2]) β†’ true` | | `isTruthy(value)` | Is truthy? | `ppIs.isTruthy(1) β†’ true` | | `isFalsy(value)` | Is falsy? | `ppIs.isFalsy(0) β†’ true` | | `isCallable(value)` | Can be invoked as function? | `ppIs.isCallable(()=>{}) β†’ true` | | `isAsyncFunction(value)` | Is an async function? | `ppIs.isAsyncFunction(async()=>{}) β†’ true` | | `isPromiseLike(value)` | Is Promise or thenable? | `ppIs.isPromiseLike({then:()=>{}}) β†’ true` | --- ### 🏠 DOM | Function | Description | Example | |----------|-------------|---------| | `isElement(value)` | Is a DOM element (nodeType === 1)? | `ppIs.isElement(document.body) β†’ true` | | `isNodeList(value)` | Is a NodeList? | `ppIs.isNodeList(document.querySelectorAll('div')) β†’ true` | | `isHTMLCollection(value)` | Is an HTMLCollection? | `ppIs.isHTMLCollection(document.getElementsByClassName('x')) β†’ true` | --- ### 🧩 Composition | Function | Description | Example | |----------|-------------|---------| | `isNil(value)` | Is null or undefined? | `ppIs.isNil(null) β†’ true` | --- ### πŸ”’ Object State | Function | Description | Example | |----------|-------------|---------| | `isFrozen(value)` | Is it frozen (objects, arrays, functions; primitives are always frozen)? | `ppIs.isFrozen(Object.freeze([1,2])) β†’ true` | | `isSealed(value)` | Is it sealed (objects, arrays, functions; primitives are always sealed)? | `ppIs.isSealed(Object.seal([1,2])) β†’ true` | --- ## πŸͺ Callback System Every function supports **optional `done` and `reject` callbacks** for extra validation. This is what makes pp-is unique. ```js ppIs.isString(value, done?, reject?) ``` - **`done`** β€” runs when the check passes. Return `true`/`false` to override. - **`reject`** β€” runs when the check fails. Return `true`/`false` to override. ### Example: Basic ```js ppIs.isString('hello') // β†’ true ``` ### Example: Extra validation ```js const result = ppIs.isString( 'hello', (val) => val.length > 3, // done: also check length (val) => false // reject: always false on fail ) // β†’ true (it's a string AND length > 3) ``` ### Example: Real-world form validation ```js function validateEmail(input) { return ppIs.isEmail(input, (val) => val.includes('@company.com'), // must be company email () => { showError('Invalid email'); return false } ) } validateEmail('john@company.com') // βœ… true validateEmail('john@gmail.com') // ❌ false (not company domain) ``` --- ## πŸ› οΈ TypeScript pp-is is written in vanilla JavaScript but works great with TypeScript: ```ts import ppIs from 'pp-is' function processUser(input: unknown) { if (ppIs.isString(input)) { // input is narrowed to string here βœ… console.log(input.toUpperCase()) } if (ppIs.isEmail(input)) { // input is validated as email format βœ… sendWelcome(input) } } ``` --- ## 🧬 How It Works Under the hood, pp-is uses `Object.prototype.toString.call()` for accurate type detection, wrapped in a callback system that gives you full control: ``` ppIs.isString(value, done, reject) β”‚ β”‚ β”‚ β–Ό β–Ό β–Ό getTypeCompare callback callback (type check) (on pass) (on fail) β”‚ β”‚ β”‚ β–Ό β–Ό β–Ό true/false ← baseEvaluate β†’ true/false ``` --- ## 🀝 Contributing Contributions are welcome! Here's how to get started: 1. **Fork** the repository 2. **Clone** your fork ```bash git clone https://github.com/YOUR_USERNAME/pp-is.git cd pp-is ``` 3. **Install** dependencies ([Bun](https://bun.sh) is this project's runtime/build tool) ```bash bun install ``` 4. **Create** your function in `src/main/yourFunction.js` 5. **Add** it to `src/pp-is.js` (import + add to `is` object) 6. **Build** to verify β€” `bun run build` uses Bun's own bundler (`scripts/build.mjs`) to produce `dist/pp-is.mjs` (ESM), `dist/pp-is.cjs` (CommonJS) and `dist/pp-is.min.js` (browser global) ```bash bun run build ``` 7. **Test** your function ```bash bun test ``` Add a matching test case in `test/is.test.js` (or a new `test/*.test.js` file). 8. **Submit** a pull request ### πŸ“‹ Guidelines - One function per file in `src/main/` - Use `export { funcName as default }` - Add JSDoc comments (`@function`, `@description`, `@param`, `@return`) - Wrap with `base()` for callback support - Keep it **zero dependencies** - Follow existing code style (arrow functions, no semicolons) - Add tests for your function in `test/` --- ## πŸ“„ License [MIT](./LICENSE.txt) β€” Carlos Illesca --- [πŸ“„ EspaΓ±ol](./README_es.md)