Skip to content

Commit

Permalink
docs: Add generated documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
davidkarolyi committed Mar 7, 2022
1 parent 316c9d1 commit f6f4bca
Show file tree
Hide file tree
Showing 13 changed files with 1,947 additions and 129 deletions.
154 changes: 37 additions & 117 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ try {
const user = TUser.cast({ posts: ["Who am I?", "I am a user."] });
// Type of user is User
} catch (error) {
// error.message === 'Validation failed: Missing value at "name", expected type: string'
// error.message === 'Validation failed: Missing value at "id", expected type: string(UUID-v4)'
}
```

Expand Down Expand Up @@ -190,8 +190,7 @@ new Guard({

## Schema

`Schema` can be a single [Validator](#validators),
a Guard, or an object of these types.
`Schema` can be a single [Validator](#validators), or an object of [Validators](#validators).

```ts
import { Schema, TBoolean, TString, TNumber } from "tguard";
Expand All @@ -210,7 +209,7 @@ const userSchema: Schema = {
};
```

## Guard<T>
## Guard

### Type Predicate Functions

Expand Down Expand Up @@ -244,7 +243,7 @@ if (TUser.isValid(user)) {
}
```

> Note that this is possible, because Guard could automatically figure out the guarded type from the schema.
> Note that this is possible, because Guard could automatically figure out the guarded TypeScript type from the schema.
### Type Casting

Expand Down Expand Up @@ -276,7 +275,7 @@ try {

## Validators

Validators are instances of `Validator` that have an `isValid` method, and a `name` property, which represents the name of the guarded type.
Validators are instances of `Validator` abstract class that have an `isValid` method, and a `name` property, which represents the name of the guarded type.

> Note that this means that Guards are Validators as well. This means you can reuse them in other guard schemas.
Expand All @@ -288,129 +287,50 @@ TArray(TNumber).name === "number[]"; // true

const TUser = new Guard({ name: TString });
TUser.name === '{"name":"string"}'; //true

const TUserGroup = new Guard({ name: TString, users: TArray(TUser) });
```

Validators are prefixed with the letter `T`, to indicate that they are representing a type of some sort,
and to differentiate them from the built-in vanilla JavaScript types, like `Array` or `String`.

> ⚠️ Not all the validators are documented here. Check `validators.ts`, or exported members to see all of them.
### `TAny`

Accepts every value.

### `TString`

Accepts the JS type `string`.

### `TBigInt`

Accepts the JS type `bigint`.

### `TBoolean`

Accepts the JS type `boolean`.

### `TFunction`

Accepts the JS type `function`.

### `TNull`

Accepts only `null`.

### `TNumber`

Accepts the JS type `number`.

### `TNumberAsString`

Accepts only `strings`, that can be converted to a valid `number`.

### `TObject`

Accepts the JS type `boolean`. (including `null`)

### `TUndefined`

Accepts the JS type `undefined`.
- [TAny](/docs/modules.md#tany)
- [TBigInt](/docs/modules.md#tbigint)
- [TBoolean](/docs/modules.md#tboolean)
- [TFunction](/docs/modules.md#tfunction)
- [TNull](/docs/modules.md#tnull)
- [TNumber](/docs/modules.md#tnumber)
- [TNumberAsString](/docs/modules.md#tnumberasstring)
- [TObject](/docs/modules.md#tobject)
- [TString](/docs/modules.md#tstring)
- [TStringEmail](/docs/modules.md#tstringemail)
- [TStringISODate](/docs/modules.md#tstringisodate)
- [TStringJSON](/docs/modules.md#tstringjson)
- [TStringJWT](/docs/modules.md#tstringjwt)
- [TStringMIMEType](/docs/modules.md#tstringmimetype)
- [TStringPhoneNumber](/docs/modules.md#tstringphonenumber)
- [TStringSemVer](/docs/modules.md#tstringsemver)
- [TStringURL](/docs/modules.md#tstringurl)
- [TUndefined](/docs/modules.md#tundefined)

## Compound Validators

A function that returns a [Validator](#validators), called a compound validator.

> ⚠️ Not all the validators are documented here. Check `validators.ts`, or exported members to see all of them.
### `TArray(validator: Validator)`

Accpets an `array` of the type validated by the given `validator`.

```ts
const validator = new TArray(TNumber);

validator.isValid([1, 2, 3]); // true
validator.isValid([1, 2, "3"]); // false
validator.name === "number[]"; // true
```

### `TObjectOfShape(shape: { keys: Validator, values: Validator })`

Accpets not-null objects where
all keys and values are accepted by the given shape `validators`.
Similar in mind as TypeScript's `{[keys: string]: number}` type annotations.

```ts
const validator = new TObjectShape({
keys: TString,
values: TNumber,
});

validator.isValid({
avocado: 2,
orange: 5,
}); // true

validator.isValid({
avocado: "green",
orange: 5,
}); // false

validator.name === "{ [string]: number }"; // true
```

### `TStringMatch(patternName: string, regexp: RegExp)`

Accepts strings that matches `regexp`.
`patternName` is used to describe the regular expression in a user-readable manner.
For example:

```ts
const validator = new TStringMatch("email", /^\S+@\S+$/);

validator.isValid("foo@bar.com"); // true
validator.isValid("foobar.com"); // false
validator.name === "string(email)"; // true
```

### `TOr(...validators: Validator[])`

Similar in concept as the `|` operator in TypeScript.

Accepts a value when it was accepted by at least one of the `validators`.

### `TAnd(validatorA: Validator, validatorB: Validator)`

Similar in concept as the `&` operator in TypeScript.

Accepts a value when it was accepted by both `validatorA` and `validatorB`.

### `TNot(validator: Validator)`

Accepts a value when it was **not** accepted by the given validator.
- [TAnd](/docs/modules.md#tand)
- [TArray](/docs/modules.md#tarray)
- [TNot](/docs/modules.md#tnot)
- [TObjectOfShape](/docs/modules.md#tobjectofshape)
- [TOr](/docs/modules.md#tor)
- [TStringBase64](/docs/modules.md#tstringbase64)
- [TStringMatch](/docs/modules.md#tstringmatch)
- [TStringOfLength](/docs/modules.md#tstringoflength)
- [TStringUUID](/docs/modules.md#tstringuuid)
- [TValidate](/docs/modules.md#tvalidate)

## Custom Validators
## Defining Custom Validators

You can define any custom [validator](#validators) or [compound validator](#compound-validators) with the `TValidator` compound validator.
You can define any custom [validator](#validators) or [compound validator](#compound-validators) with the [`TValidate`](/docs/modules.md#tvalidate) compound validator.

### Examples

Expand Down
1 change: 1 addition & 0 deletions docs/.nojekyll
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.
Loading

0 comments on commit f6f4bca

Please sign in to comment.