@ckimrie/utils
Personal utility library with frequently used helper functions
Install
npm add @ckimrie/utils
yarn add @ckimrie/utils
Usage
Import
import { getEnv, shortButUnique, currentBranchName } from '@ckimrie/utils'
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')
envKeyName('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'
const env = getEnv('NODE_ENV')
const env = getEnv('NODE_ENV', 'development')
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'
envAwareName('my-app')
envAwareName('my-app')
envAwareName('my-really-long-app-name', 20)
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()
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')
shortButUnique('this-is-a-very-long-string')
shortButUnique('long-string', 15, '_')
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()
Usage Patterns
Environment-Aware Resource Naming
Perfect for creating unique resource names in different environments:
import { envAwareName, isCI } from '@ckimrie/utils'
const dbName = envAwareName('myapp-db')
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.