npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@arcaelas/utils

v2.0.4

Published

A small box of tools, which are implemented in different factions of the library.

Downloads

429

Readme

Arcaelas Insiders Banner Arcaelas Insiders Banner

Welcome to Arcaelas Insiders!

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

Implementatión

// 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( value?: any ): boolean

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

copy(object: any): object

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

empty( value?: any ): boolean

Return 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 ])  // false

promify(): Promify

With 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"
})

rand( min: number, max?: number ): number

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 banana

sleep( ms: number ): never

Use 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()
}

source(schema: object): fn

Replaces the string properties of a template from an element.

const schema = source({ github:"https://github.com/${username}" })
console.log( schema({ email:"[email protected]", username:"arcaelas" }) )
	// Output: { github:"https://github.com/arcaelas" }

query

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")

Reading Cookie

To read cookie value, you need call setcookie method with just cookie name.

const fetch(..., {
	headers: {
		authentication: "Bearer " + setcookie("accessToken")
	}
})

unsetcookie( name: string ): boolean

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")
}

Working with Objects

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.

get(o: object, path: string, default: any): any

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: "[email protected]",
	skills:{
		frontEnd: "23 years",
		backEnd: "19 years"
	}
}
get(profile, "name") // Arcaelas Insiders
get(profile, "skills.frontEnd") // 23 years
get(profile, "skills.server", "defaultValue") // defaultValue

has( o: object, path: string ): boolean

Once 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: "[email protected]",
	skills:{
		frontEnd: "23 years",
		backEnd: "19 years"
	}
}
has(profile, "name") // true
has(profile, "skills.server") // false

keys(o: object): string[]

With 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: "[email protected]",
	skills:{
		frontEnd: "23 years",
		backEnd: "19 years"
	}
}
keys(profile) // ["name", "email", "skills.frontEnd", "skills.backEnd"]

merge(target: object, ...objects: object[]): target

Mixes properties to a target object, mutating its initial structure.

set(o: object, path: string, value: any ): any

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: "[email protected]",
	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 years

unset( o: object, path: string ): boolean

Of 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: "[email protected]",
	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.