Goldies

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

Features

• 🌲 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

Installation

npm install goldies

Usage

Goldies supports two import styles to fit your needs:

1. Traditional namespace import (includes everything)

import goldies from 'goldies';

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

// Object utilities
const cloned = goldies.object.clone({ name: 'John' });

// String utilities
const hasPrefix = goldies.string.startsWith('Hello world', 'Hello');

2. Tree-shakable direct imports (recommended)

// Only import what you need for smaller bundle size
import { dedupe } from 'goldies/array/dedupe';
import { clone } from 'goldies/object/clone';
import { startsWith } from 'goldies/string/startsWith';

const uniqueArray = dedupe([1, 2, 2, 3]);
const cloned = clone({ name: 'John' });
const hasPrefix = startsWith('Hello world', 'Hello');

Bundle Size Comparison

Import Style	Bundle Size
Full library	~28 KB (minified)
Single function	~0.3-1 KB (minified)

Using direct imports can reduce your bundle size by up to 99% if you only need a few functions!

Available Utilities

Array

Function	Description	Import Path
dedupe	Remove duplicates from an array	goldies/array/dedupe

Color

Function	Description	Import Path
getContrast	Calculate contrast ratio between colors	goldies/color/getContrast
isValidHexSimpleColor	Validate a hex color code	goldies/color/isValidHexSimpleColor

Convert

Function	Description	Import Path
base64ToBlob	Convert base64 string to Blob	goldies/convert/base64ToBlob
fromArray	Convert array to other formats	goldies/convert/fromArray
fromBase64	Decode base64 string	goldies/convert/fromBase64
parseJSONFromBytes	Parse JSON from byte array	goldies/convert/parseJSONFromBytes
toBase64	Encode string to base64	goldies/convert/toBase64

DOM (Browser only)

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
addClass, removeClass, toggleClass	Manipulate element classes	goldies/dom/classes
domify	Create DOM elements from HTML string	goldies/dom/domify
getCustomCSSVariables	Get CSS custom properties	goldies/dom/getCustomCSSVariables
getDataAttributes	Get data attributes from element	goldies/dom/getDataAttributes

Format

Function	Description	Import Path
formatBytes	Format byte sizes (e.g., 1024 → "1 KB")	goldies/format/formatBytes

Object

Function	Description	Import Path
clone	Deep clone an object	goldies/object/clone
filter	Filter object properties	goldies/object/filter
has	Check if object has property	goldies/object/has
pick	Pick specific properties from object	goldies/object/pick

String

Function	Description	Import Path
endsWith	Check if string ends with substring	goldies/string/endsWith
findUsernames	Extract usernames from string	goldies/string/findUsernames
startsWith	Check if string starts with substring	goldies/string/startsWith

Types

Function	Description	Import Path
isDefined	Check if value is defined	goldies/types/isDefined
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
isUrl	Check if string is valid URL	goldies/types/isUrl

Utils

Function	Description	Import Path
buildQuery	Build URL query string	goldies/utils/buildQuery
escapeHTML	Escape HTML characters	goldies/utils/escapeHTML
getURLParams	Parse URL parameters	goldies/utils/getURLParams
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
s3	S3 URL utilities	goldies/utils/s3
sleep	Promise-based delay	goldies/utils/sleep

Files (Node.js only)

Function	Description	Import Path
getDirectoryTree	Generate directory structure	goldies/files/getDirectoryTree
getFileType	Determine file type	goldies/files/getFileType
isDirectory	Check if path is directory	goldies/files/isDirectory
readFile	Read file contents	goldies/files/readFile

Node (Node.js only)

Function	Description	Import Path
port	Find available network port	goldies/node/port
sh	Execute shell commands	goldies/node/sh

Library Features

• Array Utilities: Deduplication, filtering, and more
• DOM Utilities: Element selection, class manipulation, and attribute handling
• Color Utilities: Color validation and contrast calculation
• File Utilities: Directory tree generation, file type detection
• String Utilities: Pattern matching, username detection
• Type Checking: Comprehensive type checking utilities
• Object Utilities: Cloning, filtering, and property manipulation
• General Utilities: URL parsing, query string building, and more

TypeScript Support

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

Development

# 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

Contributing

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

License

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

Author

• Matthew Hudson (@matthewhudson)
• Website: hudson.dev