dbl-utils

dbl-utils is a JavaScript/TypeScript utility library designed to simplify common application development tasks. This collection includes functions for event handling, queue processing, text manipulation, and date and currency formatting, among others.

Table of Contents

• Installation
• Usage
• Main Modules
• Utilities
• Documentation
• License

Installation

You can install dbl-utils via npm:

npm install dbl-utils
Copy

Or using yarn:

yarn add dbl-utils
Copy

Usage

Import the modules and functions in your project as needed. Below is a basic example of how to use dbl-utils:

// Import individual functions
import { formatCurrency, flatten, t } from 'dbl-utils';
// Use functions
console.log(formatCurrency(1234.56)); // Example of currency formatting
console.log(flatten({ a: { b: { c: 1 } } })); // Converts a nested object into a flat object
Copy

Minimal example of the CLI logic for CSS purging:

import purgeCss from 'dbl-utils/src/purge-css';
purgeCss('styles.css', 'index.html', 'clean.css');
Copy

Imports directly from any file to don't include all:

CommonJS use /dist/cjs/*

// Import individual functions
const i18n = require('dbl-utils/dist/cjs/i18n');
// Use functions
console.log(i18n.formatCurrency(1234.56));
Copy

ESM use /dist/esm/*

// Import individual functions
import t, { formatCurrency } from 'dbl-utils/dist/esm/i18n';
// Use functions
console.log(i18n.formatCurrency(1234.56));
Copy

TypeScript use /src/*

// Import individual functions
import t, { formatCurrency } from 'dbl-utils/src/i18n';
// Use functions
console.log(i18n.formatCurrency(1234.56));
Copy

For a complete reference of all available functions, visit the full documentation here.

Main Modules

Below are the main modules available in dbl-utils:

• event-handler
• fetch-queue
• flat
• format-value
• i18n
• object-mutation
• resolve-refs
• utils

Utilities

event-handler

Decouple communication by subscribing to and dispatching custom events.

import { EventHandler } from 'dbl-utils';

const handler = new EventHandler();
handler.subscribe('ping', msg => console.log(msg), 'id'); // listen to events
await handler.dispatch('ping', 'pong'); // emit an event
handler.unsubscribe('ping', 'id'); // stop listening
Copy

fetch-queue

Deduplicate concurrent HTTP calls so the same request is only made once.

import FetchQueue from 'dbl-utils/src/fetch-queue';

const queue = new FetchQueue(fetch);
const [a, b] = await Promise.all([
  queue.addRequest('https://example.com'),
  queue.addRequest('https://example.com')
]);
// a === b
Copy

flat

Convert nested objects to and from dot notation.

import { flatten, unflatten } from 'dbl-utils';

flatten({ a: { b: 1 } }); // { 'a.b': 1 }
unflatten({ 'a.b': 1 }); // { a: { b: 1 } }
Copy

format-value

Format numbers, dates, or dictionary entries using locale-aware helpers.

import formatValue from 'dbl-utils/src/format-value';

formatValue(1000, { format: 'currency', currency: 'USD' }); // "$1,000.00"
Copy

i18n

Manage dictionaries and locale-aware formatting.

import t, { addDictionary, setLang, formatDate } from 'dbl-utils';

addDictionary({ es: { hello: 'Hola' } });
setLang('es');
t('hello'); // 'Hola'
formatDate(); // date formatted in Spanish
Copy

object-mutation

Combine and transform objects without modifying the originals.

import { deepMerge, mergeWithMutation, transformJson } from 'dbl-utils';

deepMerge({}, { a: 1 }, { b: 2 }); // merge nested structures
await mergeWithMutation({ a: { b: 1 } }, { mutation: () => ({ c: 2 }) }); // async mutation
transformJson({ a: { b: 1 } }, { filter: 'a' }); // extract subset
Copy

resolve-refs

Advanced reference resolution system for dynamic object composition and template inheritance. Perfect for configuration management, content templating, and complex data transformations.

Core Features

• 🌐 Global References: Access any value in your data schema
• 🔗 Relative References: Reference values within the current object context
• 📝 String Interpolation: Embed references within strings seamlessly
• 🎨 Template Inheritance: Create reusable object templates with property overrides
• ⚙️ Custom Rules & Tasks: Define advanced transformation logic
• 🔄 Recursive Resolution: Handle complex nested reference chains

Reference Types

1. Global References

const config = { api: { url: "https://api.com", key: "secret" } };
const settings = {
  endpoint: "$api/url",           // Direct reference → "https://api.com"
  auth: "Bearer ${api/key}",      // String interpolation → "Bearer secret"
  full: "${api/url}/v1/users"     // Mixed interpolation → "https://api.com/v1/users"
};
Copy

2. Template Inheritance

const data = {
  // Base template
  userTemplate: { name: "Guest", role: "viewer", active: false },
  
  // Inherit and override properties
  admin: { ref: "$userTemplate", name: "Admin", role: "admin", active: true },
  john: { ref: "$userTemplate", name: "John Doe" }
};

const result = resolveRefs(data);
// result.admin = { name: "Admin", role: "admin", active: true }
// result.john = { name: "John Doe", role: "viewer", active: false }
Copy

3. Relative References with Template System

const data = {
  user1: { ref: "$templates/user", firstName: "Alice", lastName: "Smith" },
  user2: { ref: "$templates/user", firstName: "Bob", lastName: "Jones" },
  
  templates: {
    user: {
      firstName: "",
      lastName: "",
      ".": {
        // These resolve AFTER template merging
        fullName: "${./firstName} ${./lastName}",           // Relative interpolation
        email: "${./firstName}.${./lastName}@company.com",  // Complex relative refs
        profile: {
          displayName: "$./fullName",    // Reference to another relative ref
          initials: "${./firstName/0}${./lastName/0}"  // Access array/string indices
        }
      }
    }
  }
};

const result = resolveRefs(data);
// result.user1.fullName = "Alice Smith"
// result.user1.email = "Alice.Smith@company.com"  
// result.user1.profile.displayName = "Alice Smith"
// result.user1.profile.initials = "AS"
Copy

Advanced Usage

Configuration Management

const config = {
  // Environment settings
  env: { 
    name: "production",
    domain: "myapp.com",
    apiVersion: "v2"
  },
  
  // Service definitions using templates
  services: {
    auth: { ref: "$templates/service", path: "/auth", timeout: 5000 },
    users: { ref: "$templates/service", path: "/users", port: 8080 },
    payments: { ref: "$templates/service", path: "/payments", ssl: true }
  },
  
  templates: {
    service: {
      path: "/",
      port: 3000,
      timeout: 30000,
      ssl: false,
      ".": {
        // Dynamic URL generation
        baseUrl: "http${./ssl ? 's' : ''}://${env/domain}:${./port}",
        fullUrl: "${./baseUrl}/${env/apiVersion}${./path}",
        
        // Service configuration
        config: {
          endpoint: "$./fullUrl",
          timeout: "$./timeout",
          retries: 3,
          headers: {
            "X-Service-Name": "${env/name}",
            "X-API-Version": "${env/apiVersion}"
          }
        }
      }
    }
  }
};

const result = resolveRefs(config);
// result.services.auth.fullUrl = "http://myapp.com:3000/v2/auth"
// result.services.users.fullUrl = "http://myapp.com:8080/v2/users"
// result.services.payments.fullUrl = "https://myapp.com:3000/v2/payments"
Copy

Custom Rules and Tasks

const data = {
  users: ["Alice", "Bob", "Charlie"],
  products: [{ name: "Widget", price: 10 }, { name: "Gadget", price: 25 }]
};

const template = {
  welcomeMessage: "$greetUsers",
  productSummary: "$summarizeProducts",
  totalValue: "$calculateTotal"
};

// Define custom processing rules
const rules = {
  "$greetUsers": ["join", "$users", " and "],
  "$summarizeProducts": ["iterate", "$products", "product"],
  "$calculateTotal": ["sum", "$products", "price"]
};

// Custom task implementations
const extraTasks = {
  sum: (array: any[], property: string) => 
    array.reduce((total, item) => total + item[property], 0),
  
  format: (template: string, ...values: any[]) =>
    template.replace(/{(\d+)}/g, (_, i) => values[i]),
    
  conditional: (condition: boolean, trueVal: any, falseVal: any) =>
    condition ? trueVal : falseVal
};

const result = resolveRefs(template, data, rules, extraTasks);
// result.welcomeMessage = "Alice and Bob and Charlie"
// result.totalValue = 35
Copy

Built-in Tasks

• iterate(array, itemName) - Process array items with current schema context
• join(values, separator, ...extras) - Join arrays or concatenate values
• ignore(path, fallback) - Safe property access with fallback values
• if(condition, trueValue, falseValue) - Conditional value resolution

API Reference

resolveRefs<T>(
  object: ResolvableValue,      // Object/array with references to resolve
  schema?: Record<string, any>, // Base schema for global references
  rules?: ResolveRefsRules,     // Custom rule definitions
  extraTasks?: ResolveRefsTasks // Additional task implementations
): T
Copy

Best Practices

1. 🏗️ Structure: Organize templates in dedicated sections (e.g., templates/, definitions/)
2. 📋 Naming: Use descriptive paths like config/database/url over abbreviated versions
3. 🎯 Performance: Avoid deep circular references and excessive nesting
4. 🔒 Type Safety: Define TypeScript interfaces for your schema structure
5. 🧪 Testing: Test complex reference chains with various data combinations

Real-World Examples

For comprehensive examples and advanced use cases, see the detailed examples documentation.

• Multi-environment Configuration: Different API endpoints per environment
• Component Templates: Reusable UI component configurations
• Dynamic Content: Blog posts with shared metadata and custom overrides
• API Documentation: Auto-generated endpoint documentation from templates
• Feature Flags: Conditional configuration based on environment/user settings

utils

sliceIntoChunks

Split an array into smaller arrays for batching.

import { sliceIntoChunks } from 'dbl-utils';
sliceIntoChunks([1,2,3,4],2); // [[1,2],[3,4]]
Copy

splitAndFlat

Turn a list of strings into unique tokens.

import { splitAndFlat } from 'dbl-utils';
splitAndFlat(['a b','c']); // ['a','b','c']
Copy

generateRandomColors

Generate distinct colors for visualizations.

import { generateRandomColors } from 'dbl-utils';
generateRandomColors(2); // ['#aabbcc', '#ddeeff']
Copy

evaluateColorSimilarity

Check how close colors are to each other.

import { evaluateColorSimilarity } from 'dbl-utils';
evaluateColorSimilarity(['#fff','#ffe']); // value near 1
Copy

normalize

Remove accents and lowercase text.

import { normalize } from 'dbl-utils';
normalize('á'); // 'a'
Copy

slugify

Create URL-friendly slugs.

import { slugify } from 'dbl-utils';
slugify('Hello World'); // 'hello-world'
Copy

randomS4

Produce a short hex segment.

import { randomS4 } from 'dbl-utils';
randomS4(); // '9f3b'
Copy

randomString

Generate a random alphanumeric string.

import { randomString } from 'dbl-utils';
randomString(5); // e.g., 'abcde'
Copy

timeChunks

Build time intervals between two dates.

import { timeChunks } from 'dbl-utils';
timeChunks({ from:'2020-01-01', to:'2020-01-02', step:3600 }); // [...]
Copy

delay

Pause execution for a given time.

import { delay } from 'dbl-utils';
await delay(10); // waits 10ms
Copy

hash

Generate a numeric hash.

import { hash } from 'dbl-utils';
hash('data'); // 123456789
Copy

LCG

Deterministic pseudo-random number generator.

import { LCG } from 'dbl-utils';
const gen = new LCG(123);
gen.random(); // 0.5967...
Copy

Documentation

For a detailed description of each module and function, visit the full documentation automatically generated with Typedoc. The documentation includes usage examples and in-depth explanations of each function.

For an in-depth analysis of the project architecture, codebase structure, and implementation details, check out the comprehensive DeepWiki analysis.

Testing

Run the test suite with:

npm test
Copy

This project uses Jest with ts-jest. New tests cover the i18n and object-mutation modules.

Recent Changes

• Comprehensive resolve-refs documentation: Completely redesigned documentation with:
  • Enhanced JSDoc comments with detailed examples and use cases
  • Full TypeScript type definitions and interfaces
  • Comprehensive README section with visual examples
  • Real-world usage examples including configuration management, API documentation, and component systems
  • Advanced examples covering feature flags, e-commerce catalogs, and multi-environment setups
• Enhanced resolve-refs module: Added support for relative references with $./ and ${./} syntax
  • New template system using the "." key for relative references
  • Ability to create reusable templates that can be extended with different values
  • Support for references that point to other references (recursive resolution)
  • Comprehensive unit tests covering all relative reference scenarios
• Fixed handling of numeric keys in unflatten so arrays are reconstructed correctly.
• Added unit tests for the i18n and object-mutation modules.
• Expanded coverage with additional tests for utils, format-value, and i18n.

TODO

• Move number compact formatting to the i18n module.

Development & Testing

When developing or debugging tests, use yarn test -- <pattern> to run only the relevant test cases.

License

This project is under the ISC license. See the LICENSE file for more details.