puffy-core

v1.3.2

Published

17 days ago

A collection of ES6 modules with zero-dependencies to help manage common programming tasks in both NodeJS or native JS.

Downloads

512

0High
0Medium
0Low

neapnic

Puffy Core

A collection of ES6 modules with zero dependencies to help manage common programming tasks in both Node.js and native JavaScript.

Using an AI assistant? This project provides LLM-optimized documentation. Give your AI one of the links below and it will figure out the rest.
| Module | LLM Doc | |---|---| | All modules (start here) | https://raw.githubusercontent.com/nicolasdao/puffy-core/master/llms.txt | | error — catchErrors, wrapErrors, PuffyResponse | https://raw.githubusercontent.com/nicolasdao/puffy-core/master/llms/error.txt | | func — chainAsync, chainSync | https://raw.githubusercontent.com/nicolasdao/puffy-core/master/llms/func.txt | | collection — batch, uniq, sortBy, flatten | https://raw.githubusercontent.com/nicolasdao/puffy-core/master/llms/collection.txt | | obj — merge, diff, same, getProperty | https://raw.githubusercontent.com/nicolasdao/puffy-core/master/llms/obj.txt | | converter — toNumber, toBoolean, case conversion | https://raw.githubusercontent.com/nicolasdao/puffy-core/master/llms/converter.txt | | crypto — encoder, jwtDecode | https://raw.githubusercontent.com/nicolasdao/puffy-core/master/llms/crypto.txt | | date — formatDate, addDays, getTimeDiff, toTz | https://raw.githubusercontent.com/nicolasdao/puffy-core/master/llms/date.txt | | math — avg, median, percentile, getRandomNumber | https://raw.githubusercontent.com/nicolasdao/puffy-core/master/llms/math.txt | | string — plural, justifyLeft, safeStringify | https://raw.githubusercontent.com/nicolasdao/puffy-core/master/llms/string.txt | | db — newId (BigInt) | https://raw.githubusercontent.com/nicolasdao/puffy-core/master/llms/db.txt | | time — delay, Timer | https://raw.githubusercontent.com/nicolasdao/puffy-core/master/llms/time.txt | | logger — log | https://raw.githubusercontent.com/nicolasdao/puffy-core/master/llms/logger.txt | | url — getUrlParts | https://raw.githubusercontent.com/nicolasdao/puffy-core/master/llms/url.txt | | validate — validateUrl, validateEmail | https://raw.githubusercontent.com/nicolasdao/puffy-core/master/llms/validate.txt |

Note:
Requires Node.js >= 13. For Node.js 12, use the --experimental-modules flag.
As of v1.3.0, all APIs are available in both camelCase and snake_case (e.g., newId() and new_id()).

Overview

Puffy Core provides 14 utility modules covering collections, data conversion, cryptography, dates, database IDs, error handling, functional programming, logging, math, objects, strings, time, URLs, and validation. All modules have zero external dependencies and support both ES Modules (import/export) and CommonJS (require) via the exports and main fields in package.json.

Getting Started

Installation

npm i puffy-core

Import Patterns

ES Modules -- import individual functions from specific modules:

import { batch, uniq, sortBy } from 'puffy-core/collection'
import { catchErrors, wrapErrors } from 'puffy-core/error'
import { newId } from 'puffy-core/db'

CommonJS -- destructure from the main entry point:

const { collection, error, db } = require('puffy-core')

collection.batch([1,2,3,4,5], 2) // [[1,2], [3,4], [5]]
error.catchErrors(() => riskyOperation())
db.newId() // 1737111960607002926n

Modules at a Glance

| Module | Import Path | Key Functions | Description | |---|---|---|---| | collection | puffy-core/collection | batch, uniq, sortBy, flatten, flattenUniq, seed, headTail, levelUp | Array utilities: batching, deduplication, sorting, flattening | | converter | puffy-core/converter | addZero, nbrToCurrency, s2cCase, c2sCase, objectC2Scase, objectS2Ccase, toNumber, toBoolean, toObj, toArray | Type conversion, case conversion, currency formatting | | crypto | puffy-core/crypto | encoder, jwtDecode | Encoding (base64, hex, bin, buffer) and JWT decoding | | date | puffy-core/date | addDays, addMonths, addYears, formatDate, getTimeDiff, toTz | Date arithmetic, formatting, timezone conversion | | db | puffy-core/db | newId | Monotonically increasing BigInt ID generation | | error | puffy-core/error | catchErrors, wrapErrors, wrapErrorsFn, wrapCustomErrors, mergeErrors, getErrorMetadata, required | Functional error handling with [errors, data] tuples | | func | puffy-core/func | chainAsync, chainSync | Function chaining with automatic error propagation | | logger | puffy-core/logger | log | Structured JSON logging | | math | puffy-core/math | avg, stdDev, median, percentile, getRandomNumber, getRandomNumbers | Statistics and random number generation | | obj | puffy-core/obj | merge, diff, same, exists, isEmpty, getType, setProperty, getProperty, extractFlattenedJSON | Deep merge, diff, equality, nested property access | | string | puffy-core/string | plural, justifyLeft, safeStringify | Pluralization, text alignment, BigInt-safe JSON | | time | puffy-core/time | delay, Timer | Cancellable delays and time measurement | | url | puffy-core/url | getUrlParts | URL parsing with extra convenience properties | | validate | puffy-core/validate | validateUrl, validateEmail, validateDate, validateSpecialChar | Input validation for URLs, emails, dates, special chars |

Project Structure

puffy-core/
├── src/                  # ES6 module source files
│   ├── index.mjs         # Re-exports all modules as namespaces
│   ├── collection.mjs    # Array utilities
│   ├── converter.mjs     # Type and case converters
│   ├── crypto.mjs        # Encoding and JWT
│   ├── date.mjs          # Date arithmetic and formatting
│   ├── db.mjs            # BigInt ID generation
│   ├── error.mjs         # Functional error handling (PuffyResponse)
│   ├── func.mjs          # Function chaining (depends on error.mjs)
│   ├── logger.mjs        # Structured logging (depends on string.mjs)
│   ├── math.mjs          # Statistics and random numbers
│   ├── obj.mjs           # Object utilities
│   ├── string.mjs        # String utilities
│   ├── time.mjs          # Delays and timers
│   ├── url.mjs           # URL parsing
│   └── validate.mjs      # Input validation
├── dist/                 # Rollup-compiled CommonJS output
├── test/                 # Mocha test files (one per module)
├── index.mjs             # Dev/example entry point
├── rollup.config.js      # Rollup config: src/**/*.mjs -> dist/*.cjs
└── package.json          # Dual ESM/CJS exports

Most modules are fully standalone. Only two internal dependencies exist:

func.mjs imports from error.mjs
logger.mjs imports from string.mjs

Documentation

| Document | Description | |---|---| | API Reference | Complete reference for all 14 modules with function signatures and usage examples | | Error Handling Guide | In-depth guide to the PuffyResponse pattern, catchErrors, error wrapping, chaining, and partial-success responses | | LLM System Prompts | Premade system prompts for coding agents to learn puffy-core's error handling APIs | | Gotchas | Index of non-obvious behavior and pitfalls, organized by domain |

Dev

Building

Compile ES6 modules to CommonJS:

npm run build

This uses Rollup to compile src/**/*.mjs to .cjs files in the dist/ directory.

Linting

npm run lint

Testing

npm test

Runs Mocha tests from the test/ directory.

Releasing

npm run rls -- <major|minor|patch>
npm run push

Uses standard-version for changelog generation and version bumping, then builds, pushes, and publishes to npm.

Creating URLs with the URL Object

The URL is a native object supported in both browser and Node.js environments:

const u = new URL('https://example.com')
u.pathname = 'blog'
u.searchParams.set('hello', 'world')
u.hash = 'footer'
console.log(u.toString()) // 'https://example.com/blog?hello=world#footer'

License

BSD 3-Clause License

See LICENSE for the full text.