JSPM

  • Created
  • Published
  • Downloads 271
  • Score
    100M100P100Q84181F
  • License MIT

A simple and lightweight TypeScript type guard library providing runtime validation utilities.

Package Exports

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (guardz) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

    guardz

    NPM Version License: MIT Node.js CI

    A simple and lightweight TypeScript type guard library.

    The core function isType allows you to easily create type guards for complex object structures by composing simpler guards.

    Installation

    npm install guardz
    # or
    yarn add guardz

    Usage

    Simple usage with primitive type-guard function

    Problem:

    • It could be simple
    import { isString } from 'guardz';
    
    const data: unknown = getDataFromSomewhere();
    
    if (isString(data)) { // data type is narrowed to string
      console.log(data.toUpperCase());
    }
    • Or complicated
    import { isType, isString } from 'guardz';
    const data: unknown = getDataFromSomewhere();
    
    // Build typeguard function
    const isUser = isType({
      name: isString,
      age: isString,
    })
    
    if (isUser(data)) { // data type is narrowed to { name: string, age: string }
      console.log(`Name: ${data.name}`);
      console.log(`Age: ${data.age}`);
    }
    • For Array
    import { isArrayWithEachItem, isNumber } from 'guardz';
    
    // Example using isArrayWithEachItem
    const data: unknown = getDataFromSomewhere()
    if (isArrayWithEachItem(isNumber)(data)) { // data type is narrowed to number[]
      console.log(data.map((item) => item.toFixed(2)))
    }
    • For Record
    import { isObjectWithEachItem, isNumber } from 'guardz';
    
    // Example using isObjectWithEachItem
    const data: unknown = getDataFromSomewhere()
    if (isObjectWithEachItem(isNumber)(data)) { // data type is narrowed to Record<string, number | undefined>
      console.log(data.something?.toFixed(2))
    }
    • Union Type
    import { isNumber, isString, isOneOfType } from 'guardz';
    
    // Example using isOneOfType
    const data: unknown = getDataFromSomewhere()
    if (isOneOfType<number | string>(isNumber, isString)(data)) { // data type is narrowed to string | number
      return isNumber(a) ? a.toFix(2) : a;
    }
    • Nullable type
    import { isNullOr, isString } from 'guardz';
    
    // Example using isArrayWithEachItem
    const data: unknown = getDataFromSomewhere()
    if (isNullOr(isString)(data)) { // data type is narrowed to string | null
      return a?.toUpperCase();
    }
    • Optional type
    import { isUndefinedOr, isString } from 'guardz';
    
    // Example using isUndefinedOr
    const data: unknown = getDataFromSomewhere()
    if (isUndefinedOr(isString)(data)) { // data type is narrowed to string | undefined
      return a?.toUpperCase();
    }
    • Or even both
    import { isUndefinedOr, isString } from 'guardz';
    
    // Example using isUndefinedOr
    const data: unknown = getDataFromSomewhere()
    if (isUndefinedOr(isNullOr(isString))(data)) { // data type is narrowed to string | undefined | null
      return a?.toUpperCase();
    }

    or complex type

    import { isUndefinedOr, isString, isEnum, isEqualTo, isNumber, isOneOfType, isArrayWithEachItem, isType } from 'guardz';
    
    enum PriceTypeEnum {
      FREE = 'free',
      PAID = 'paid'
    }
    
    // Example using isUndefinedOr
    type Book = {
      title: string;
      price: PriceTypeEnum,
      author: {
        name: string;
        email?: string;
      };
      chapters: Array<{
        content: string;
        startPage: number;
      }>;
      rating: Array<{
        userId: string;
        average: number | 'N/A';
      }>
    }
    
    const data: unknown = getDataFromSomewhere()
    
    const isBook = isType<Book>({
      title: isString,
      price: isEnum(PriceTypeEnum),
      author: isType({
        name: isString,
        email: isUndefinedOr(isString),
      }),
      chapters: isArrayWithEachItem(isType({
        content: isString,
        startPage: isNumber,
      })),
      rating: isArrayWithEachItem(isType({
        userId: isString,
        average: isOneOfType<number | 'N/A'>(isNumber, isEqualTo('N/A'))
      })),
    })
    
    if (isBook(data)) { // data type is narrowed to Book
      return data;
    }

    Guard with tolerance

    import { isBook } from 'isBook'; // see previous example
    import { guardWithTolerance } from 'guardz';
    
    
    
    ## API Reference
    
    Below is a list of the core type guards provided by `guardz`.
    
    *   **`isType<T>(propsTypesToCheck: { [P in keyof T]: TypeGuardFn<T[P]> }): TypeGuardFn<T>`**
        **(Core Function)** Creates a type guard function for a specific object shape `T`. It checks if a value is a non-null object and verifies that each property specified in `propsTypesToCheck` conforms to its corresponding type guard function.
    
    *   **`guardWithTolerance<T>(data: unknown, typeGuardFn: TypeGuardFn<T>, config?: Nullable<TypeGuardFnConfig>): T
        Check if data type match typeGuardFn, otherwise assert type of data (even though it is wrong), but log the error via config
    
    *   **`isAny`**
    *   **`isArrayWithEachItem`**
    *   **`isBoolean`**
    *   **`isDate`**
    *   **`isDefined`**
    *   **`isEnum`**
    *   **`isEqualTo`**
    *   **`isNil`**
    *   **`isNonEmptyArrayWithEachItem`**
    *   **`isNonEmptyString`**
    *   **`isNonNegativeNumber`**
    *   **`isNullOr`**
    *   **`isNumber`**
    *   **`isObjectWithEachItem`**
    *   **`isOneOf`**
    *   **`isOneOfTypes`**
    *   **`isString`**
    *   **`isUndefinedOr`**
    *   **`isUnknown`**
    
    
    some utility types
    *   **`NonEmptyArray`**
    *   **`NonEmptyString`**
    *   **`NonNegativeNumber`**
    *   **`Nullable`**
    *   **`PositiveNumber`**
    
    
    
    For more detailed API documentation generated from the source code comments, please see the [TypeDoc generated documentation](docs/index.html) (available after running `npm run docs`).
    
    ## Contributing
    
    Contributions are welcome! Please open an issue or submit a pull request.
    
    ## License
    
    MIT
    
    ---
    
    ## Support
    
    If you find this library helpful, consider buying me a beer! 🍺
    
    [Buy me a coffee](https://paypal.me/thiennp)