@codedrifters/utils

@codedrifters/utils

Common utilities and helper functions for CodeDrifter projects. This package provides reusable utility functions for working with Git, string manipulation, and other common tasks.

Table of Contents

• Installation
• Utility Functions
  • Git Utilities
  • String Utilities
  • AWS Types
• API Reference
• Further Documentation

Installation

Important: Always configure dependencies through Projen/Configulator, not by manually installing packages via command line. This ensures consistent dependency management across your project.

In a Monorepo (Recommended)

If you're using @codedrifters/configulator in a monorepo, add the package as a dependency in your sub-project configuration:

import { TypeScriptProject } from '@codedrifters/configulator';
import { MonorepoProject } from '@codedrifters/configulator';

const myProject = new TypeScriptProject({
  name: 'my-project',
  packageName: '@myorg/my-project',
  outdir: 'packages/my-project',
  parent: root, // Your MonorepoProject instance
  
  deps: [
    '@codedrifters/utils',
  ],
});

In a Standalone Project

If you're using Projen directly, add the package to your deps array:

import { typescript } from 'projen';

const project = new typescript.TypeScriptProject({
  name: 'my-project',
  
  deps: [
    '@codedrifters/utils',
  ],
});

After Adding to Configuration

After updating your projenrc configuration file, run:

npx projen

This will update your package.json with the new dependency. Then run:

pnpm install

to install the newly configured dependencies.

Utility Functions

Git Utilities

Helper functions for working with Git in deployments and build processes.

findGitBranch()

Returns the current git branch name.

import { findGitBranch } from '@codedrifters/utils/lib/git-utils';

const branch = findGitBranch();
// Returns: "feature/1234" or "main" etc.

Example Usage:

import { findGitBranch } from '@codedrifters/utils/lib/git-utils';

// Use in CDK deployment
const branch = findGitBranch();
const environment = branch === 'main' ? 'production' : 'staging';

findGitRepoName()

Returns the repository name. Works in both local environments and GitHub Actions.

import { findGitRepoName } from '@codedrifters/utils/lib/git-utils';

const repoName = findGitRepoName();
// Returns: "codedrifters/packages" or similar

How it works:

• In GitHub Actions, this uses the GITHUB_REPOSITORY environment variable
• Locally, it extracts the name from the git remote URL

Example Usage:

import { findGitRepoName } from '@codedrifters/utils/lib/git-utils';

const repoName = findGitRepoName();
console.log(`Deploying from repository: ${repoName}`);

String Utilities

Helper functions for string manipulation and hashing.

hashString(inString: string, trimLength?: number)

Creates a SHA-256 hash of a string, optionally trimmed to a specific length.

import { hashString } from '@codedrifters/utils/lib/string-utils';

const hash = hashString('my-string');
// Returns: Full SHA-256 hash

const shortHash = hashString('my-string', 8);
// Returns: First 8 characters of hash

Parameters:

• inString: string - The string to hash
• trimLength?: number - Optional length to trim the hash to (defaults to 999)

Example Usage:

import { hashString } from '@codedrifters/utils/lib/string-utils';

// Create a unique identifier from a string
const id = hashString('user-123', 16);
// Returns: First 16 characters of SHA-256 hash

// Full hash for security purposes
const secureHash = hashString('sensitive-data');

trimStringLength(inputString: string, maxLength: number)

Truncates a string to a maximum length if it exceeds it.

import { trimStringLength } from '@codedrifters/utils/lib/string-utils';

const short = trimStringLength('very long string', 10);
// Returns: "very long " (truncated to 10 chars)

const unchanged = trimStringLength('short', 10);
// Returns: "short" (no change needed)

Parameters:

• inputString: string - The string to truncate
• maxLength: number - Maximum length of the string

Example Usage:

import { trimStringLength } from '@codedrifters/utils/lib/string-utils';

// Ensure string fits within AWS resource name limits
const resourceName = trimStringLength('very-long-resource-name', 63);
// Useful for AWS resource naming constraints

AWS Types

Type definitions for AWS deployment stages and environment types, commonly used in CDK deployment configurations.

AWS_STAGE_TYPE and AwsStageType

Constants and types for deployment stage classification (dev, stage, prod).

import { AWS_STAGE_TYPE, AwsStageType } from '@codedrifters/utils/lib/aws/aws-types';

// Use the constant
const stage = AWS_STAGE_TYPE.DEV; // "dev"
const prodStage = AWS_STAGE_TYPE.PROD; // "prod"

// Use the type
function configureDeployment(stage: AwsStageType) {
  // stage can be "dev", "stage", or "prod"
}

Available Values:

• AWS_STAGE_TYPE.DEV - Development environment
• AWS_STAGE_TYPE.STAGE - Staging environment
• AWS_STAGE_TYPE.PROD - Production environment

DEPLOYMENT_TARGET_ROLE and DeploymentTargetRoleType

Constants and types for deployment target role (primary vs secondary region).

import { DEPLOYMENT_TARGET_ROLE, DeploymentTargetRoleType } from '@codedrifters/utils/lib/aws/aws-types';

// Use the constant
const role = DEPLOYMENT_TARGET_ROLE.PRIMARY; // "primary"
const replicaRole = DEPLOYMENT_TARGET_ROLE.SECONDARY; // "secondary"

// Use the type
function configureRegion(role: DeploymentTargetRoleType) {
  // role can be "primary" or "secondary"
}

Available Values:

• DEPLOYMENT_TARGET_ROLE.PRIMARY - Primary deployment target (account/region)
• DEPLOYMENT_TARGET_ROLE.SECONDARY - Secondary/replica deployment target

Example Usage:

import { AWS_STAGE_TYPE, DEPLOYMENT_TARGET_ROLE } from '@codedrifters/utils/lib/aws/aws-types';
import { AwsDeploymentTarget } from '@codedrifters/configulator';

// Configure a deployment target (preferred: deploymentTargetRole)
new AwsDeploymentTarget(project, {
  account: '123456789012',
  region: 'us-east-1',
  awsStageType: AWS_STAGE_TYPE.PROD,
  deploymentTargetRole: DEPLOYMENT_TARGET_ROLE.PRIMARY,
});

AWS_ENVIRONMENT_TYPE and AwsEnvironmentType (deprecated)

Deprecated. Use DEPLOYMENT_TARGET_ROLE and DeploymentTargetRoleType instead. These names are maintained for backward compatibility.

• AWS_ENVIRONMENT_TYPE - Same as DEPLOYMENT_TARGET_ROLE (PRIMARY, SECONDARY)
• AwsEnvironmentType - Same as DeploymentTargetRoleType

API Reference

Exports

The package exports the following utility functions:

Git Utilities:

• findGitBranch() - Get current git branch name
• findGitRepoName() - Get repository name (works in local and CI environments)

String Utilities:

• hashString(inString: string, trimLength?: number) - Create SHA-256 hash of a string
• trimStringLength(inputString: string, maxLength: number) - Truncate string to maximum length

AWS Types:

• AWS_STAGE_TYPE - Constants for deployment stages (DEV, STAGE, PROD)
• AwsStageType - Type for deployment stage values
• DEPLOYMENT_TARGET_ROLE - Constants for deployment target role (PRIMARY, SECONDARY)
• DeploymentTargetRoleType - Type for deployment target role values
• AWS_ENVIRONMENT_TYPE - (Deprecated) Use DEPLOYMENT_TARGET_ROLE instead
• AwsEnvironmentType - (Deprecated) Use DeploymentTargetRoleType instead

Import Paths

You can import utilities in two ways:

Direct import from lib:

import { findGitBranch } from '@codedrifters/utils/lib/git-utils';
import { hashString } from '@codedrifters/utils/lib/string-utils';
import { AWS_STAGE_TYPE, AwsStageType } from '@codedrifters/utils/lib/aws/aws-types';

Import from main package (if re-exported):

import { findGitBranch, hashString, AWS_STAGE_TYPE, AwsStageType } from '@codedrifters/utils';

Further Documentation

Package Information

• NPM Package - View on NPM
• GitHub Repository - Source code

Related Packages

• @codedrifters/constructs - AWS CDK constructs that use these utilities
• @codedrifters/configulator - Projen configuration utilities

Note: This package is designed to be lightweight and dependency-free where possible. It uses Node.js built-in modules (node:child_process, node:crypto) for maximum compatibility.