goldies
    Preparing search index...

    goldies

    Goldies

    A wide-ranging collection of JavaScript helpers covering debugging, serialization, sanitization, validation, HTTP requests and more.

    npm version npm downloads Bundle size License: MIT TypeScript Node.js: v22 CI

    API reference · Live demo

    • 🌲 Tree-shakable: Import only what you need
    • 🔄 Multiple formats: ESM, CommonJS, and UMD bundles
    • 📦 Environment-aware: Browser and Node.js specific utilities
    • 📊 Type-safe: Full TypeScript support with type definitions
    • 🧩 Modular: Use individual functions or the full library
    npm install goldies

    Goldies supports two import styles to fit your needs:

    import goldies from 'goldies';

    // Array utilities
    const uniqueArray = goldies.array.dedupe([1, 2, 2, 3]);

    // Object utilities
    const picked = goldies.object.pick({ name: 'John', age: 30 }, ['name']);

    // Color utilities
    const ratio = goldies.color.getContrastRatio('#777777', '#ffffff'); // 4.48

    CommonJS works too:

    const goldies = require('goldies');

    // Only import what you need for smaller bundle size
    import { dedupe } from 'goldies/array/dedupe';
    import { pick } from 'goldies/object/pick';
    import { getContrastRatio } from 'goldies/color/getContrastRatio';

    const uniqueArray = dedupe([1, 2, 2, 3]);
    const picked = pick({ name: 'John', age: 30 }, ['name']);
    const ratio = getContrastRatio('#777777', '#ffffff');

    Direct imports work with require too: const { dedupe } = require('goldies/array/dedupe');

    Import Style Bundle Size
    Full library (browser) ~8 KB minified, ~3.5 KB gzipped
    Single function ~0.1-0.8 KB minified

    With direct imports, your bundle only includes the functions you use.

    Function Description Import Path
    chunk Split an array into chunks of a given size goldies/array/chunk
    dedupe Remove duplicates from an array goldies/array/dedupe
    Function Description Import Path
    calculateRelativeLuminance WCAG relative luminance of a hex color, from 0 to 1 goldies/color/calculateRelativeLuminance
    generateRandomHexColor Random hex color goldies/color/generateRandomHexColor
    generateRandomHexColorInRange Random hex color between two colors, channel by channel goldies/color/generateRandomHexColorInRange
    getContrastColor Pick black or white text for a background color goldies/color/getContrastColor
    getContrastRatio WCAG contrast ratio between two colors, from 1 to 21 goldies/color/getContrastRatio
    hexToRgb Convert a 3- or 6-digit hex color to { r, g, b } goldies/color/hexToRgb
    isValidHexColor Validate a 6-digit hex color (#rrggbb) goldies/color/isValidHexColor
    Function Description Import Path
    base64ToBlob Convert base64 string to Blob goldies/convert/base64ToBlob
    fromBase64 Decode base64 string goldies/convert/fromBase64
    parseJSONFromBytes Parse JSON from byte array goldies/convert/parseJSONFromBytes
    toBase64 Encode string to base64 goldies/convert/toBase64
    Function Description Import Path
    $ Query selector (similar to jQuery) goldies/dom/selectors
    $$ Query selector all (similar to jQuery) goldies/dom/selectors
    attr Get/set element attributes goldies/dom/attr
    domify Create DOM elements from HTML string goldies/dom/domify
    getCustomCSSVariables Get CSS custom properties goldies/dom/getCustomCSSVariables
    Function Description Import Path
    formatBytes Format byte sizes (e.g., 1024 → "1 KB") goldies/format/formatBytes
    Function Description Import Path
    filter Filter object properties goldies/object/filter
    omit Copy an object without the given properties goldies/object/omit
    pick Pick specific properties from object goldies/object/pick
    Function Description Import Path
    findUsernames Extract usernames from string goldies/string/findUsernames
    Function Description Import Path
    isDefined Check if value is defined goldies/types/isDefined
    isExternalUrl Check if a string is a URL on a different host than the current page goldies/types/isExternalUrl
    isJSON Check if string is valid JSON goldies/types/isJSON
    isNil Check if value is null or undefined goldies/types/isNil
    isNull Check if value is null goldies/types/isNull
    isUndefined Check if value is undefined goldies/types/isUndefined
    Function Description Import Path
    debounce Call a function once calls stop for a while goldies/utils/debounce
    escapeHTML Escape HTML characters goldies/utils/escapeHTML
    isBrowser Check if code runs in browser goldies/utils/isBrowser
    isServer Check if code runs on server goldies/utils/isServer
    reloadPageWhenOnline Auto-reload page when back online goldies/utils/reloadPageWhenOnline
    retry Retry a function with exponential backoff, cancellable with an AbortSignal goldies/utils/retry
    s3 S3 URL utilities goldies/utils/s3
    sleep Promise-based delay goldies/utils/sleep
    throttle Call a function at most once per interval goldies/utils/throttle
    Function Description Import Path
    getFileType Determine file type goldies/files/getFileType
    isDirectory Check if path is directory goldies/files/isDirectory
    Function Description Import Path
    port Find available network port goldies/node/port
    sh Execute shell commands goldies/node/sh

    These still work in 5.x, but JavaScript and Node.js now do the same job. Editors show them crossed out.

    Function Use instead
    addClass, hasClass, removeClass, toggleClass element.classList.add, .contains, .remove, .toggle
    buildQuery new URLSearchParams(data).toString()
    clone structuredClone(obj), which doesn't freeze the copy
    endsWith str.toLowerCase().endsWith(ends.toLowerCase())
    fromArray String(arr)
    getDataAttributes element.dataset
    getDirectoryTree readdirSync(dir, { recursive: true, withFileTypes: true }) from node:fs
    getURLParams Object.fromEntries(new URL(url).searchParams)
    has Object.hasOwn(target, key)
    isUrl isExternalUrl (same function, new name)
    readFile readFile(path, 'utf8') from node:fs/promises
    startsWith str.toLowerCase().startsWith(prefix.toLowerCase())
    • Array Utilities: Deduplication and chunking
    • DOM Utilities: Element selection, attributes, HTML parsing, and CSS variables
    • Color Utilities: Validation, conversion, WCAG contrast and random colors
    • File Utilities: File type detection and directory checks
    • String Utilities: Username detection
    • Type Checking: Comprehensive type checking utilities
    • Object Utilities: Picking, omitting, and filtering properties
    • General Utilities: Debounce, throttle, retry with backoff, HTML escaping, S3 paths, and more

    This package is written in TypeScript and includes type definitions. You get full type safety and autocompletion when using it in TypeScript projects.

    # Install dependencies
    npm install

    # Run tests
    npm test

    # Build the package
    npm run build

    # Lint the code
    npm run lint

    # Format the code
    npm run format

    Contributions are welcome! Please feel free to submit a Pull Request.

    1. Fork the repository
    2. Create your feature branch (git checkout -b feature/amazing-feature)
    3. Commit your changes (git commit -m 'Add some amazing feature')
    4. Push to the branch (git push origin feature/amazing-feature)
    5. Open a Pull Request

    This project is licensed under the MIT License - see the LICENSE file for details.

    Settings
    Member Visibility

    On This Page
    Goldies