Skip to content

Latest commit

 

History

History
631 lines (425 loc) · 24.7 KB

binding.md

File metadata and controls

631 lines (425 loc) · 24.7 KB
Raw

Binding

Provides ready-to-use functionality. They are bound with default failure messages.

They are also exported in the form of closures or, objects.

Common interface

Binding includes the following interfaces.

Validator

API to perform Validation. See Validator for details.

Expectation

Objects with the Expectation interface can bind validation failure messages.

Static message:

import { string } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";

const StringValidator = string.expect("should be string");

Dynamic message:

The context is different for each object.

import { string } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";

const StringValidator = string.expect((context) =>
  `should be string, but ${typeof context.input}`
);

Objects implementing this interface also come with default messages.

List of bindings

Name Closure / Object Validator Expectation
type Closure TypeValidator ✅
string Object TypeValidator ✅
number Object TypeValidator ✅
bigint Object TypeValidator ✅
boolean Object TypeValidator ✅
symbol Object TypeValidator ✅
instance Closure InstanceValidator ✅
props Closure PropertiesValidator
optional Closure OptionalValidator
enumerator Closure EnumValidator ✅
nullish Object NullishValidator ✅
propKey Closure PropertyKeyValidator
propValue Closure PropertyValueValidator
and Closure AndValidator ✅
or Closure OrValidator ✅
eq Closure EqualityValidator ✅
ne Closure InequalityValidator ✅
gt Closure GreaterThanValidator ✅
gte Closure GreaterThanOrEqualValidator ✅
lt Closure LessThanValidator ✅
lte Closure LessThanOrEqualValidator ✅
between Closure RangeValidator ✅
not Closure NotValidator ✅
has Closure InValidator ✅
pattern Closure PatternValidator ✅
item Closure ItemValidator
count Closure CountValidator ✅
maxCount Closure MaxCountValidator ✅
minCount Closure MinCountValidator ✅
single Object SingleValidator ✅
empty Object EmptyValidator ✅
nonEmpty Object NonEmptyValidator ✅
unique Object UniqueValidator ✅
fixedArray Closure FixedArrayValidator
float Object FloatValidator ✅
int Object IntegerValidator ✅
positive Object PositiveNumberValidator ✅
negative Object NegativeNumberValidator ✅
nonPositive Object NonPositiveNumberValidator ✅
nonNegative Object NonNegativeNumberValidator ✅
int8 Object - ✅
int16 Object - ✅
int32 Object - ✅
uint8 Object - ✅
uint16 Object - ✅
uint32 Object - ✅
validDate Object ValidDateValidator ✅

type

Validator factory for JavaScript data type. The difference with typeof operator is that "object" does not match null.

import { type } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
const validator = type("object");

string

abstruct:string

String validator.

number

abstruct:number

Number validator.

bigint

abstruct:bigint

Bigint validator.

boolean

abstruct:boolean

Boolean validator.

symbol

abstruct:symbol

Symbol validator.

instance

abstruct:instance

Validator factory equivalent to the instanceof operator.

import { instance } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
const validator = instance(Array);

props

abstruct:props

Factory for properties validator.

import {
  number,
  props,
  string,
} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
const User = props({ name: string, age: number });

optional

abstruct:optional

Factory for optional properties validator.

import {
  number,
  optional,
  string,
} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
const Profile = optional({ greeting: string, hobby: string });

enumerator

abstruct:enumerator

Factory for enumerator validator.

import { enumerator } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
const validator = enumerator(0, 1, 2, 3);
const validator2 = enumerator("Red", "Yellow", "Green");

nullish

abstruct:nullish

Nullish(null or undefined) validator.

propKey

abstruct:propKey

Factory for property key validator.

import {
  propKey,
  type Validator,
} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
declare const validator: Validator<string>;
const keyValidator = propKey(validator);

propValue

abstruct:propValue

Factory for property value validator.

import {
  propValue,
  type Validator,
} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
declare const validator: Validator;
const valueValidator = propValue(validator);

and

abstruct:and

Factory for validator composer like Logical AND.

and composes multiple validators and creates a new validator. The composed validator executes the validator from left to right, just like the Logical AND operator. If the validation fails en route, the evaluation stops there.

import {
  and,
  between,
  gte,
  int,
  lte,
} from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
const _int8 = and(int, lte(128), gte(-127));
const __int8 = and(int, between(-127, 128));

note: int8 provides.

Type-narrowing

Composition of and is type-safe.

Each validator is corrected to satisfy the narrowed type from the previous validators.

import {
  and,
  type Validator,
} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
import { assertType, type Has } from "https://deno.land/std/testing/types.ts";
declare const v1: Validator<unknown, string>;
declare const v2: Validator<string, "a" | "b">;
declare const v3: Validator<"a" | "b" | "c", "a">;
const validator = and(v1, v2, v3);

assertType<Has<typeof validator, Validator<unknown, "a">>>(true);

The following example shows type error because it is insufficient narrowing.

import {
  and,
  type Validator,
} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
import { assertType, type Has } from "https://deno.land/std/testing/types.ts";
declare const v1: Validator<number, -1 | 0 | 1>;
declare const v2: Validator<0 | 1, 0>;

// @ts-expect-error v2 should type-compatible with `Validator<-1 | 0 | 1>`.
const validator = and(v1, v2);

The following example is correct because it is faithful to Logical AND narrowing.

import {
  and,
  type Validator,
} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
import { assertType, type Has } from "https://deno.land/std/testing/types.ts";
declare const v1: Validator<unknown, string>;
declare const v2: Validator<unknown, number>;
const validator = and(v1, v2);

assertType<Has<typeof validator, Validator<unknown, never>>>(true);

Limit the number of arguments

The number of arguments is limited by overloading to achieve this.

Currently it accepts up to 5 arguments.

This limit is based on the strict Function.bind type signature.

If more than that is needed, you must nest and.

or

abstruct:or

Factory for validator composer like Logical OR.

import {
  or,
  type Validator,
} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
import { assertType, type Has } from "https://deno.land/std/testing/types.ts";
declare const v1: Validator;
declare const v2: Validator;
declare const v3: Validator;

const validator = or(v1, v2, v3);

If the validators are not type-compatible with each other, generics must be specified.

import {
  or,
  type Validator,
} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
import { assertType, type Has } from "https://deno.land/std/testing/types.ts";
declare const v1: Validator<unknown, string>;
declare const v2: Validator<unknown, number>;
const validator = or<unknown, string | number>(v1, v2);

assertType<Has<typeof validator, Validator<unknown, string | number>>>(true);

For more information, see Specifying Type Arguments.

eq

abstruct:eq

Validator factory equivalent to strict equality(===) operator.

import { eq } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
const validator = eq(0);

ne

abstruct:ne

Factory for validator equivalent to strict inequality(!==) operator.

import { ne } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
const validator = ne(0);

gt

abstruct:gt

Factory for validator equivalent to greater than(<) operator.

import { gt } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
const validator = gt(8);

gte

abstruct:gte

Factory for validator equivalent to greater than or equal(<=) operator.

import { gte } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
const validator = gte(8);

lt

abstruct:lt

Factory for validator equivalent to less than(>) operator.

import { lt } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
const validator = lt(256);

lte

abstruct:lte

Factory for validator equivalent to less than or equal to (>=) operator.

import { lte } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
const validator = lte(255);

between

abstruct:between

Factory for range validator.

import { between } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
const numberRangeValidator = between(0, 255);
const dateRangeValidator = between(new Date("1970/1/1"), new Date("2038/1/19"));

not

abstruct:not

Factory for validator inversion.

import {
  not,
  type Validator,
} from "https://deno.land/x/abstruct@$VERSION/mod.ts";

declare const validator: Validator;
const inversionValidator = not(validator);

has

abstruct:has

Factory for existence of property validator.

import { has } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
const validator = has("prop");

pattern

abstruct:pattern

Factory for regex pattern validator.

import { pattern } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
const validator = pattern(/^\d*$/);

item

abstruct:item

Factory for item validator. It checks each item of items.

import {
  item,
  type Validator,
} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
declare const validator: Validator;
const itemValidator = item(validator);

count

abstruct:count

Factory for count validator. It checks count(size, length) of items.

import { count } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
const validator = count(5);

maxCount

abstruct:maxCount

Factory for max count validator. It checks items count is less than or equal to limit.

import { maxCount } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
declare const limit: number;
const validator = maxCount(limit);

minCount

abstruct:minCount

Factory for min count validator. It checks items count is greater than or equal to limit.

import { minCount } from "https://deno.land/x/abstruct@$VERSION/bindings.ts";
declare const limit: number;
const validator = minCount(limit);

single

abstruct:single

Single validator. It checks items is single.

empty

abstruct:empty

Empty validator. It checks the items is empty.

nonEmpty

abstruct:nonEmpty

Non-Empty validator. It checks items is non-empty.

unique

abstruct:unique

Unique validator. It checks the each item is unique.

fixedArray

abstruct:fixedArray

Factory for fixed array validator. It checks each item passes each Validator.

import {
  fixedArray,
  type Validator,
} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
declare const v1: Validator;
declare const v2: Validator;
const validator = fixedArray(v1, v2);

float

abstruct:float

Float validator.

int

abstruct:int

Integer validator.

positive

abstruct:positive

Positive number validator.

negative

abstruct:negative

Negative number validator.

nonPositive

abstruct:nonPositive

Non-positive number validator.

nonNegative

abstruct:nonNegative

Non-negative number validator.

int8

abstruct:int8

Integer in the range -127 ~ 128 validator.

int16

abstruct:int16

Integer in the range -32768 ~ 32767 validator.

int32

abstruct:int32

Integer in the range -2147483648 ~ 2147483647 validator.

uint8

abstruct:uint8

Integer in the range 0 ~ 255 validator.

uint16

abstruct:uint16

Integer in the range 0 ~ 65535 validator.

uint32

abstruct:uint32

Integer in the range 0 ~ 4294967295 validator.

validDate

abstruct:validDate

Valid Date validator.