@buildeross/utils

Comprehensive utility library for BuilderOSS applications, providing helper functions for blockchain operations, data formatting, validation schemas, and common development tasks.

Installation

pnpm install @buildeross/utils

Features

Address Utilities: Wallet address formatting and validation
Number Formatting: Crypto value formatting with BigNumber precision
String Processing: Slugification, sanitization, and text utilities
Date & Time: Duration handling and blockchain date parsing
Validation Schemas: Yup schemas for common blockchain data types
Wagmi Integration: Chain configurations and server-side utilities
Data Helpers: Object manipulation, comparison, and array utilities
ENS Support: Ethereum Name Service utilities
Testing: Comprehensive test coverage with Vitest

Usage

Address Utilities

import { walletSnippet } from '@buildeross/utils'

// Create address snippets for display
const snippet = walletSnippet('0x742d35Cc6634C0532925a3b8D2C31883a29B8f8D')
// Result: "0x742...B8f8D"

// Custom snippet length
const customSnippet = walletSnippet('0x742d35Cc6634C0532925a3b8D2C31883a29B8f8D', 6)
// Result: "0x742d...1B8f8D"

Number Formatting

import { formatCryptoVal, numberFormatter } from '@buildeross/utils'

// Format crypto values with appropriate precision
formatCryptoVal('1234567890000000000') // "1.23B"
formatCryptoVal('1000000000000000000') // "1.00"
formatCryptoVal('123456789') // "123.46M"
formatCryptoVal('0.000001234567') // "0.000001"

// General number formatting
numberFormatter(1234.5678) // "1,234.568"
numberFormatter('98765') // "98,765"

String Processing

import { slugify, unslugify, sanitize } from '@buildeross/utils'

// Convert strings to URL-friendly slugs
slugify('My DAO Name & Special Characters!') // "my-dao-name-and-special-characters"
slugify('Nouns DAO #123') // "nouns-dao-123"

// Convert slugs back to readable text
unslugify('my-dao-name') // "My Dao Name"

// Sanitize HTML content
sanitize('<script>alert("xss")</script><p>Safe content</p>') // "<p>Safe content</p>"

Duration Utilities

import { toSeconds, fromSeconds, formatDuration } from '@buildeross/utils'

// Convert duration to seconds
const duration = { days: 3, hours: 2, minutes: 30, seconds: 15 }
const totalSeconds = toSeconds(duration) // 266415

// Convert seconds back to duration
const parsed = fromSeconds(266415)
// Result: { days: 3, hours: 2, minutes: 30, seconds: 15 }

// Format duration for display
formatDuration(duration) // "3 days, 2 hours, 30 minutes"

Data Helpers

import { 
  isEmpty, 
  flatten, 
  isEqual, 
  compareAndReturn,
  unpackOptionalArray 
} from '@buildeross/utils'

// Check if object is empty
isEmpty({}) // true
isEmpty({ key: 'value' }) // false

// Flatten nested objects
const nested = { a: { b: { c: 'value' } } }
flatten(nested) // { c: 'value' }

// Deep equality comparison
isEqual({ a: 1, b: { c: 2 } }, { a: 1, b: { c: 2 } }) // true

// Compare objects and return changes
const initial = { name: 'DAO', tokens: 100 }
const updated = { name: 'My DAO', tokens: 100 }
const changes = compareAndReturn(initial, updated)
// Result: [{ field: 'name', value: 'My DAO' }]

// Handle optional arrays from contract calls
const result = unpackOptionalArray(maybeArray, 5)
// Returns array or array of 5 undefined values

Blockchain Date Parsing

import { parseBlockchainDate, formatDate, formatDateTime } from '@buildeross/utils'

// Parse blockchain timestamps
const date = parseBlockchainDate(1640995200) // Unix timestamp
console.log(date) // Date object

// Format dates for display
formatDate(new Date(), false) // "2024-01-15"
formatDate(new Date(), true) // "01/15/2024"

// Format with time
formatDateTime(new Date()) // "Jan 15, 2024 10:30 AM"

ENS Utilities

import { isENSName, resolveENS } from '@buildeross/utils'

// Check if string is ENS name
isENSName('vitalik.eth') // true
isENSName('0x742d35...') // false

// Resolve ENS name to address
const address = await resolveENS('vitalik.eth')
console.log(address) // "0x..."

Gradient Utilities

import { generateGradient, createGradientFromAddress } from '@buildeross/utils'

// Generate gradient from colors
const gradient = generateGradient(['#ff0000', '#00ff00', '#0000ff'])

// Create gradient from wallet address
const addressGradient = createGradientFromAddress('0x742d35Cc6634C0532925a3b8D2C31883a29B8f8D')

Modular Imports

Import specific utilities to reduce bundle size:

// Import specific functions
import { walletSnippet, formatCryptoVal } from '@buildeross/utils'

// Import from specific modules
import { walletSnippet } from '@buildeross/utils/helpers'
import { formatCryptoVal } from '@buildeross/utils/numbers'

// Import validation schemas
import { addressSchema, durationSchema } from '@buildeross/utils/yup'

// Import wagmi utilities
import { chains, serverConfig } from '@buildeross/utils/wagmi'

Validation Schemas

The package includes Yup validation schemas for common blockchain data:

Address Schema

import { addressSchema } from '@buildeross/utils/yup'

const schema = yup.object().shape({
  recipient: addressSchema,
  token: addressSchema
})

// Validates Ethereum addresses
schema.validate({
  recipient: '0x742d35Cc6634C0532925a3b8D2C31883a29B8f8D',
  token: '0x...'
})

Duration Schema

import { durationSchema } from '@buildeross/utils/yup'

const schema = yup.object().shape({
  votingPeriod: durationSchema
})

// Validates duration objects
schema.validate({
  votingPeriod: { days: 3, hours: 0, minutes: 0, seconds: 0 }
})

URL Schema

import { urlSchema } from '@buildeross/utils/yup'

const schema = yup.object().shape({
  website: urlSchema,
  image: urlSchema
})

// Validates URLs and IPFS URIs
schema.validate({
  website: 'https://nouns.build',
  image: 'ipfs://QmHash...'
})

Wagmi Integration

Wagmi-specific utilities for server-side and client-side configuration:

import { chains, serverConfig } from '@buildeross/utils/wagmi'

// Pre-configured chains for wagmi
const config = createConfig({
  chains,
  transports: {
    [mainnet.id]: http(),
    [base.id]: http(),
  }
})

// Server-side configuration
const serverClient = createPublicClient(serverConfig)

Testing

The package includes comprehensive test coverage:

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test --coverage

Test Utilities

// Test files are co-located with source files
// helpers.test.ts, slugify.test.ts, etc.

// Example test usage
import { slugify } from '@buildeross/utils'

describe('slugify', () => {
  it('converts strings to URL-friendly slugs', () => {
    expect(slugify('My DAO Name!')).toBe('my-dao-name')
  })
})

Development

Prerequisites

Node.js 18+
pnpm 8+

Setup

# Install dependencies
pnpm install

# Build the package
pnpm build

# Development build with watch
pnpm dev

# Run tests
pnpm test

# Run type checking
pnpm type-check

# Run linting
pnpm lint

Scripts

pnpm build - Build the package for production
pnpm dev - Build in watch mode for development
pnpm test - Run test suite with Vitest
pnpm test:watch - Run tests in watch mode
pnpm type-check - Run TypeScript type checking
pnpm lint - Run ESLint with auto-fix
pnpm clean - Remove build artifacts

Dependencies

Runtime Dependencies

@buildeross/constants - Shared constants
@buildeross/types - TypeScript type definitions
@buildeross/ipfs-service - IPFS utilities
bignumber.js - Precise decimal arithmetic
tinycolor2 - Color manipulation

Peer Dependencies

viem ^2.30.0 - Ethereum library
wagmi ^2.15.4 - React hooks for Ethereum
yup ^1.6.1 - Schema validation

Development Dependencies

vitest - Testing framework
TypeScript and ESLint configurations

Utility Categories

String Processing

slugify - Convert strings to URL-friendly slugs
unslugify - Convert slugs back to readable text
sanitize - Sanitize HTML content
camelToTitle - Convert camelCase to Title Case
maxChar - Truncate strings with ellipsis
isPossibleMarkdown - Detect markdown syntax

Number & Value Formatting

formatCryptoVal - Format crypto values with precision
numberFormatter - General number formatting
BigNumberish - Type for various number formats

Address & Blockchain

walletSnippet - Create address snippets
parseBlockchainDate - Parse blockchain timestamps
parseContractURI - Parse contract metadata URIs
chainIdToSlug - Convert chain ID to URL slug

Duration & Time

toSeconds - Convert duration to seconds
fromSeconds - Convert seconds to duration
formatDuration - Format duration for display
formatDate - Format dates
formatDateTime - Format dates with time
yearsAhead - Calculate future dates
handleGMTOffset - Handle timezone offsets

Data Manipulation

isEmpty - Check if object is empty
flatten - Flatten nested objects
isEqual - Deep equality comparison
compareAndReturn - Find object differences
unpackOptionalArray - Handle optional arrays
resolvedPromise - Convert function to promise

Validation & Schemas

addressSchema - Ethereum address validation
durationSchema - Duration object validation
urlSchema - URL and IPFS URI validation

Encoding & Parsing

encodePageNumToEndCursor - Pagination cursor encoding
formABI - ABI formatting utilities
fetch - Enhanced fetch utilities
provider - Provider configuration

Error Handling

The utilities include proper error handling and graceful fallbacks:

import { formatCryptoVal, walletSnippet } from '@buildeross/utils'

// Handles invalid inputs gracefully
formatCryptoVal('invalid') // "0"
walletSnippet(undefined) // ""
walletSnippet('not-an-address') // "not-an-address"

Performance Considerations

Uses BigNumber.js for precise decimal arithmetic
Implements efficient string processing algorithms
Provides lazy evaluation where appropriate
Includes memoization for expensive operations

License

MIT License - see LICENSE file for details.