Guarder


Guarder is a simple validation library that allows quick validation on properties.

This project is still in development.

Contents

- Getting Started
- Installation
- Guides
- Default Guards
- Official Guards
- Examples
- Usage
- Null Guard
- Undefined Guard
- Empty Guard
- Falsy Guard
- Get Registered Guards
- Unregister Guard
- Register Guard
- Custom Guards
- Inline Custom Guards
- Tests
- Issues
- Contributions
- License

Getting Started

You can get started with cloning the Guarder repository by using the following command:

``bash
$ git clone git@github.com:ToeFungi/guarder.git
$ cd guarder
$ npm i
`

Installation

Use the following command to install the Guarder package:

`
npm i guarder
`

Guides

Guides are basic information about the package for easier use. This section aims to satisfy FAQs.

#### Default Guards

The default configured guards are the following:

- EmptyGuard
_Empty Guard ensures that the property is not null or undefined. A string should contain at least one character, an
array should contain at least one item, an object should contain at least one key_
- FalsyGuard
_Falsy Guard ensures that the property does not evaluate to false in a type coercion_
- NullGuard
_Undefined Guard ensures that the property is not null_
- UndefinedGuard
_Undefined Guard ensures that the property is not undefined_

As a general rule of thumb, default configured guards will always be available by name within the Guarder class.

#### Official Guards

The full list of packaged official guards include:

- EmptyGuard
_Empty Guard ensures that the property is not null or undefined. A string should contain at least one character, an
array should contain at least one item, an object should contain at least one key_
- FalsyGuard
_Falsy Guard ensures that the property does not evaluate to false in a type coercion_
- NegativeGuard
_Negative Guard validates a property is not a negative number_
- NullGuard
_Undefined Guard ensures that the property is not null_
- NumberGuard
_Number Guard validates that the property is a number_
- UndefinedGuard
_Undefined Guard ensures that the property is not undefined_
- WhitespaceGuard
_Whitespace Guard validates that the string does not contain only whitespace_
- ZeroGuard
_Zero Guard validates that the property is not zero_

#### Examples

Considering this is a convenience package, the following example highlights reducing line count.

`typescript
// This is
if (property === undefined || property === null) {
throw new Error('Property cannot be null')
}

// Replace by this
Guard.null(property)
// Or this
Guard.null(property, 'Custom Error Message')
// Or this
Guard.null(property, 'Custom Error Message', CustomError)
`

Usage

#### .null(property: T, message?: string, error?: Instantiable)

You can validate that the specified property is not null using the .null guard and specify the error message and
error to be thrown if the property is null.

`typescript
// Returns the property
const property = Guarder.null('not null')
console.log({ property })

// Throws ArgumentError
const property = Guarder.null(null)

// Throws ArgumentError('Property is null')
const property = Guarder.null(null, 'Property is null')

// Throws CustomError('Property is null')
const property = Guarder.null(null, 'Property is null', CustomError)
`

#### .undefined(property: T, message?: string, error?: Instantiable)

You can validate that the specified property is not undefined using the .undefined guard and specify the error
message and error to be thrown if the property is undefined.

`typescript
// Returns the property
const property = Guarder.undefined('not undefined')
console.log({ property })

// Throws ArgumentError
const property = Guarder.undefined(undefined)

// Throws ArgumentError('Property is undefined')
const property = Guarder.undefined(undefined, 'Property is undefined')

// Throws CustomError('Property is undefined')
const property = Guarder.undefined(undefined, 'Property is undefined', CustomError)
`

#### .empty(property: T, message?: string, error?: Instantiable)

You can validate that the specified property is not empty using the .empty guard and specify the error message and
error to be thrown if the property is empty. The property will be considered empty if:

It is an empty string, an array with length of 0 or an object with no keys. Undefined and null are also considered to be
empty.

`typescript
// Returns the property
const property = Guarder.empty('not empty')
console.log({ property })

// Throws ArgumentError
const property = Guarder.empty('')
const property = Guarder.empty([])
const property = Guarder.empty({})
const property = Guarder.empty(null)
const property = Guarder.empty(undefined)

// Throws ArgumentError('Property is empty')
const property = Guarder.empty('', 'Property is empty')

// Throws CustomError('Property is empty')
const property = Guarder.empty('', 'Property is undefined', CustomError)
`

#### .falsy(property: T, message?: string, error?: Instantiable)

You can guard against values that evaluate to false in type coercion.

Falsy Values

`typescript
Guarder.falsy('') // Error
Guarder.falsy(false) // Error
Guarder.falsy(0) // Error
Guarder.falsy(-0) // Error
Guarder.falsy(null) // Error
Guarder.falsy(undefined) // Error

Guarder.falsy('foo') // 'foo'
Guarder.falsy(1) // 1
Guarder.falsy([]) // []
Guarder.falsy({}) // {}
`

#### .getRegisteredGuards()

You can retrieve the list of registered guards to validate the guard functionality available. By default, the empty,
null and undefined guards are initialised.

`typescript
const guards = Guarder.getRegisteredGuards()
console.log({ guards })
// [ 'null', 'empty', 'undefined' ]
`

#### .unregisterGuard(guardName: string)

You can unregister a specific guard by name. This will remove the guard from the map and it will no longer be available
for use.

`typescript
Guarder.unregisterGuard('empty')

const guards = Guarder.getRegisteredGuards()
console.log({ guards })
// [ 'null', 'undefined' ]
`

#### .registerGuard(guardName: string, guard: Instantiable)

You can register guards and specify the guard name. This allows you to build custom guards and register them for use.

`typescript
Guarder.registerGuard('custom-guard', TestGuard)

const guards = Guarder.getRegisteredGuards()
console.log({ guards })
// [ 'null', 'empty', 'undefined', 'custom-guard' ]
`

#### .custom(guardName: string, property: T, message?: string, error?: Instantiable)

You can use your custom guard after it is registered with the custom functionality. You need to specify which guard
you want to use and pass the remaining parameters as normal.

`typescript
Guarder.registerGuard('custom-guard', TestGuard)
const property = Guarder.custom('custom-guard', 'property', 'Property failed validation', CustomError)
console.log({ property })
`

#### .guard(guard: Guard, property: T, message?: string, error?: Instantiable)

You can specify the guard to use as a once off guard without needing to register it using the inlineCustom mechanism.
The TestGuard guard will not be registered in the guard map and will need to be passed each time the mechanism is
used.

`typescript
const property = Guarder.inlineCustom(TestGuard, 'property', 'Property failed validation', CustomError)
console.log({ property })
`

Tests

To run tests, you should be able to simply run be able to run the following.

`bash
$ npm run test
$ npm run coverage
``

The testing framework used is Mocha. Chai and nyc are used for assertions and coverage reporting respectively. Ensure
that any new changes are covered by an accompanying test suite.

Issues

If you find any problems while working with this library, please log an issue
here so that development can begin to rectify the error.

Contributions

This project is completely open source and as such, you are invited to make contributions. Fork the project, make some
changes and make the pull request. If you have any feedback regarding the functionality, please don't hesitate to open
an issue so this can be resolved. Please ensure that any pull requests have unit tests that cover any additional
functionality.

License

MIT License

Copyright (c) 2021 Alex Pickering