What is Gates?

Gates is a library with many functions to make writing logic less fatiguing and more stable. The functions are broken into five categories:

• Ensure Functions
• Is Functions
• Returning Functions
• Throwing Functions
• When Functions

Installation

npm install --save @ao-framework/gates

Typescript types are included.

How Do I Import Gates?

// You can import a single function for tree shaking
import { isFunction } from "@ao-framework/gates"

// You can import everything
import * as gates from "@ao-framework/gates"

// You can import by using Old Faithful.
const gates = require("@ao-framework/gates")

**A common use case code example is provided below each description for visual code learners.

Ensure Functions

This category is used to ensure that variables are what you think they are.

import { ensureObject, ensureFunction } from "@ao-framework/gates"

function myLibrary(options: iMyOptions) {
    const defaultOptions = { x: 0, y: 0 }
    const finalOptions = ensureObject(options, defaultOptions, false);
    ensureFunction(finalOptions.loaded)()
}

• ensureObject
• ensureArray
• ensureFunction

Is Functions

This category is used to assert that a variable is a particular type.

import { isString, isNumber } from "@ao-framework/gates"

function doSomething(v: string | number) {
    if(isString(v)) { /** do something */ }
    if(isNumber(v)) { /** do something */ }
}

For Typescript users, please note that Type Guards were used so that intellisense knowledge is maintained.

• isObjectLike
• isObject
• isString
• isStringWithLength
• isFunction
• isBoolean
• isNumber
• isArray
• isUndefined
• isNull
• isNill
• isBigInt
• isSymbol
• constructedFrom

Is Functions include the negations

• isNotObjectLike
• isNotObject
• isNotString
• isNotStringWithLength
• isNotFunction
• isNotBoolean
• isNotNumber
• isNotArray
• isNotUndefined
• isNotNull
• isNotNill
• isNotBigInt
• isNotSymbol

Returning Functions

This category is used to make sure that you have either the correct type assigned or nothing at all.

import { returnStringWithLengthOrNothing } from "@ao-framework/gates"

function createUser(data: iCreateUserRequest) {
    const user = new User();
    user.name = returnStringWithLengthOrNothing(data.name);
    user.email = returnStringWithLengthOrNothing(data.email);
}

• returnObjectLikeOrNothing
• returnObjectOrNothing
• returnStringOrNothing
• returnStringWithLengthOrNothing
• returnFunctionOrNothing
• returnBooleanOrNothing
• returnNumberOrNothing
• returnArrayOrNothing
• returnNullOrNothing
• returnBigIntOrNothing
• returnSymbolOrNothing

Throwing Functions

This category is used to streamline throwing exceptions when variables are not needed types.

import { throwWhenNotObject, throwWhenNotStringWithLength } from "@ao-framework/gates"

function validateUser(user: User) {
    throwWhenNotObject(user, "User object was not created", SystemException)
    throwWhenNotStringWithLength(user.name, "User must have a name", BadInputException)
    throwWhenNotStringWithLength(user.email, "User must have an email", BadInputException)
}

• throwException
• throwWhenObjectLike
• throwWhenObject
• throwWhenString
• throwWhenStringWithLength
• throwWhenFunction
• throwWhenBoolean
• throwWhenNumber
• throwWhenArray
• throwWhenUndefined
• throwWhenNull
• throwWhenNill
• throwWhenBigInt
• throwWhenSymbol

Throwing Functions include the negations

• throwWhenNotObjectLike
• throwWhenNotObject
• throwWhenNotString
• throwWhenNotStringWithLength
• throwWhenNotFunction
• throwWhenNotBoolean
• throwWhenNotNumber
• throwWhenNotArray
• throwWhenNotUndefined
• throwWhenNotNull
• throwWhenNotNill
• throwWhenNotBigInt
• throwWhenNotSymbol

When Functions

This category is used to be a short replacement for if statements.

import { when, whenString } from "@ao-framework/gates"

when(something === true)(fnThatCanBeCalled)
whenString(nameOfUser)(fnThatCanBeCalledExpectingString);

• when
• whenObjectLike
• whenObject
• whenString
• whenStringWithLength
• whenFunction
• whenBoolean
• whenNumber
• whenArray
• whenUndefined
• whenNull
• whenNill
• whenBigInt
• whenSymbol

When Functions include the negations

• whenNotObjectLike
• whenNotObject
• whenNotString
• whenNotStringWithLength
• whenNotFunction
• whenNotBoolean
• whenNotNumber
• whenNotArray
• whenNotUndefined
• whenNotNull
• whenNotNill
• whenNotBigInt
• whenNotSymbol

At the End of the Day

You can turn something like this...

import { cleanString } from "./commons"

function createPost(request: iPostRequest) {

    // validation & construction are together
    // and not easily refactorable.

    if(typeof request === "object" && request !== null) {
         const post = new Post();
        if(typeof request.title === "string") { 
            post.title = cleanString(request.title)
        } else { 
            throw new Error("Post title must be a string") 
        }
        if(typeof request.content === "string") { 
            post.content = cleanString(request.content) 
        } else { 
            throw new Error("Post content must be a string") 
        }
        if(Array.isArray(request.tags)) {
            request.tags.forEach(tag => {
                if(typeof tag !== "string") {
                    throw new Error("Post tag must be a string")
                }
            })
        } else {
            throw new Error("Post tags must be an array")
        }
        return post;
    } else {
        throw new Error("Post request data is corrupt")
    }
}

To something more refactorable...

import { cleanString } from "./commons"

function createPost(request: iPostRequest) {

    // validation -> easily refactorable

    assert(typeof request === "object" && request !== null, 
        "Post request data is corrupt")

    assert(typeof request.title === "string", 
        "Post title must be a string")
    
    assert(typeof request.content === "string", 
        "Post content must be a string")
    
    assert(Array.isArray(request.tags), 
        "Post tags must be an array")
    
    request.tags.forEach(tag => 
        assert(typeof tag === "string", 
            "Post tag must be a string"))

    // construction -> feeling secure

    const post = new Post();
    post.title = cleanString(request.title)
    post.content = cleanString(request.content)
    post.tags = request.tags.map(tag => cleanString(tag))
    return post;
}

Now something more readable

import { cleanString } from "./commons"

function createPost(request: iPostRequest) {
    
    // validation -> easily refactorable

    throwWhenNotObject(request, "Post request data is corrupt")
    throwWhenNotString(request.title, "Post title must be a string")
    throwWhenNotString(request.content, "Post content must be a string")
    throwWhenNotArray(request.tags, "Post tags must be an array")
    request.tags.forEach(tag => throwWhenNotString(tag, "Post tag must be a string"))

    // construction -> feeling secure

    const post = new Post();
    post.title = cleanString(request.title)
    post.content = cleanString(request.content)
    post.tags = request.tags.map(tag => cleanString(tag))
    return post;
}