tessl/npm-ow

Function argument validation for humans with expressive, chainable API

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Primitive Type Validation

Name: tessl/npm-ow
Author: tessl

Comprehensive validation for JavaScript primitive types including strings, numbers, booleans, symbols, and special values with extensive chainable validation methods.

Capabilities

String Validation

Validation for string values with length, content, format, and pattern matching methods.

/** String validation predicate */
interface StringPredicate extends BasePredicate<string> {
  // Length validation
  length(length: number): StringPredicate;
  minLength(length: number): StringPredicate;
  maxLength(length: number): StringPredicate;
  
  // Content validation
  matches(regex: RegExp): StringPredicate;
  startsWith(searchString: string): StringPredicate;
  endsWith(searchString: string): StringPredicate;
  includes(searchString: string): StringPredicate;
  oneOf(list: readonly string[]): StringPredicate;
  equals(expected: string): StringPredicate;
  
  // State validation
  readonly empty: StringPredicate;
  readonly nonEmpty: StringPredicate;
  readonly nonBlank: StringPredicate;
  
  // Format validation
  readonly alphanumeric: StringPredicate;
  readonly alphabetical: StringPredicate;
  readonly numeric: StringPredicate;
  readonly lowercase: StringPredicate;
  readonly uppercase: StringPredicate;
  readonly date: StringPredicate;
  readonly url: StringPredicate;
}

Usage Examples:

import ow from 'ow';

// Length validation
ow('hello', ow.string.minLength(3).maxLength(10));

// Content validation
ow('hello@example.com', ow.string.matches(/^.+@.+\..+$/));
ow('Hello World', ow.string.startsWith('Hello'));
ow('filename.txt', ow.string.endsWith('.txt'));
ow('JavaScript', ow.string.includes('Script'));
ow('red', ow.string.oneOf(['red', 'green', 'blue']));

// State validation
ow('', ow.string.empty);
ow('not empty', ow.string.nonEmpty);
ow('  not blank  ', ow.string.nonBlank);

// Format validation
ow('abc123', ow.string.alphanumeric);
ow('abc', ow.string.alphabetical);
ow('123', ow.string.numeric);
ow('hello', ow.string.lowercase);
ow('HELLO', ow.string.uppercase);
ow('2023-12-01', ow.string.date);
ow('https://example.com', ow.string.url);

Number Validation

Validation for numeric values with range checking, type validation, and typed integer constraints.

/** Number validation predicate */
interface NumberPredicate extends BasePredicate<number> {
  // Range validation
  inRange(start: number, end: number): NumberPredicate;
  greaterThan(number: number): NumberPredicate;
  greaterThanOrEqual(number: number): NumberPredicate;
  lessThan(number: number): NumberPredicate;
  lessThanOrEqual(number: number): NumberPredicate;
  equal(expected: number): NumberPredicate;
  oneOf(list: readonly number[]): NumberPredicate;
  
  // Type validation
  readonly integer: NumberPredicate;
  readonly finite: NumberPredicate;
  readonly infinite: NumberPredicate;
  readonly positive: NumberPredicate;
  readonly negative: NumberPredicate;
  readonly integerOrInfinite: NumberPredicate;
  
  // Typed integer validation
  readonly uint8: NumberPredicate;   // 0-255
  readonly uint16: NumberPredicate;  // 0-65535
  readonly uint32: NumberPredicate;  // 0-4294967295
  readonly int8: NumberPredicate;    // -128 to 127
  readonly int16: NumberPredicate;   // -32768 to 32767
  readonly int32: NumberPredicate;   // -2147483648 to 2147483647
}

Usage Examples:

import ow from 'ow';

// Range validation
ow(5, ow.number.inRange(1, 10));
ow(15, ow.number.greaterThan(10));
ow(15, ow.number.greaterThanOrEqual(15));
ow(5, ow.number.lessThan(10));
ow(10, ow.number.lessThanOrEqual(10));
ow(42, ow.number.equal(42));
ow(3, ow.number.oneOf([1, 2, 3, 4, 5]));

// Type validation
ow(42, ow.number.integer);
ow(3.14, ow.number.finite);
ow(Infinity, ow.number.infinite);
ow(5, ow.number.positive);
ow(-5, ow.number.negative);
ow(42, ow.number.integerOrInfinite);

// Typed integer validation
ow(255, ow.number.uint8);
ow(65535, ow.number.uint16);
ow(4294967295, ow.number.uint32);
ow(-128, ow.number.int8);
ow(-32768, ow.number.int16);
ow(-2147483648, ow.number.int32);

Boolean Validation

Validation for boolean values with specific true/false checking.

/** Boolean validation predicate */
interface BooleanPredicate extends BasePredicate<boolean> {
  readonly true: BooleanPredicate;
  readonly false: BooleanPredicate;
}

Usage Examples:

import ow from 'ow';

// Basic boolean validation
ow(true, ow.boolean);
ow(false, ow.boolean);

// Specific value validation
ow(true, ow.boolean.true);
ow(false, ow.boolean.false);

BigInt Validation

Validation for BigInt values.

/** BigInt validation predicate */
interface BigIntPredicate extends BasePredicate<bigint> {
  // Inherits only base predicate methods
}

Usage Examples:

import ow from 'ow';

// Basic bigint validation
ow(123n, ow.bigint);
ow(BigInt('123456789012345678901234567890'), ow.bigint);

// With custom validation
ow(42n, ow.bigint.is(value => value > 0n));

Symbol Validation

Validation for Symbol values.

/** Symbol validation predicate */
const symbol: Predicate<symbol>;

Usage Examples:

import ow from 'ow';

// Basic symbol validation
ow(Symbol('test'), ow.symbol);
ow(Symbol.for('global'), ow.symbol);

Special Value Validation

Validation for special JavaScript values including undefined, null, and NaN.

/** Special value predicates */
const undefined: Predicate<undefined>;
const null: Predicate<null>;
const nullOrUndefined: Predicate<null | undefined>;
const nan: Predicate<number>;

Usage Examples:

import ow from 'ow';

// Special value validation
ow(undefined, ow.undefined);
ow(null, ow.null);
ow(null, ow.nullOrUndefined);
ow(undefined, ow.nullOrUndefined);
ow(NaN, ow.nan);

Base Predicate Methods

All primitive predicates inherit these common validation methods:

/** Base methods available on all predicates */
interface BasePredicate<T> {
  /** Inverts the following validator */
  readonly not: BasePredicate<T>;
  
  /** Custom validation function returning boolean or error string */
  is(validator: (value: T) => boolean | string): BasePredicate<T>;
  
  /** Custom validation with validator/message object */
  validate(customValidator: CustomValidator<T>): BasePredicate<T>;
  
  /** Override default error message */
  message(newMessage: string | MessageBuilder<T>): BasePredicate<T>;
}

interface CustomValidator<T> {
  validator: boolean;
  message: string | ((label?: string) => string);
}

type MessageBuilder<T> = (value: T, label?: string) => string;

Usage Examples:

import ow from 'ow';

// Negation
ow(5, ow.number.not.negative);
ow('hello', ow.string.not.empty);

// Custom validation
ow(8, ow.number.is(x => x % 2 === 0 || 'Expected even number'));
ow('password123', ow.string.is(s => s.length >= 8 && /\d/.test(s)));

// Custom validation object
ow(10, ow.number.validate(value => ({
  validator: value > 5,
  message: `Expected number greater than 5, got ${value}`
})));

// Custom error messages
ow('hi', 'greeting', ow.string.minLength(5).message('Greeting too short'));
ow(3, ow.number.positive.message((value, label) => 
  `Expected positive ${label}, got ${value}`
));

Install with Tessl CLI