Guarder provides simple validation logic to reduce clutter with inline guard statements
npm install guarder




Guarder is a simple validation library that allows quick validation on properties.
This project is still in development.
- 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
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
Use the following command to install the Guarder package:
``
npm i guarder
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)
`
#### .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 andnull
error to be thrown if the property is .
`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 errorundefined
message and error to be thrown if the property is .
`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 andempty
error to be thrown if the property is . 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.
`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.TestGuard
The 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 })
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.
If you find any problems while working with this library, please log an issue
here so that development can begin to rectify the error.
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.
MIT License
Copyright (c) 2021 Alex Pickering