preps

Quick shortcut with prepositions

Table of Contents

• Installation
• Usage
  • to(obj: string)
  • to(obj: any[])
  • to(obj: HTMLElement)
  • at(selector: string)
• API
  • Subject
    • final()
    • log()
  • StringSubject
    • as(str: string | ((value: string) => string | void))
    • is(str: string)
    • add(str: string)
    • cut(index: number)
    • split(separator: string)
    • cutfine()
  • ArraySubject
    • as(operation: array | ((value: array) => array | void))
    • is(arr: array)
    • foreach(cb: (item: T, index: number, arr: array) => T | void)
    • remove(which: number | T)
    • removeIndex(index: number)
    • removeItem(item: T)
    • removeItems(target: T)
    • put(index: number, item: T)
    • join(separator: string)
    • sort()
    • reverse()
    • shuffle()
    • filter(cb: (item: T) => boolean)
    • cut(index: number)
    • final(index?: number)
  • DOMSubject
    • as(element: HTMLElement | ((value: HTMLElement) => HTMLElement | void))
    • clear()
    • classes()
    • has(className: string)
    • attr(key: string, value?: string)
    • css()
    • on(event: string, handler: (ev: Event) => void)
    • once(event: string, handler: (ev: Event) => void)
    • off(event: string)
  • CSSSubject
    • get(key: string)
    • set(key: string, value: string)
    • is(key: string, value: string)
    • map()
  • Tool
    • random(min: number, max: number)
    • sleep(ms: number)
    • is(obj1: any, obj2: any)
• LICENSE

Installation

preps is available for both browsers and Node.js.

HTML

<script src="https://cdn.jsdelivr.net/gh/NriotHrreion/preps/dist/preps.min.js"></script>

npm

npm install preps

// esm
import { to, by } from "preps";

// commonjs
const { to, by } = require("preps");

Usage

preps supports chain calling, which means you can do multiple operations with just one line of code. Take the following as an example:

const { to } = require("preps");

to(["3", "2", "4", true, "5", "1", false, {}, "6"])
  .filter((value) => typeof value !== "string")
  .foreach((num) => parseInt(num) + 1)
  .sort()
  .reverse()
  .filter((num) => num % 2 === 0)
  .f();

Run the code, and you would get:

[7, 5, 3]

preps also provides some utilities, and you can get the utils with by(). For example:

const { by } = require("preps");

by().is({ abc: 1, test: "Hello" }, { test: "Hello", abc: 1 }); // true

For detailed usage, please refer to API.

API

to(obj: string)

• Return: StringSubject

This allows you to operate a string with preps. Available operations such as as(), cut(), cutfine(), ...

to("hello")

to(obj: any[])

• Return: ArraySubject

This allows you to operate an array with preps. Available operations such as as(), foreach(), remove(), ...

to(["ABC", "abc", 150, null, true])

to(obj: HTMLElement)

• Return: DOMSubject

This allows you to operate a HTML element with preps. Available operations such as as(), clear(), on(), ...

var elem = document.getElementById("btn");

if(elem) to(elem);

at(selector: string)

• Return: DOMSubject

Almost the same as to(obj: HTMLElement), this allows you to get a HTML element by a selector directly and then operate it with preps.

at("#btn")

by()

• Return: Tool

This allows you to get the Tool class for the utilities.

by()

Subject

All the functions above returns an object that extends Subject. This class provides some basic methods.

final()

• Return: The final result of your operations
• Alias: f()

This method is to finalize a series of operations.

to("hello").add(" world").final() // "hello world"
// or
to("hello").add(" world").f() // "hello world"

log()

• Return: void

This method is to finalize a series of operations and print the result into the console.

to("hello").add(" world").log() // "hello world"

StringSubject

This class is for the operations of strings.

as(operation: string | ((value: string) => string | void))

• Return: StringSubject

This allows you to change the content of the string.

to("hello").as("hi").f() // "hi"
to("hello").as((value) => value.length.toString()).f() // "5"

is(str: string)

• Return: boolean

This allows you to check if the string is equal to another string.

to("hello").is("hello") // true
to("hello").is("hi") // false

add(str: string)

• Return: StringSubject

This allows you to add a string to the end of the string.

to("hello").add(" world").f() // "hello world"

cut(index: number)

• Return: ArraySubject

This allows you to divide the string into two parts.

to("hello").cut(2).f() // ["he", "llo"]

split(separator: string)

• Return: ArraySubject

This allows you to divide the string into pieces by a separator.

to("hello").split("l").f() // ["he", "", "o"]

cutfine()

• Return: ArraySubject

This allows you to divide the string into pieces, and each piece is no more than one character.

to("hello").cutfine().f() // ["h", "e", "l", "l", "o"]

ArraySubject

This class is for the operations of arrays.

Here, we took T[] as array for understandability and simplicity.

as(operation: array | ((value: array) => array | void))

• Return: ArraySubject

This allows you to change the value of the array.

to([1, 2, 3]).as([3]).f() // [3]
to([1, 2, 3]).as((value) => [...value, 4]).f() // [1, 2, 3, 4]

is(arr: array)

• Return: boolean

This allows you to check if the array is equal to another array.

to([1, 2, 3]).is([1, 2, 3]) // true
to([1, 2, 3]).is([1, 2, 4]) // false

foreach(cb: (item: T, index: number, arr: array) => T | void)

• Return: ArraySubject

This allows you to iterate the array.

to([1, 2, 3]).foreach((item) => item + 1).f() // [2, 3, 4]

remove(which: number | T)

• Return: ArraySubject

This allows you to remove an item from the array by the index or the item itself.

to([1, "2", true]).remove(2).f() // [1, "2"]
to([1, "2", true]).remove("2").f() // [1, true]

removeIndex(index: number)

• Return: ArraySubject

This allows you to remove an item from the array by the index.

removeItem(item: T)

• Return: ArraySubject

This allows you to remove an item from the array by the item itself.

removeItems(target: T)

• Return: ArraySubject

This allows you to remove all of the items in the array that are equal to the target.

to([1, 2, 3, 3, 3, 4, 3, 5, 3]).removeItems(3).f() // [1, 2, 4, 5]

put(index: number, item: T)

• Return: ArraySubject

This allows you to insert an item into the array by the index.

to([1, 2, 3]).put(1, 4).f() // [1, 4, 2, 3]

join(separator: string)

• Return: StringSubject

This allows you to join the array into a string.

sort()

• Return: ArraySubject

This allows you to sort the array.

[!NOTE]
This method is only available for number arrays.

to([3, 7, 2, 5, 4, 6, 1]).sort().f() // [1, 2, 3, 4, 5]
to(["Hello", 7, 2, 5, 4, 6, 1]).sort().f() // Error

reverse()

• Return: ArraySubject

This allows you to reverse the array.

to([1, 2, 3]).reverse().f() // [3, 2, 1]

shuffle()

• Return: ArraySubject

This allows you to shuffle the array.

to([1, 2, 3, 4]).shuffle().f()

filter(cb: (item: T) => boolean)

• Return: ArraySubject

This allows you to filter the array with the specific condition.

to([1, 2, 3, 4, 5]).filter((item) => item > 2).f() // [3, 4, 5]

cut(index: number)

• Return: ArraySubject

This allows you to divide the array into two parts.

to([1, 2, 3, 4, 5]).cut(2).f() // [[1, 2], [3, 4, 5]]

final(index?: number)

• Return: The final result of your operations to the array or the specific item in the array.
• Alias: f(index?: number)

Overriding the final() method in Subject, this allows you to get a specific item in the final array. You can also use this method in the common way, which gives you the final result of your operations to the array.

to([1, 2, 3, 4, 5]).final(2) // 3

DOMSubject

This class is for the operations of HTML elements. It is only available in browser environment.

The following code snippets are shown in the context of this HTML file:

<button id="#btn-1" class="cls-1 cls-2">Test 1</button>
<button id="#btn-2" data-attr="1">Test 2</button>

<div id="container">
    <p>Hello</p>
    <p>World</p>
</div>

<span style="color: red">Hello World</span>

as(operation: HTMLElement | ((value: HTMLElement) => HTMLElement | void))

• Return: DOMSubject

This allows you to change the value of the HTML element.

at("#btn-1").as(() => document.querySelector("#btn-2")).f(); // <button id="#btn-2">Test 2</button>

clear()

• Return: DOMSubject

This allows you to clear the child nodes of the HTML element.

at("#container").clear().f() // <div id="container"></div>

classes()

• Return: ArraySubject

This allows you to get the class list of the HTML element.

at("#btn-1").classes().f() // ["cls-1", "cls-2"]

has(className: string)

• Return: boolean

This allows you to check if the HTML element has the specific class.

at("#btn-1").has("cls-1").f() // true
at("#btn-2").has("cls-1").f() // false

attr(key: string, value?: string)

• Return: DOMSubject | StringSubject

This allows you to get or set the attribute of the HTML element. If the value is specified, it will set the attribute value. Otherwise, it will return the attribute value.

at("#btn-2").attr("data-attr").f() // "1"
at("#btn-2").attr("data-attr", "2").f() // <button id="#btn-2" data-attr="2">Test 2</button>

css()

• Return: CSSSubject

This allows you to get the CSSSubject instance of the HTML element, which enables you to edit the CSS styles.

at("span").css().f() // CSSSubject { color: "red" }

on(event: string, handler: (ev: Event) => void)

• Return: DOMSubject

This allows you to add an event listener to the HTML element.

at("#btn-1").on("click", () => alert("Hello World!")).f()

once(event: string, handler: (ev: Event) => void)

• Return: DOMSubject

This allows you to add a one-time event listener to the HTML element.

at("#btn-1").once("click", () => alert("Hello World!")).f()

off(event: string)

• Return: DOMSubject

This allows you to remove events of a specific event type from the HTML element.

// Remove all the click handlers of the button
at("#btn-1").off("click").f()

CSSSubject

This class is for editing the CSS styles of HTML elements. It is only available in browser environment.

You can only get the instance by the css() method in DOMSubject.

get(key: string)

• Return: string

This allows you to get the value of the CSS property.

at("span").css().get("color") // "red"

set(key: string, value: string)

• Return: CSSSubject

This allows you to set the value of the CSS property.

at("span").css().set("color", "blue").f() // CSSSubject { color: "blue" }

is(key: string, value: string)

• Return: boolean

This allows you to check if the CSS property is the specified value.

at("span").css().is("color", "red") // true
at("span").css().is("color", "blue") // false

map()

• Return: Map<string, string>

This allows you to get the map of the CSS properties.

at("span").css().map() // Map { color: "red" }

Tool

This class is a utility class.

random(min: number, max: number)

• Return: number

This allows you to get a random number between the specified range.

by().random(1, 10)

sleep(ms: number)

• Return: void
• Async

This allows you to let the program sleep for a specified time.

await by().sleep(1000)

is(obj1: any, obj2: any)

• Return: boolean

This allows you to check if two values are equal. It supports comparing objects, arrays, etc.

by().is(1, 1) // true
by().is(1, 2) // false
by().is({ a: 1, b: 2 }, { b: 2, a: 1 }) // true

LICENSE

MIT