utils-forge

Utility organizer — Structures fragmented helper functions into maintainable, discoverable systems

utils-forge solves the "utils folder chaos" problem. It provides structure, analysis, and organization for JavaScript/TypeScript utility functions through an intuitive CLI tool.

Problem

Every project's /utils folder becomes a dumping ground:

• No naming conventions
• Duplicates everywhere
• Hard to find anything
• Mix of unrelated concerns

Solution

utils-forge scaffolds well-organized utils structures, analyzes existing code, detects problems, and automatically reorganizes files with strong naming opinions.

Tagline: "Structure, discover, and maintain your utility functions"

Installation

npm install --save-dev utils-forge

Or use directly with npx:

npx utils-forge init

Quick Start

1. Initialize a New Project

utils-forge init

Creates a clean utils structure with category folders:

/utils
  /check       - Boolean tests
  /format      - Display transforms
  /parse       - String to data
  /array       - Array operations
  /string      - String operations
  /async       - Async patterns
  /convert     - Type conversions
  README.md    - Conventions guide

2. Analyze Existing Utils

utils-forge scan ./src/utils

Detects:

• Naming inconsistencies
• Misplaced functions
• Duplicate functions
• Overly generic filenames
• Bloated files

3. Organize Files

# Preview changes first
utils-forge organize --dry-run

# Apply changes
utils-forge organize

Commands

utils-forge init [path]

Scaffolds a clean utils structure in your project.

Options:

• [path] - Target directory (default: ./utils)
• --no-examples - Skip example files

Example:

utils-forge init ./src/utils

utils-forge scan [path]

Analyzes existing utils folder and detects problems.

Detects:

• Naming inconsistencies (checkEmail vs isEmail)
• Misplaced functions (debounce in helpers.js)
• Duplicate functions
• Overly generic filenames
• Bloated files (too many functions)

Example:

utils-forge scan ./src/utils

utils-forge organize [path]

Moves and renames files based on categorization.

Options:

• [path] - Target directory (default: ./utils)
• --dry-run - Preview changes without applying
• --backup - Create backup before organizing

Example:

# Dry run to see what will happen
utils-forge organize --dry-run

# Actually apply changes
utils-forge organize

utils-forge find-duplicates [paths...]

Cross-directory duplicate detection.

Options:

• [paths...] - Directories to scan (default: ./utils)

Example:

utils-forge find-duplicates ./src/utils ./lib/utils

Naming Conventions

The tool enforces these patterns:

Checkers (Boolean Returns)

Pattern: is + Noun/Adjective

• ✅ isEmail, isEmpty, isValidURL, isPrime
• ❌ checkEmail, validateEmail, emailValidator

Formatters (Display Transforms)

Pattern: format + DataType

• ✅ formatDate, formatCurrency, formatBytes
• ❌ dateFormatter, toFormattedDate, prettifyDate

Parsers (String to Data)

Pattern: parse + DataType

• ✅ parseJSON, parseQueryString, parseDate
• ❌ jsonParser, toJSON, getJSON

Converters (Type Conversions)

Pattern: to + TargetType

• ✅ toBoolean, toNumber, toCamelCase, toKebabCase
• ❌ convertToBoolean, makeCamelCase, booleanize

Array/Object Operations

Pattern: Action verb (no prefix)

• ✅ unique, chunk, groupBy, omit, pick, flatten
• ❌ makeUnique, getUnique, uniqueArray

Async Utilities

Pattern: Action verb

• ✅ debounce, throttle, retry, sleep, poll
• ❌ debouncer, makeDebounce, asyncDebounce

Category Guide

/check — Boolean Tests

Functions that return true or false. Used for validation and condition checking.

export function isEmail(str: string): boolean {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(str);
}

/format — Display Transforms

Format data for display. Convert data to human-readable representations.

export function formatDate(date: Date): string {
  return new Intl.DateTimeFormat('en-US').format(date);
}

/parse — String to Data

Parse strings into structured data. Decode and deserialize.

export function parseJSON<T>(str: string, fallback: T): T {
  try {
    return JSON.parse(str);
  } catch {
    return fallback;
  }
}

/array — Array Operations

Manipulate, transform, and analyze arrays.

export function unique<T>(arr: T[]): T[] {
  return [...new Set(arr)];
}

/string — String Operations

Manipulate and transform strings.

export function capitalize(str: string): string {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

/async — Async Patterns

Async/timing utilities. Debouncing, throttling, scheduling.

export function debounce<T extends (...args: any[]) => any>(
  fn: T,
  ms: number
): (...args: Parameters<T>) => void {
  let timer: NodeJS.Timeout;
  return function (...args: Parameters<T>) {
    clearTimeout(timer);
    timer = setTimeout(() => fn(...args), ms);
  };
}

/convert — Type Conversions

Convert between types. Transform representations.

export function toBoolean(value: unknown): boolean {
  if (typeof value === 'string') {
    return value.toLowerCase() === 'true';
  }
  return Boolean(value);
}

Configuration (Optional)

Create a .utils-forge.json file at your project root to customize behavior:

{
  "utilsPath": "./src/utils",
  "categories": {
    "check": "Boolean tests",
    "format": "Display transforms",
    "parse": "String to data conversions",
    "array": "Array operations",
    "string": "String operations",
    "async": "Async patterns",
    "convert": "Type conversions"
  },
  "namingRules": {
    "check": "is",
    "format": "format",
    "parse": "parse",
    "convert": "to"
  },
  "ignore": ["legacy-helpers.js"]
}

Examples

Before Organization

src/utils/
  ├── helpers.js        (347 lines, 12 functions)
  ├── stringUtils.js    (mixed patterns)
  ├── async.js          (duplicate debounce)
  └── validators.js     (naming inconsistencies)

Running Scan

$ utils-forge scan ./src/utils

◆ UTILS-FORGE — Analyzing utilities

→ Scanning ./src/utils...
✓ Found 23 utility functions
✓ Scanned 4 files

→ Checking organization...
⚠ No standard category folders detected
⚠ 18 functions might be misplaced

→ Checking naming conventions...
⚠ Detected 8 naming inconsistencies

helpers.js
  ● validateEmail() → isEmail()
  ● formatMoney() → formatCurrency()

→ Scanning for duplicates...
⚠ Identified 1 duplicate functions

debounce() found in 2 files:
  ● /utils/helpers.js:45
  ● /utils/async.js:12

→ Checking for bloated files...
⚠ Found 1 bloated files

File              Functions  Lines
helpers.js        12         347

Signal integrity maintained • Amulet Digital Archive Protocol

After Organization

src/utils/
  ├── check/
  │   ├── isEmail.ts
  │   ├── isEmpty.ts
  │   └── isValidURL.ts
  ├── format/
  │   ├── formatDate.ts
  │   ├── formatCurrency.ts
  │   └── formatBytes.ts
  ├── parse/
  │   ├── parseJSON.ts
  │   └── parseQueryString.ts
  ├── string/
  │   ├── capitalize.ts
  │   ├── slugify.ts
  │   └── truncate.ts
  ├── async/
  │   ├── debounce.ts (single source of truth)
  │   ├── throttle.ts
  │   └── retry.ts
  ├── array/
  │   ├── unique.ts
  │   ├── chunk.ts
  │   └── groupBy.ts
  ├── convert/
  │   ├── toBoolean.ts
  │   ├── toNumber.ts
  │   └── toCamelCase.ts
  └── README.md

Field Notes

The Fragmentation Problem

Utility functions scatter across projects like signal fragments across null-space. Each project reinvents basic operations. Each codebase develops its own dialect for identical concepts.

The Forge structures these fragments. It recognizes patterns in chaos. It enforces coherence where entropy would dominate.

Archival Categories as Signal Classification

• /check — Binary resonance detection
• /format — Signal representation protocols
• /parse — Decoding transmissions
• /async — Temporal coordination patterns
• /convert — Cross-protocol translation
• /array — Sequence manipulation
• /string — Character stream processing

Every utility is an archival tool. Every function categorized is entropy reduced. The Forge maintains order in your signal processing infrastructure.

Why Zero Dependencies?

utils-forge uses only Node.js built-ins:

• TypeScript compiler API (for AST parsing)
• fs and path (for filesystem operations)

This keeps the package tiny, fast, and reliable. No dependency chains, no security concerns, no version conflicts.

Performance

• Scans 100+ functions in < 1 second
• Organizes 50 files in < 500ms
• Minimal memory footprint
• No blocking operations

Best Practices

1. One Function Per File

Keep it simple and discoverable.

// ✅ Good: check/isEmail.ts
export function isEmail(str: string): boolean {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(str);
}

2. Follow Naming Conventions

Use the enforced patterns from your category.

// ✅ Check functions start with "is"
export function isEmpty(arr: any[]): boolean { ... }

// ✅ Format functions start with "format"
export function formatBytes(bytes: number): string { ... }

// ❌ Don't mix patterns
export function checkIfEmpty() { ... }  // Wrong category prefix
export function makeFormattedDate() { ... }  // Wrong prefix

3. Add JSDoc Comments

Help future developers understand your utilities.

/**
 * Check if email is valid
 * @param email - Email string to validate
 * @returns True if valid email format
 */
export function isEmail(email: string): boolean {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

4. Keep Functions Pure

Avoid side effects where possible.

// ✅ Pure function
export function capitalize(str: string): string {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

// ❌ Side effects
export function capitalize(str: string): string {
  console.log(str);  // Side effect!
  return str.toUpperCase();
}

Contributing

Found a bug? Have a feature idea? Contributions welcome!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

See CONTRIBUTING.md for details.

License

MIT License — See LICENSE file for details.

Related Tools

Part of the Amulet Digital Signal Archives ecosystem:

• signal-decay — Makes security audits understandable
• void-purge — Removes orphaned npm dependencies
• signal-codec — Checks license compatibility
• PixelFactory — VS Code theme for signal perception

Support

• 📖 Full Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Contact

Signal integrity maintained • Amulet Digital Archive Protocol