@architect/utils 

[@architect/utils][npm] is a collection of common utility functions for the [@architect][arc] framework ecosystem. It provides essential tools for AWS Lambda development, CLI operations, infrastructure management, AWS credential validation, and static asset fingerprinting for serverless applications.

Installation

npm i @architect/utils

API

utils.banner(params)

Responsible for printing the standard banner, displaying environment information including app name, AWS region, profile, version, and current working directory.

Parameters:
- params (object, optional): Configuration object with the following properties:
- inventory (object, required): Inventory object from @architect/inventory
- cwd (string): Current working directory (defaults to process.cwd())
- disableBanner (boolean): Skip printing the banner entirely
- version (string): Package version string to display (defaults to '–')
- quiet (boolean): Disable banner printing

Returns: undefined

Example:
``js
let utils = require('@architect/utils')
let inventory = require('@architect/inventory')

utils.banner({
inventory,
version: 'Architect 1.2.3'
})
`

Environment Variables:
- ARC_QUIET - if truthy, disables printing
- QUIET - if truthy, disables printing
- AWS_REGION - fallback AWS region if not configured in inventory
- AWS_PROFILE - fallback AWS profile if not configured in inventory
- AWS_ACCESS_KEY_ID - if set, shows "Set via environment" for profile

utils.chars

Returns platform-appropriate CLI characters for terminal UI printing. Provides different character sets for Windows and Unix-like systems to ensure proper display across platforms.

Parameters: None (this is an object, not a function)

Returns: Object with the following properties:
- buzz (string): Progress indicator character ('⌁' on Unix, '~' on Windows)
- start (string): Start indicator character ('⚬' on Unix, '○' on Windows)
- done (string): Completion indicator character ('✓' on Unix, '√' on Windows)
- warn (string): Warning indicator character ('⚠️' on Unix, '!' on Windows)
- err (string): Error indicator character ('×' on Unix, 'x' on Windows)

Example:
`js
let utils = require('@architect/utils')
console.log(${utils.chars.done} Task completed successfully)
console.log(${utils.chars.warn} Warning message)
`

Related utilities: Used by utils.banner() and utils.updater() for consistent CLI character display

utils.checkCreds(params, callback)

Performs basic AWS credential validation by attempting to initialize an AWS client. Used to verify that valid AWS credentials are available before proceeding with AWS operations.

Parameters:
- params (object, required): Configuration object with the following properties:
- inventory (object, required): Inventory object from @architect/inventory
- callback (function, optional): Node.js-style callback function (err) => {}

Returns: Promise if no callback provided, otherwise undefined

Example:
`js
let utils = require('@architect/utils')
let inventory = require('@architect/inventory')

// With callback
utils.checkCreds({ inventory }, (err) => {
if (err) console.log('Invalid AWS credentials')
else console.log('AWS credentials are valid')
})

// With promise
try {
await utils.checkCreds({ inventory })
console.log('AWS credentials are valid')
} catch (err) {
console.log('Invalid AWS credentials')
}
`

utils.deepFrozenCopy(obj)

Creates a deep copy of an object and recursively freezes all nested objects, making the entire structure immutable. Approximately 2x faster than JSON-based deep copying while also providing immutability.

Parameters:
- obj (any): The object to copy and freeze

Returns: Deep frozen copy of the input object

Example:
`js
let utils = require('@architect/utils')

let original = {
config: { debug: true },
items: [1, 2, { nested: 'value' }]
}

let frozenCopy = utils.deepFrozenCopy(original)
// frozenCopy is completely immutable
// frozenCopy.config.debug = false // This would throw an error
`

utils.fingerprint(params, callback)

Generates static asset fingerprinting for cache-busting by creating a static.json manifest file that maps original filenames to fingerprinted versions with content hashes.

Parameters:
- params (object, required): Configuration object with the following properties:
- inventory (object, required): Inventory object from @architect/inventory
- fingerprint (boolean): Enable fingerprinting (defaults to inventory.inv.static.fingerprint)
- ignore (array): Array of file patterns to ignore (defaults to inventory.inv.static.ignore)
- update (function): Updater function for progress reporting
- callback (function, required): Node.js-style callback function (err, manifest) => {}

Returns: undefined

Example:
`js
let utils = require('@architect/utils')
let inventory = require('@architect/inventory')

utils.fingerprint({
inventory,
fingerprint: true
}, (err, manifest) => {
if (err) throw err
console.log('Generated fingerprint manifest:', manifest)
// manifest = { 'app.js': 'app-a1b2c3d4e5.js', ... }
})
`

Environment Variables:
- Uses inventory configuration for static asset settings

Related utilities: Uses utils.pathToUnix() internally for cross-platform path handling

utils.getLambdaName(fn)

Converts an Architect route path into a valid AWS Lambda function name by applying character substitutions that comply with Lambda naming requirements (up to 64 characters, letters, numbers, hyphens, and underscores only).

Parameters:
- fn (string): The Architect route path (e.g., '/api/users/:id')

Returns: Valid AWS Lambda function name (string)

Example:
`js
let utils = require('@architect/utils')

utils.getLambdaName('/') // Returns: '-index'
utils.getLambdaName('/api/users') // Returns: '-api-users'
utils.getLambdaName('/api/users/:id') // Returns: '-api-users-000id'
utils.getLambdaName('/api/v1.0/users') // Returns: '-api-v1_0-users'
`

Character Conversion Rules:
- / (root) becomes -index
- - becomes _
- . becomes _
- / becomes -
- \ becomes -
- : becomes 000
- * becomes catchall

Related utilities: Works with utils.toLogicalID() for CloudFormation resource naming

utils.pathToUnix(pathString)

Converts any file path to Unix-style format with forward slashes as separators. Essential for cross-platform compatibility, especially when running on Windows where backslashes are the default path separator.

Parameters:
- pathString (string): The file path to convert

Returns: Unix-style path string with forward slashes

Example:
`js
let utils = require('@architect/utils')

utils.pathToUnix('C:\\Users\\dev\\project') // Returns: 'C:/Users/dev/project'
utils.pathToUnix('/unix/path/already') // Returns: '/unix/path/already'
utils.pathToUnix('relative\\windows\\path') // Returns: 'relative/windows/path'
`

Related utilities: Used internally by utils.fingerprint() for cross-platform static asset handling

utils.toLogicalID(str)

Converts dash-case strings into PascalCase format suitable for CloudFormation logical IDs. Handles special cases and ensures the output meets CloudFormation naming requirements.

Parameters:
- str (string): The string to convert to PascalCase

Returns: PascalCase string suitable for CloudFormation logical IDs

Example:
`js
let utils = require('@architect/utils')

utils.toLogicalID('my-api-function') // Returns: 'MyApiFunction'
utils.toLogicalID('user_profile') // Returns: 'UserProfile'
utils.toLogicalID('get') // Returns: 'GetIndex' (special case)
utils.toLogicalID('api-v1.0') // Returns: 'ApiV10'
`

Related utilities: Complements utils.getLambdaName() for AWS resource naming conventions

utils.updater(name, params)

Creates a standardized progress indicator and logging utility with multiple output methods. Automatically respects Architect's global printing status and environment variables for consistent CLI experience.

Parameters:
- name (string, required): Label for the updater (e.g., 'Deploy', 'Build')
- params (object, optional): Configuration object with the following properties:
- quiet (boolean): Manually override global printing status
- logLevel (string): Set log level ('normal', 'verbose', 'debug')

Returns: Updater object with the following methods:
- status(message, ...details) - prints an affirmative status update
- start(message) - starts an animated progress indicator (aliases: update)
- done(message) - ends current progress indicator with an update (aliases: stop)
- cancel() - cancels current progress indicator without an update
- err(error) - pretty prints an error (aliases: error, fail)
- warn(message) - prints a warning (aliases: warning)
- raw(message) - logs a message as-is while respecting quiet mode
- get() - returns current updater state
- reset() - resets updater state (aliases: clear)
- verbose - verbose logging methods
- debug - debug logging methods

Example:
`js
let utils = require('@architect/utils')

let update = utils.updater('Deploy')
update.start('Deploying application...')
// ... deployment logic ...
update.done('Application deployed successfully')

// With error handling
try {
// ... some operation ...
} catch (err) {
update.err(err)
}
`

Environment Variables:
- ARC_QUIET - if truthy, disables printing
- QUIET - if truthy, disables printing
- CI - if truthy, disables certain terminal progress animations

Related utilities: Uses utils.chars` for consistent terminal character display

[arc]: https://github.com/architect
[npm]: https://www.npmjs.com/package/@architect/utils