KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #codex #ai-agents #claude-code #dsh #dsh-plugin #cli #macos #ai-agent #deepseek-harness #open-source

semantic-validator

★ 35 Open GitHub ↗

A functional semantic validator tool for validation of several types and rich content.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Semantic Validator

A functional semantic validator tool for validation of several types and rich content, inspired by prop-types from React.

[![npm version](https://badge.fury.io/js/semantic-validator.svg)](https://badge.fury.io/js/semantic-validator)
[![Build Status](https://travis-ci.com/chenzitw/semantic-validator.svg?branch=master)](https://travis-ci.com/chenzitw/semantic-validator)
[![Coverage Status](https://coveralls.io/repos/github/chenzitw/semantic-validator/badge.svg?branch=master)](https://coveralls.io/github/chenzitw/semantic-validator?branch=master)

## Get started

### Using NPM or Yarn

First, install it via npm.  
```sh
npm i semantic-validator
```
Then, import it from dependencies and enjoy it.  
```javascript
import { op, is } from 'semantic-validator';

const validate = op.shape({
  id: is.integer(),
  tags: op.every(is.string()),
});
```

### Using script tag

First, add a script tag with to the HTML page.
```html
<script src="https://unpkg.com/semantic-validator/bundle.js" crossorigin></script>
```
Then, just enjoy it.  
```javascript
var op = semanticValidator.op;
var is = semanticValidator.is;

var validate = op.shape({
  id: is.integer(),
  tags: op.every(is.string())
});
```

## Usage

The base unit of the semantic validator is a function which accepts the value as an argument for validation. We define it in TypeScript like below.  
```typescript
type Validator<T = any> = (val: T) => boolean;
```

This validator tool has several methods in two types: validator operator (op) and validator creator (is).

For example, we can call a validator creator such as `is.integer()` to create a validator which expects the number should be an integer. We can also call `is.greaterThan(100)` to create a validator which expects the number is greater than 100.  
If we want to match both conditions, we can use a validator operator like `op.and(validator1, validator2)` to combine two validators.

```javascript
import { op, is } from 'semantic-validator';

const isInt = is.integer();
isInt(12); // => true;
isInt(12.34); // => false;

const isGt100 = is.greaterThan(100);
isGt100(150); // => true;
isGt100(50); // => false;

const isIntGt100 = op.and(
  is.integer(),
  is.greaterThan(100),
);
isIntGt100(123); // => true;
isIntGt100(123.456); // => false;
isIntGt100(12); // => false;
```

You can also integrate other validation tools together. Just follow the validator pattern.

For example, there is a method `isUUID(str, version)` for validating a string. We can make a validator like `val => isUUID(val, 5)` and compose with other validator operators.

```javascript
import { op, is } from 'semantic-validator';

### Cheatsheet

| Method                                                           | Description                                                      |
| ---------------------------------------------------------------- | ---------------------------------------------------------------- |
| **Basic validator operators**                                    |                                                                  |
| > **`op.so(validator)`**                                         | Pass the validator.                                              |
| > **`op.not(validator)`**                                        | Not pass the validator.                                          |
| > **`op.and(...validators)`**                                    | Pass all validators.                                             |
| > **`op.or(...validators)`**                                     | Pass any validators.                                             |
| > **`op.every(validator)`**                                      | Pass the validator on all elements in an array.                  |
| > **`op.some(validator)`**                                       | Pass the validator on any elements in an array.                  |
| > **`op.shape({ ...validatorOfKeys })`**                         | Pass all validators for each properties of an object.            |
| > **`op.exact({ ...validatorOfKeys })`**                         | Pass all validators for each properties of an exact object.      |
| **Converter validator operators**                                |                                                                  |
| > **`op.convert(converter, validator)`**                         | Pass the validator after converted.                              |
| > **`op.toFloat(validator)`**                                    | Pass the validator after converted to a float.                   |
| > **`op.toInteger(validator)`**                                  | Pass the validator after converted to an integer.                |
| > **`op.toLength(validator)`**                                   | Pass the validator after converted to the length.                |
| > **`op.toSplit(separator, validator)`**                         | Pass the validator after splitted the string as an array.        |
| > **`op.toKeys(validator)`**                                     | Pass the validator after converted to keys of an object.         |
| > **`op.toValues(validator)`**                                   | Pass the validator after converted to values of an object.       |
| > **`op.toDate(validator)`**                                     | Pass the validator after converted to a date object.             |
| **Basic validator creators**                                     |                                                                  |
| > **`is.same(value)`**                                           | Is the same as the base value?                                   |
| > **`is.oneOf(...values)`**                                      | Is the same as any base values?                                  |
| > **`is.defined()`**                                             | Is defined (not undefined)?                                      |
| > **`is.notDefined()`**                                          | Is undefined?                                                    |
| > **`is.nul()`**                                                 | Is null?                                                         |
| > **`is.nil()`**                                                 | Is undefined or null?                                            |
| > **`is.bool()`**                                                | Is a boolean?                                                    |
| > **`is.number()`**                                              | Is a number?                                                     |
| > **`is.string()`**                                              | Is a string?                                                     |
| > **`is.object()`**                                              | Is a non null object?                                            |
| > **`is.func()`**                                                | Is a function?                                                   |
| > **`is.symbol()`**                                              | Is a symbol?                                                     |
| > **`is.instanceOf(constructor)`**                               | Is an instance of the constructor (class)?                       |
| > **`is.float()`**                                               | Is a valid (not `NaN` or `Infinity`) float?                      |
| > **`is.integer()`**                                             | Is a valid (not `NaN` or `Infinity`) integer?                    |
| > **`is.array()`**                                               | Is an array?                                                     |
| > **`is.date()`**                                                | Is a valid (not `Invalid Date`) date object?                     |
| **Math validator creators**                                      |                                                                  |
| > **`is.equalTo(num)`**                                          | Is the number equal to the base number?                          |
| > **`is.greaterThan(num)`**                                      | Is the number greater than the base number?                      |
| > **`is.atLeast(num)`**                                          | Is the number at least the base number?                          |
| > **`is.lessThan(num)`**                                         | Is the number less than the base number?                         |
| > **`is.atMost(num)`**                                           | Is the number at most the base number?                           |
| > **`is.between(min, max)`**                                     | Is the number between the base numbers?                          |
| > **`is.fromTo(min, max)`**                                      | Is the number from and to the base numbers?                      |
| **Text validator creators**                                      |                                                                  |
| > **`is.match(regexp)`**                                         | Is the string match the regular expression?                      |
| > **`is.startsWith(wording)`**                                   | Is the string starts with the wording?                           |
| > **`is.endsWith(wording)`**                                     | Is the string ends with the wording?                             |
| > **`is.contains(wording)`**                                     | Is the string contains the wording?                              |
| **List validator creators**                                      |                                                                  |
| > **`is.includes(...includings)`**                               | Is the array includes all includings?                            |
| > **`is.excludes(...excludings)`**                               | Is the array excludes all excludings?                            |
| > **`is.restrictedBy(...allowedItems)`**                         | Is the array only includes allowed items?                        |
| > **`is.distinct()`**                                            | Is items of the array are all different?                         |
| **Date validator creators**                                      |                                                                  |
| > **`is.moment(date)`**                                          | Is the date object at the moment of the base date object?        |
| > **`is.laterThan(date)`**                                       | Is the date object later than the base date object?              |
| > **`is.atEarliest(date)`**                                      | Is the date object at earliest the base date object?             |
| > **`is.earlierThan(date)`**                                     | Is the date object earlier than the base date object?            |
| > **`is.atLatest(date)`**                                        | Is the date object at latest the base date object?               |

### Validator operator reference

#### Basic

**op: so**  
Will be valid when the validator returns true. It is usually not necessary.  
```javascript
op.so(validator)
```
Example:   
```javascript
const validate = op.so(is.same('hello'));
validate('hello'); // => true
validate('bye'); // => false
```

**op: not**  
Will be valid when the validator returns false.  
```javascript
op.not(validator)
```
Example:   
```javascript
const validate = op.not(is.same('hello'));
validate('bye'); // => true
validate('hello'); // => false
```

**op: and**  
Will be valid when all validators return true.  
```javascript
op.and(validator1, validator2, ...validators)
```
Example:   
```javascript
const validate = op.and(is.integer(), is.greaterThan(100));
validate(120); // => true
validate(80); // => false
validate(123.456); // => false
```

**op: or**  
Will be valid when any validator returns true.  
```javascript
op.or(validator1, validator2, ...validators)
```
Example:   
```javascript
const validate = op.or(is.nul(), is.integer());
validate(null); // => true
validate(123); // => true
validate('abc'); // => false
```

**op: every**  
Will be valid when validator returns true on all elements in the array.  
```javascript
op.every(validator)
```
Example:   
```javascript
const validate = op.every(is.integer());
validate([1, 2, 3]); // => true
validate([1, 2.22, 3]); // => false
```

**op: some**  
Will be valid when validator returns true on any element in the array.  
```javascript
op.some(validator)
```
Example:   
```javascript
const validate = op.some(is.integer());
validate([1, 2, 3]); // => true
validate([1.11, 2, 3.33]); // => true
validate([1.11, 2.22, 3.33]); // => false
```

**op: shape**  
Will be valid when value is an object and all validator returns true on each key.  
```javascript
op.shape({
  [key1]: validator1,
  [key2]: validator2,
  ...keysWithValidator,
})
```
Example:   
```javascript
const validate = op.shape({
  id: is.integer(),
  name: is.string(),
});
validate({ id: 123, name: 'Mr. Sandman' }); // => true
validate({ id: 123, name: 'Mr. Sandman', active: true }); // => true
validate({ id: 123 }); // => false
validate({ id: 123, name: 456 }); // => false
```

**op: exact**  
Will be valid when value is an object with specific keys and all validator returns true on each key.  
```javascript
op.exact({
  [key1]: validator1,
  [key2]: validator2,
  ...keysWithValidator,
})
```
Example:   
```javascript
const validate = op.exact({
  id: is.integer(),
  name: is.string(),
});
validate({ id: 123, name: 'Mr. Sandman' }); // => true
validate({ id: 123, name: 'Mr. Sandman', active: true }); // => false
validate({ id: 123 }); // => false
validate({ id: 123, name: 456 }); // => false
```

#### Converter

**op: convert**  
Will be valid when successfully converts the value and the validation is success.  
```javascript
op.convert(converter, validator)
```
Example:   
```javascript
const validate = op.convert(
  numeric => parseFloat(numeric),
  is.greaterThan(100)
);
validate('150'); // => true
validate('50'); // => false
```

**op: to float**  
Will be valid when successfully converts to a float and the validation is success.  
```javascript
op.toFloat(validator)
```
Example:   
```javascript
const validate = op.toFloat(is.greaterThan(1.2));
validate('1.5'); // => true
validate('two'); // => false
validate('0.8'); // => false
```

**op: to integer**  
Will be valid when successfully converts to an integer and the validation is success.  
```javascript
op.toInteger(validator)
```
Example:   
```javascript
const validate = op.toInteger(is.greaterThan(100));
validate('150'); // => true
validate('two'); // => false
validate('123.456'); // => false
validate('50'); // => false
```

**op: to length**  
Will be valid when successfully get the length of an array or string and the validation is success.  
```javascript
op.toLength(validator)
```
Example:   
```javascript
const validate = op.toLength(is.atLeast(3));
validate(['a', 'b', 'c']); // => true
validate('abc'); // => true
validate(['a', 'b']); // => false
validate('ab'); // => false
validate(3); // => false
```

**op: to split**  
Will be valid when successfully split to the array and the validation is success.  
```javascript
op.toSplit(separator, validator)
```
Example:   
```javascript
const validate = op.toSplit(',', op.every(is.startsWith('c')));
validate('candy,cookie,coffee'); // => true
validate('candy,cookie,tea'); // => false
validate(123); // => false
```

**op: to keys**  
Will be valid when successfully get keys of an object and the validation is success.  
```javascript
op.toKeys(validator)
```
Example:   
```javascript
const validate = op.toKeys(op.every(is.oneOf('id', 'name')));
validate({ id: 123, name: 'Mario' }); // => true
validate({ id: 123, name: 'Mario', age: 20 }); // => false
```

**op: to values**  
Will be valid when successfully get values of an object and the validation is success.  
```javascript
op.toValues(validator)
```
Example:   
```javascript
const validate = op.toValues(op.every(is.integer()));
validate({ people: 64, seats: 80 }); // => true
validate({ people: 640, seats: 'many' }); // => false
```

### Validator creator reference

#### Basic

**is: same**  
Will be valid when base value and compare value are the same by using the SameValueZero algorithm.  
```javascript
is.same(baseValue)
```
Example:   
```javascript
const validate = is.same('hello');
validate('hello'); // => true
```

**is: one of**  
Will be valid when one of base values and compare value are the same by using the SameValueZero algorithm.  
```javascript
is.oneOf(...baseValues)
```
Example:   
```javascript
const validate = is.oneOf(100, '100', 'one hundred');
validate('100'); // => true
```

**is: defined**  
Will be valid when the value is defined (not undefined).  
```javascript
is.defined()
```
Example:   
```javascript
const validate = is.defined();
validate(123); // => true
validate(undefined); // => false
```

**is: not defined**  
Will be valid when the value is not defined (undefined).  
```javascript
is.notDefined()
```
Example:   
```javascript
const validate = is.notDefined();
validate(undefined); // => true
validate(123); // => false
```

**is: nul**  
Will be valid when the value is null.  
```javascript
is.nul()
```
Example:   
```javascript
const validate = is.nul();
validate(null); // => true
validate(123); // => false
```

**is: nil**  
Will be valid when the value is undefined or null.  
```javascript
is.nil()
```
Example:   
```javascript
const validate = is.nil();
validate(undefined); // => true
validate(null); // => true
validate(123); // => false
```

**is: bool**  
Will be valid when the value is a boolean.  
```javascript
is.bool()
```
Example:   
```javascript
const validate = is.bool();
validate(false); // => true
validate(123); // => false
```

**is: number**  
Will be valid when the value is a number.  
```javascript
is.number()
```
Example:   
```javascript
const validate = is.number();
validate(123); // => true
validate('abc'); // => false
```

**is: string**  
Will be valid when the value is a string.  
```javascript
is.string()
```
Example:   
```javascript
const validate = is.string();
validate('abc'); // => true
validate(123); // => false
```

**is: object**  
Will be valid when the value is a non null object.  
```javascript
is.object()
```
Example:   
```javascript
const validate = is.object();
validate({ key: 'value' }); // => true
validate({}); // => true
validate(null); // => false
validate(123); // => false
```

**is: func**  
Will be valid when the value is a function.  
```javascript
is.func()
```
Example:   
```javascript
const validate = is.func();
validate(() => {}); // => true
validate(123); // => false
```

**is: symbol**  
Will be valid when the value is a symbol.  
```javascript
is.symbol()
```
Example:   
```javascript
const validate = is.symbol();
validate(Symbol('abc')); // => true
validate('abc'); // => false
```

**is: instance of**  
Will be valid when the value is the instance of a constructor.  
```javascript
is.instanceOf(constructor)
```
Example:   
```javascript
const validate = is.instanceOf(Date);
validate(new Date()); // => true
validate(123); // => false
```

**is: float**  
Will be valid when the value is a float and not NaN or infinity.  
```javascript
is.float()
```
Example:   
```javascript
const validate = is.float();
validate(123.456); // => true
validate(123); // => true
validate('123'); // => false
```

**is: integer**  
Will be valid when the value is a integer and not NaN or infinity.  
```javascript
is.integer()
```
Example:   
```javascript
const validate = is.integer();
validate(123); // => true
validate(123.456); // => false
```

**is: array**  
Will be valid when the value is an array object.  
```javascript
is.array()
```
Example:   
```javascript
const validate = is.array();
validate([1, 2, 3]); // => true
```

**is: date**  
Will be valid when the value is a valid date object.  
```javascript
is.date()
```
Example:   
```javascript
const validate = is.date();
validate(new Date()); // => true
validate(new Date('invalid date')); // => false
validate('invalid date'); // => false
```

#### Math

**is: equal to**  
Will be valid when the value is equal to the number.  
```javascript
is.equalTo(num)
```
Example:   
```javascript
const validate = is.equalTo(100);
validate(100); // true
validate(200); // false
```

**is: greater than**  
Will be valid when the value is greater than the number.  
```javascript
is.greaterThan(num)
```
Example:   
```javascript
const validate = is.greaterThan(100);
validate(101); // => true
validate(100); // => false
```

**is: at least**  
Will be valid when the value is at least the number.  
```javascript
is.atLeast(num)
```
Example:   
```javascript
const validate = is.atLeast(100);
validate(100); // => true
validate(99); // => false
```

**is: less than**  
Will be valid when the value is less than the number.  
```javascript
is.lessThan(num)
```
Example:   
```javascript
const validate = is.lessThan(200);
validate(199); // => true
validate(200); // => false
```

**is: at most**  
Will be valid when the value is at most the number.  
```javascript
is.atMost(num)
```
Example:   
```javascript
const validate = is.atMost(200);
validate(200); // => true
validate(201); // => false
```

**is: between**  
Will be valid when the value is between the numbers.  
```javascript
is.between(min, max)
```
Example:   
```javascript
const validate = is.between(0, 10);
validate(5); // => true
validate(0); // => false
validate(10); // => false
```

**is: from to**  
Will be valid when the value is from and to the numbers.  
```javascript
is.fromTo(min, max)
```
Example:   
```javascript
const validate = is.fromTo(1, 9);
validate(1); // => true
validate(9); // => true
validate(0); // => false
validate(10); // => false
```

#### Text

**is: match**  
Will be valid when the value matches the regular expression.  
```javascript
is.match(regexp)
```
Example:   
```javascript
const validate = is.match(/^b[aeiou]t$/);
validate('bat'); // => true
validate('brt'); // => false
```

**is: starts with**  
Will be valid when the value starts with the wording.  
```javascript
is.startsWith(wording)
```
Example:   
```javascript
const validate = is.startsWith('net');
validate('network'); // => true
validate('artwork'); // => false
```

**is: ends with**  
Will be valid when the value ends with the wording.  
```javascript
is.endsWith(wording)
```
Example:   
```javascript
const validate = is.endsWith('fox');
validate('firefox'); // => true
validate('firewall'); // => false
```

**is: contains**  
Will be valid when the value contains the wording.  
```javascript
is.contains(wording)
```
Example:   
```javascript
const validate = is.contains('lie');
validate('believe'); // => true
validate('behave'); // => false
```

#### List

**is: includes**  
Will be valid when the array value includes all includings.  
```javascript
is.includes(including1, including2, ...includings)
```
Example:   
```javascript
const validate = is.includes(10, 20, 30);
validate([0, 10, 20, 30, 40]); // => true
validate([0, 20, 40]); // => false
```

**is: excludes**  
Will be valid when the array value excludes all excludings.  
```javascript
is.excludes(excluding1, excluding2, ...excludings)
```
Example:   
```javascript
const validate = is.excludes(5, 15, 25);
validate([0, 10, 20, 30]); // => true
validate([5, 10]); // => false
```

**is: restricted by**  
Will be valid when the array value is restricted by allowed items.  
```javascript
is.restrictedBy(allowedItem1, allowedItem2, ...allowedItems)
```
Example:   
```javascript
const validate = is.restrictedBy(5, 10, 15, 20);
validate([10, 20]); // => true
validate([5, 10, 15, 20, 25, 30]); // => false
```

**is: distinct**  
Will be valid when items of array value are all different.  
```javascript
is.distinct()
```
Example:   
```javascript
const validate = is.distinct();
validate([1, 2, 3]); // => true
validate([1, 2, 3, 3]]); // => false
```

semantic-validator

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README