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:

$ git clone [email protected]: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.

// 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.

// 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.

// 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.

// 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

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.

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.

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.

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.

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.

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.

$ 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