CoreUtils

Cross-platform, general-purpose, JavaScript core library for Node, Deno and the browser.
Intended to be used in conjunction with @sv443-network/userutils and @sv443-network/djsutils, but can be used independently as well.

Documentation • Features • Installation • License • Changelog

Features

• Array:
  • 🟣 function randomItem() - Returns a random item from the given array
  • 🟣 function randomItemIndex() - Returns a random array item and index as a tuple
  • 🟣 function randomizeArray() - Returns a new array with the items in random order
  • 🟣 function takeRandomItem() - Returns a random array item and mutates the array to remove it
  • 🟣 function takeRandomItemIndex() - Returns a random array item and index as a tuple and mutates the array to remove it
  • 🔷 type NonEmptyArray - Non-empty array type
• Colors:
  • 🟣 function darkenColor() - Darkens the given color by the given percentage
  • 🟣 function hexToRgb() - Converts a hex color string to an RGB object
  • 🟣 function lightenColor() - Lightens the given color by the given percentage
  • 🟣 function rgbToHex() - Converts an RGB object to a hex color string
• Crypto:
  • 🟣 function abtoa() - Converts an ArrayBuffer to a string
  • 🟣 function atoab() - Converts a string to an ArrayBuffer
  • 🟣 function compress() - Compresses the given string using the given algorithm and encoding
  • 🟣 function decompress() - Decompresses the given string using the given algorithm and encoding
  • 🟣 function computeHash() - Computes a string's hash using the given algorithm
  • 🟣 function randomId() - Generates a random ID of the given length
• DataStore: - Cross-platform, general-purpose, sync/async hybrid, JSON-serializable database infrastructure:
  • 🟧 class DataStore - The main class for the data store
    • 🔷 type DataStoreOptions - Options for the data store
    • 🔷 type DataMigrationsDict - Dictionary of data migration functions
  • 🟧 class DataStoreSerializer - Serializes and deserializes data for multiple DataStore instances
    • 🔷 type DataStoreSerializerOptions - Options for the DataStoreSerializer
    • 🔷 type LoadStoresDataResult - Result of calling loadStoresData()
    • 🔷 type SerializedDataStore - Meta object and serialized data of a DataStore instance
    • 🔷 type StoreFilter - Filter for selecting data stores
  • 🟧 class DataStoreEngine - Base class for DataStore storage engines, which handle the data storage
  • Storage Engines:
    • 🟧 class BrowserStorageEngine - Storage engine for browser environments (localStorage, sessionStorage)
      • 🔷 type BrowserStorageEngineOptions - Options for the browser storage engine
    • 🟧 class FileStorageEngine - File-based storage engine for Node.js and Deno
      • 🔷 type FileStorageEngineOptions - Options for the file storage engine
• Debouncer:
  • 🟣 function debounce() - Function wrapper for the Debouncer class
  • 🟧 class Debouncer - Class that manages listeners whose calls are rate-limited
    • 🔷 type DebouncerType - The triggering type for the debouncer
    • 🔷 type DebouncedFunction - Function type that is returned by the debounce() function
    • 🔷 type DebouncerEventMap - Event map type for the Debouncer class
• Errors:
  • 🟧 class DatedError - Base error class with a date property
    • 🟧 class ChecksumMismatchError - Error thrown when two checksums don't match
    • 🟧 class MigrationError - Error thrown in a failed data migration
    • 🟧 class ValidationError - Error while validating data
• Math:
  • 🟣 function bitSetHas() - Checks if a bit is set in a bitset
  • 🟣 function clamp() - Clamps a number between a given range
  • 🟣 function digitCount() - Returns the number of digits in a number
  • 🟣 function formatNumber() - Formats a number to a string using the given locale and format identifier
    • 🔷 type NumberFormat - Number format identifier
  • 🟣 function mapRange() - Maps a number from one range to another
  • 🟣 function randRange() - Returns a random number in the given range
  • 🟣 function roundFixed() - Rounds the given number to the given number of decimal places
  • 🟣 function valsWithin() - Checks if the given numbers are within a certain range of each other
• Misc:
  • 🟣 function consumeGen() - Consumes a ValueGen object
    • 🔷 type ValueGen - A value that can be either type T, or a sync or async function that returns T
  • 🟣 function consumeStringGen() - Consumes a StringGen object
    • 🔷 type StringGen - A value that can be either of type string, or a sync or async function that returns a string
  • 🟣 function fetchAdvanced() - Wrapper around fetch() with options like a timeout
    • 🔷 type FetchAdvancedOpts - Options for the fetchAdvanced() function
  • 🟣 function getListLength() - Returns the length of a ListLike object
    • 🔷 type ListLike - Any value with a quantifiable length, count or size property
  • 🟣 function pauseFor() - Pauses async execution for the given amount of time
  • 🟣 function pureObj() - Applies an object's props to a null object (object without prototype chain) or just returns a new null object
  • 🟣 function setImmediateInterval() - Like setInterval(), but instantly calls the callback and supports passing an AbortSignal
  • 🟣 function setImmediateTimeoutLoop() - Like a recursive setTimeout() loop, but instantly calls the callback and supports passing an AbortSignal
  • 🟣 function scheduleExit() - Schedules a process exit after the next event loop tick, to allow operations like IO writes to finish.
• NanoEmitter:
  • 🟧 class NanoEmitter - Simple, lightweight event emitter class that can be used in both FP and OOP, inspired by EventEmitter from node:events, based on nanoevents
    • 🔷 type NanoEmitterOptions - Options for the NanoEmitter class
• Text:
  • 🟣 function autoPlural() - Turns the given term into its plural form, depending on the given number or list length
  • 🟣 function capitalize() - Capitalizes the first letter of the given string
  • 🟣 function createProgressBar() - Creates a progress bar string with the given percentage and length
    • 🟩 const defaultPbChars - Default characters for the progress bar
    • 🔷 type ProgressBarChars - Type for the progress bar characters object
  • 🟣 function joinArrayReadable() - Joins the given array into a string, using the given separators and last separator
  • 🟣 function secsToTimeStr() - Turns the given number of seconds into a string in the format (hh:)mm:ss with intelligent zero-padding
  • 🟣 function truncStr() - Truncates the given string to the given length

• Misc. Types:
  • 🔷 type LooseUnion - A union type that allows for autocomplete suggestions as well as substitutions of the same type
  • 🔷 type ListLike - Any value with a quantifiable length, count or size property
  • 🔷 type Newable - Any class reference that can be instantiated with new
  • 🔷 type NonEmptyArray - Non-empty array type
  • 🔷 type NonEmptyString - String type with at least one character
  • 🔷 type NumberFormat - Number format identifier
  • 🔷 type Prettify - Makes the structure of a type more readable by fully expanding it (recursively)
  • 🔷 type SerializableVal - Any value that can be serialized to JSON
  • 🔷 type StringGen - A value that can be either of type string, or a sync or async function that returns a string
  • 🔷 type ValueGen - A value that can be either the generic type T, or a sync or async function that returns T
  • 🔷 type Stringifiable - Any value that can be implicitly converted to a string

Note

🟣 = function
🟧 = class
🔷 = type
🔶 = const

Installation

• If you are using Node.js or Deno, install the package from NPM or JSR via your favorite package manager:

npm i @sv443-network/coreutils
pnpm i @sv443-network/coreutils
yarn add @sv443-network/coreutils
npx jsr install @sv443-network/coreutils
deno add jsr:@sv443-network/coreutils

• If you are in a DOM environment, you can include the UMD bundle using your favorite CDN:

<script src="https://cdn.jsdelivr.net/npm/@sv443-network/coreutils@latest/dist/CoreUtils.min.umd.js"></script>
<script src="https://unpkg.com/@sv443-network/coreutils@latest/dist/CoreUtils.min.umd.js"></script>
<script src="https://esm.sh/@sv443-network/coreutils@latest/dist/CoreUtils.min.umd.js"></script>

• Then, import parts of the library as needed:

// >> EcmaScript Modules (ESM):

// - import parts of the library:
import { randomItem } from "@sv443-network/coreutils";
// - or import the full library:
import * as CoreUtils from "@sv443-network/coreutils";
// - or import raw TS files, after installing via JSR:
import { DataStore } from "jsr:@sv443-network/coreutils/lib/DataStore.ts";

// >> CommonJS (CJS):

// - import parts of the library:
const { debounce } = require("@sv443-network/coreutils");
// - or import the full library:
const CoreUtils = require("@sv443-network/coreutils");

// >> Universal Module Definition (UMD):

// - to make the global variable `CoreUtils` available, import this file:
// "@sv443-network/coreutils/dist/CoreUtils.min.umd.js"
// - or import the library on your HTML page:
// <script src="https://cdn.jsdelivr.net/npm/@sv443-network/coreutils@latest/dist/CoreUtils.min.umd.js"></script>