Install

npm add @ckimrie/utils
# or
yarn add @ckimrie/utils

Usage

Import

// ES Modules
import { getEnv, shortButUnique, currentBranchName } from '@ckimrie/utils'

// CommonJS
const { getEnv, shortButUnique, currentBranchName } = require('@ckimrie/utils')

API Documentation

Environment Utilities

envKeyName(key: string): string

Convert a key to uppercase environment variable format by replacing hyphens with underscores.

import { envKeyName } from '@ckimrie/utils'

envKeyName('my-app-key') // 'MY_APP_KEY'
envKeyName('database-url') // 'DATABASE_URL'

getEnv(name: string, defaultIfNotFound?: string | ErrorConstructor): string

Get an environment variable with optional default value. Throws an error by default if the variable is not set.

Parameters:

• name: Environment variable name
• defaultIfNotFound: Default value (string) or Error constructor to throw error (default: Error)

import { getEnv } from '@ckimrie/utils'

// Throws error if NODE_ENV is not set
const env = getEnv('NODE_ENV')

// Returns 'development' if NODE_ENV is not set
const env = getEnv('NODE_ENV', 'development')

// Returns empty string if API_KEY is not set
const apiKey = getEnv('API_KEY', '')

envAwareName(name: string, maxLength: number = 30): string

Generate environment-aware resource names. In CI environments, appends the environment name. In local development, appends username and git branch name, truncated for uniqueness.

Parameters:

• name: Base name for the resource
• maxLength: Maximum length of the generated name (default: 30)

import { envAwareName } from '@ckimrie/utils'

// In CI with NODE_ENV=production
envAwareName('my-app') // 'my-app-production'

// In local development
envAwareName('my-app') // 'my-app-john-feature-branch-a1b2'

// With custom max length
envAwareName('my-really-long-app-name', 20) // 'my-really-long-app-n-c3d4'

isProduction(): boolean

Check if the current environment is production.

import { isProduction } from '@ckimrie/utils'

if (isProduction()) {
  console.log('Running in production mode')
}

getEnvName(): string

Get the current environment name from NODE_ENV, defaulting to 'development'.

import { getEnvName } from '@ckimrie/utils'

const environment = getEnvName() // 'development', 'production', 'staging', etc.

isCI(): boolean

Check if the code is running in a CI environment by checking for the CI environment variable.

import { isCI } from '@ckimrie/utils'

if (isCI()) {
  console.log('Running in CI environment')
}

String Utilities

shortButUnique(str: string, maxLength: number = 8, separator: string = '-'): string

Truncate a string to a maximum length while maintaining uniqueness by appending a hash of the truncated portion.

Parameters:

• str: The string to truncate
• maxLength: Maximum length of the result (default: 8)
• separator: Separator between truncated string and hash (default: '-')

import { shortButUnique } from '@ckimrie/utils'

shortButUnique('hello') // 'hello' (no truncation needed)
shortButUnique('this-is-a-very-long-string') // 'this-is--a1b2' (truncated with hash)
shortButUnique('long-string', 15, '_') // 'long-string_c3d4' (custom separator)

Git Utilities

currentBranchName(executor?: CommandExecutor): string

Get the current git branch name.

Parameters:

• executor: Optional command executor for dependency injection

import { currentBranchName } from '@ckimrie/utils'

const branch = currentBranchName() // 'main', 'feature/new-feature', etc.

Usage Patterns

Environment-Aware Resource Naming

Perfect for creating unique resource names in different environments:

import { envAwareName, isCI } from '@ckimrie/utils'

// Database name that's unique per developer and environment
const dbName = envAwareName('myapp-db')

// S3 bucket with environment scoping
const bucketName = envAwareName('data-bucket', 50)

Configuration Management

import { getEnv, getEnvName, isProduction } from '@ckimrie/utils'

const config = {
  environment: getEnvName(),
  apiUrl: getEnv('API_URL', 'http://localhost:3000'),
  logLevel: isProduction() ? 'error' : 'debug',
  database: {
    host: getEnv('DB_HOST'),
    name: getEnv('DB_NAME', 'myapp_dev')
  }
}

Git-Based Workflows

import { currentBranchName } from '@ckimrie/utils'
import { execSync } from 'node:child_process'

const branch = currentBranchName()
const isMainBranch = branch === 'main'
const hasChanges = execSync('git status --porcelain').toString().length > 0

if (!isMainBranch && hasChanges) {
  console.log(`Working on ${branch} with uncommitted changes`)
}

Contributing

Please consult CONTRIBUTING for guidelines on contributing to this project.

Author

@ckimrie/utils © Christopher Imrie, Released under the Apache-2.0 License.