![](\"https://ao-framework.github.io/assets/readmeHeader.png\")
\r\n\r\n \r\n
\r\n Gates. To streamline logic.\r\n
\r\n\r\n \r\n This project is currently in early development. \r\n Expect erratic behaviour frequently as development happens.\r\n \r\n
\r\n\r\n### What is Gates?\r\nGates is a library with many functions to make writing logic less fatiguing and more stable. The functions are broken into five categories: \r\n- Ensure Functions\r\n- Is Functions\r\n- Returning Functions\r\n- Throwing Functions\r\n- When Functions\r\n\r\n### Installation\r\n```bash\r\nnpm install --save @ao-framework/gates\r\n```\r\nTypescript types are included.\r\n\r\n### How Do I Import Gates?\r\n```js\r\n// You can import a single function for tree shaking\r\nimport { isFunction } from \"@ao-framework/gates\"\r\n\r\n// You can import everything\r\nimport * as gates from \"@ao-framework/gates\"\r\n\r\n// You can import by using Old Faithful.\r\nconst gates = require(\"@ao-framework/gates\")\r\n```\r\n*************************\r\n**A common use case code example is provided below each description for visual code learners.\r\n\r\n\r\n### Ensure Functions\r\nThis category is used to ensure that variables are what you think they are.\r\n```ts\r\nimport { ensureObject, ensureFunction } from \"@ao-framework/gates\"\r\n\r\nfunction myLibrary(options: iMyOptions) {\r\n const defaultOptions = { x: 0, y: 0 }\r\n const finalOptions = ensureObject(options, defaultOptions, false);\r\n ensureFunction(finalOptions.loaded)()\r\n}\r\n```\r\n- ensureObject\r\n- ensureArray\r\n- ensureFunction \r\n\r\n\r\n### Is Functions\r\nThis category is used to assert that a variable is a particular type.\r\n```ts\r\nimport { isString, isNumber } from \"@ao-framework/gates\"\r\n\r\nfunction doSomething(v: string | number) {\r\n if(isString(v)) { /** do something */ }\r\n if(isNumber(v)) { /** do something */ }\r\n}\r\n```\r\nFor **Typescript** users, please note that **Type Guards** were used so that intellisense knowledge is maintained.\r\n\r\n- isObjectLike\r\n- isObject\r\n- isString\r\n- isStringWithLength\r\n- isFunction\r\n- isBoolean\r\n- isNumber\r\n- isArray\r\n- isUndefined\r\n- isNull\r\n- isNill\r\n- isBigInt\r\n- isSymbol\r\n- constructedFrom\r\n\r\n#### Is Functions include the negations\r\n- isNotObjectLike\r\n- isNotObject\r\n- isNotString\r\n- isNotStringWithLength\r\n- isNotFunction\r\n- isNotBoolean\r\n- isNotNumber\r\n- isNotArray\r\n- isNotUndefined\r\n- isNotNull\r\n- isNotNill\r\n- isNotBigInt\r\n- isNotSymbol\r\n\r\n### Returning Functions\r\nThis category is used to make sure that you have either the correct type assigned or nothing at all.\r\n```ts\r\nimport { returnStringWithLengthOrNothing } from \"@ao-framework/gates\"\r\n\r\nfunction createUser(data: iCreateUserRequest) {\r\n const user = new User();\r\n user.name = returnStringWithLengthOrNothing(data.name);\r\n user.email = returnStringWithLengthOrNothing(data.email);\r\n}\r\n```\r\n\r\n- returnObjectLikeOrNothing\r\n- returnObjectOrNothing\r\n- returnStringOrNothing\r\n- returnStringWithLengthOrNothing\r\n- returnFunctionOrNothing\r\n- returnBooleanOrNothing\r\n- returnNumberOrNothing\r\n- returnArrayOrNothing\r\n- returnNullOrNothing\r\n- returnBigIntOrNothing\r\n- returnSymbolOrNothing\r\n\r\n### Throwing Functions\r\nThis category is used to streamline throwing exceptions when variables are not needed types.\r\n```ts\r\nimport { throwWhenNotObject, throwWhenNotStringWithLength } from \"@ao-framework/gates\"\r\n\r\nfunction validateUser(user: User) {\r\n throwWhenNotObject(user, \"User object was not created\", SystemException)\r\n throwWhenNotStringWithLength(user.name, \"User must have a name\", BadInputException)\r\n throwWhenNotStringWithLength(user.email, \"User must have an email\", BadInputException)\r\n}\r\n```\r\n\r\n- throwException\r\n- throwWhenObjectLike\r\n- throwWhenObject\r\n- throwWhenString\r\n- throwWhenStringWithLength\r\n- throwWhenFunction\r\n- throwWhenBoolean\r\n- throwWhenNumber\r\n- throwWhenArray\r\n- throwWhenUndefined\r\n- throwWhenNull\r\n- throwWhenNill\r\n- throwWhenBigInt\r\n- throwWhenSymbol\r\n\r\n#### Throwing Functions include the negations\r\n- throwWhenNotObjectLike\r\n- throwWhenNotObject\r\n- throwWhenNotString\r\n- throwWhenNotStringWithLength\r\n- throwWhenNotFunction\r\n- throwWhenNotBoolean\r\n- throwWhenNotNumber\r\n- throwWhenNotArray\r\n- throwWhenNotUndefined\r\n- throwWhenNotNull\r\n- throwWhenNotNill\r\n- throwWhenNotBigInt\r\n- throwWhenNotSymbol\r\n\r\n### When Functions\r\nThis category is used to be a short replacement for if statements.\r\n```ts\r\nimport { when, whenString } from \"@ao-framework/gates\"\r\n\r\nwhen(something === true)(fnThatCanBeCalled)\r\nwhenString(nameOfUser)(fnThatCanBeCalledExpectingString);\r\n```\r\n\r\n- when\r\n- whenObjectLike\r\n- whenObject\r\n- whenString\r\n- whenStringWithLength\r\n- whenFunction\r\n- whenBoolean\r\n- whenNumber\r\n- whenArray\r\n- whenUndefined\r\n- whenNull\r\n- whenNill\r\n- whenBigInt\r\n- whenSymbol\r\n\r\n#### When Functions include the negations\r\n- whenNotObjectLike\r\n- whenNotObject\r\n- whenNotString\r\n- whenNotStringWithLength\r\n- whenNotFunction\r\n- whenNotBoolean\r\n- whenNotNumber\r\n- whenNotArray\r\n- whenNotUndefined\r\n- whenNotNull\r\n- whenNotNill\r\n- whenNotBigInt\r\n- whenNotSymbol\r\n\r\n\r\n### At the End of the Day\r\n\r\nYou can turn something like this...\r\n```ts\r\nimport { cleanString } from \"./commons\"\r\n\r\nfunction createPost(request: iPostRequest) {\r\n\r\n // validation & construction are together\r\n // and not easily refactorable.\r\n\r\n if(typeof request === \"object\" && request !== null) {\r\n const post = new Post();\r\n if(typeof request.title === \"string\") { \r\n post.title = cleanString(request.title)\r\n } else { \r\n throw new Error(\"Post title must be a string\") \r\n }\r\n if(typeof request.content === \"string\") { \r\n post.content = cleanString(request.content) \r\n } else { \r\n throw new Error(\"Post content must be a string\") \r\n }\r\n if(Array.isArray(request.tags)) {\r\n request.tags.forEach(tag => {\r\n if(typeof tag !== \"string\") {\r\n throw new Error(\"Post tag must be a string\")\r\n }\r\n })\r\n } else {\r\n throw new Error(\"Post tags must be an array\")\r\n }\r\n return post;\r\n } else {\r\n throw new Error(\"Post request data is corrupt\")\r\n }\r\n}\r\n```\r\n\r\nTo something more refactorable...\r\n```ts\r\nimport { cleanString } from \"./commons\"\r\n\r\nfunction createPost(request: iPostRequest) {\r\n\r\n // validation -> easily refactorable\r\n\r\n assert(typeof request === \"object\" && request !== null, \r\n \"Post request data is corrupt\")\r\n\r\n assert(typeof request.title === \"string\", \r\n \"Post title must be a string\")\r\n \r\n assert(typeof request.content === \"string\", \r\n \"Post content must be a string\")\r\n \r\n assert(Array.isArray(request.tags), \r\n \"Post tags must be an array\")\r\n \r\n request.tags.forEach(tag => \r\n assert(typeof tag === \"string\", \r\n \"Post tag must be a string\"))\r\n\r\n // construction -> feeling secure\r\n\r\n const post = new Post();\r\n post.title = cleanString(request.title)\r\n post.content = cleanString(request.content)\r\n post.tags = request.tags.map(tag => cleanString(tag))\r\n return post;\r\n}\r\n```\r\nNow something more readable\r\n```ts\r\nimport { cleanString } from \"./commons\"\r\n\r\nfunction createPost(request: iPostRequest) {\r\n \r\n // validation -> easily refactorable\r\n\r\n throwWhenNotObject(request, \"Post request data is corrupt\")\r\n throwWhenNotString(request.title, \"Post title must be a string\")\r\n throwWhenNotString(request.content, \"Post content must be a string\")\r\n throwWhenNotArray(request.tags, \"Post tags must be an array\")\r\n request.tags.forEach(tag => throwWhenNotString(tag, \"Post tag must be a string\"))\r\n\r\n // construction -> feeling secure\r\n\r\n const post = new Post();\r\n post.title = cleanString(request.title)\r\n post.content = cleanString(request.content)\r\n post.tags = request.tags.map(tag => cleanString(tag))\r\n return post;\r\n}\r\n```\r\n","readmeFilename":"README.md"}