Hello, if this is your first time reading the Arcaelas Insiders documentation, let me tell you that you have found a good place to learn.
Our team and community are happy to write and make methods simple to implement and understand, but I think you already know that.
Let's start with the basic implementation steps.
npm i --save @arcaelas/utils
yarn add --save @arcaelas/utils
// Import Statement
import utils from '@arcaelas/utils'
// or
import * as utils from '@arcaelas/utils'
// or
import { someMethodName } from '@arcaelas/utils'
// EsModule
const utils = require('@arcaelas/utils')"Blank" is a method to check if a value is never or is empty value.
import { blank } from '@arcaelas/utils'
blank('') // true
blank([]) // true
blank({}) // true
blank(null) // true
blank(undefined) // true
blank(' ') // true, because have only spaces.This method superficially copies the properties of an object, this method is recommended only for flat objects; Recursive objects or objects that have dependent properties such as Buffer, ArrayBuffer, Blob, File, etc; They will be negatively affected.
const me = { id: 1, profile: { username:"arcaelas" } }
const tmp = copy(me)
tmp.profile.username = "insiders"
console.log( me.profile.username ) // arcaelas
console.log( tmp.profile.username ) // insidersReturn true if value is not empty.
import { empty } from '@arcaelas/utils'
empty(0) // true
empty([]) // true
empty(null) // true
empty(false) // true
empty(undefined) // true
empty([ null ]) // false
empty([ false ]) // false
empty([ undefined ]) // falseWith promify you can make a promise with custom handler easy, if you want create a promise and resolve outer promise you need promify.
import { readFile } from "fs"
import { promify } from '@arcaelas/utils'
// We create a promise instance
const promise = promify()
// Define the process steps to manage the data
promise.then(data=>{
// if request is trusted
console.log("File content:", data)
}).catch(err=>{
// If process is failed
console.error("Error:", err)
})
// Initiate the read file process
readFile(__dirname + "/myfile.md", "utf-8", (err, data)=>{
if(err) promise.reject(err) // reject instance
else promise.resolve(data) // resolve instance to "then"
})Fast random number between range.
import { rand } from '@arcaelas/utils'
const fruits = ['apple', 'mango', 'banana']
const randFruit = fruits[ rand(0, fruits.length - 1) ]
// apple or mango or bananaUse this method to supress process by a few time
import { sleep } from '@arcaelas/utils'
async function submit(form: HTMLFormElement){
await sleep(3000)
return form.submit()
}Replaces the string properties of a template from an element.
const schema = source({ github:"https://github.com/${username}" })
console.log( schema({ email:"community@arcaelas.com", username:"arcaelas" }) )
// Output: { github:"https://github.com/arcaelas" }Create query handlers that allow you to compare objects There are built-in methods that you will find useful, but they can be overridden if you specify them when creating a new handler.
@example
// Create filter with custom handlers
const filter = query({
$isPast(ref: string, value: boolean, item: IObject){
let past = new Date(get(item, ref)) < value // Check if field is less than value
return value ? past : !past // If value is "true", return true when date is outdate.
}
})
// Create a function that allows you to compare the elements, based on the handlers already defined.
const match = filter({
expireAt: {
$isPast: true
}
})
// We filter the elements that have the field "expireAt" in the past.
const offline = items.filter(item=> match( item ))setcookie( name: string, value?: any, exp?: number, path?: string, domain?: string, https?: boolean ): any
In front-end, you need store cookies some times. setcookie help you to make this possible.
Let's imagine you have a login function and you want to save the result in a cookie.
import { setcookie } from '@arcaelas/utils'
function SignIn(email, password){
fetch(...)
.then(res=> res.json())
.then(data=>{
// This handler save "accessToken" cookie without expire time.
setcookie("accessToken", data.accessToken)
// If you need save token with expiration time, so need set expiration time in ms.
// 3600 seconds * 1000 ms = 1 Hour
setcookie("accessToken", data.accessToken, 3600 * 1000)
})
}We can also specify from which route our cookie is available within our domain.
// Cookie with name "key" is only available when our site is in "/shop" page.
setcookie("key", "value", "expireTime in ms", "/shop")We keep in mind that all the cookies that are defined in our application are available only in our domain name where they are defined, but sometimes we want to define them for another domain name.
// For domain http://example.com
setcookie("key", "value", 3600 * 1000)
// Only available in example.com, if you navigate to app.example.com, cookie does not available there.
// On the contrary,
// if you want the cookie to be available in the subdomains
// of your application and/or in another domain.
setcookie("key", "value", 3600 * 1000, ".example.com")
// Or available only in your shop section app.
setcookie("key", "value", 3600 * 1000, "shop.example.com")To read cookie value, you need call setcookie method with just cookie name.
const fetch(..., {
headers: {
authentication: "Bearer " + setcookie("accessToken")
}
})Above we have learned how to define a cookie in our application, but there is another activity to do and that is: How do we delete a cookie without waiting for the expiration time?
import { unsetcookie } from '@arcaelas/utils'
function SignOut(){
unsetcookie("accessToken") // Removing cookie in this app domain.
// To remove cookie in other scope, need more steps:
setcookie("accessToken", "", -1, "Your path if defined", "The domain name if defined")
}Object-oriented Programming (OOP) is very common nowadays, but although EcmaScript allows us many functionalities regarding this development model, we are still limited in many fields, here we will show you how to use some of our tools to make your life easier.
The "dot-key" notation will be common in our learning process since it is one of the most used models in development today and one of the easiest to learn to use.
Above we have explained how to define and verify a property inside our object, but it is useless if we cannot obtain its value.
import { get } from '@arcaelas/utils'
const profile = {
name: "Arcaelas Insiders",
email: "example@arcaelas.com",
skills:{
frontEnd: "23 years",
backEnd: "19 years"
}
}
get(profile, "name") // Arcaelas Insiders
get(profile, "skills.frontEnd") // 23 years
get(profile, "skills.server", "defaultValue") // defaultValueOnce we have defined our object, we may need to know if a property exists on it, regardless of whether it is empty or null.
import { has } from "@arcaelas/utils"
const profile = {
name: "Arcaelas Insiders",
email: "example@arcaelas.com",
skills:{
frontEnd: "23 years",
backEnd: "19 years"
}
}
has(profile, "name") // true
has(profile, "skills.server") // falseWith this method you can extract an array with all properties name as dot-key notation in object.
import { keys } from "@arcaelas/utils"
const profile = {
name: "Arcaelas Insiders",
email: "example@arcaelas.com",
skills:{
frontEnd: "23 years",
backEnd: "19 years"
}
}
keys(profile) // ["name", "email", "skills.frontEnd", "skills.backEnd"]Mixes properties to a target object, mutating its initial structure.
With the "set" method it will be easy to define a value to a property in our object recursively, without having to manually access its properties from our development logic.
import { set } from "@arcaelas/utils"
const profile = {
name: "Arcaelas Insiders",
email: "example@arcaelas.com",
skills:{
frontEnd: "23 years",
backEnd: "19 years"
}
}
console.log(profile.skills)
// Expected: { frontEnd: ... , backEnd: ... }
set(profile, "skills.server", "8 years")
console.log(profile.skills.server) // Expected: 8 yearsOf course, the method responsible for removing some property in our object could not be missing.
import { unset } from '@arcaelas/utils'
const profile = {
name: "Arcaelas Insiders",
email: "example@arcaelas.com",
skills:{
frontEnd: "23 years",
backEnd: "19 years"
}
}
get(profile, "skills.frontEnd") // 23 years
unset(profile, "skills.frontEnd")
get(profile, "skills.frontEnd") // undefined
¿Want to discuss any of my open source projects, or something else?Send me a direct message on Twitter.
If you already use these libraries and want to support us to continue development, you can sponsor us at Github Sponsors.
