@codedrifters/utils 0.0.20 → 0.0.21

package/README.md

@@ -1,307 +1,7 @@
 # @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.
+Common utilities and helper functions for CodeDrifters projects. Lightweight helpers for Git operations (`findGitBranch`, `findGitRepoName`), string manipulation (`hashString`, `trimStringLength`), and shared AWS type definitions (`AwsStageType`, `DeploymentTargetRoleType`) used across deployment configurations.
 
-## Table of Contents
+**Documentation:** See the [@codedrifters/utils docs](../../../docs/src/content/docs/packages/@codedrifters/utils/index.md) in the monorepo's Starlight site.
 
-- [Installation](#installation)
-- [Utility Functions](#utility-functions)
-  - [Git Utilities](#git-utilities)
-  - [String Utilities](#string-utilities)
-  - [AWS Types](#aws-types)
-- [API Reference](#api-reference)
-- [Further Documentation](#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:
-
-```typescript
-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:
-
-```typescript
-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:
-
-```bash
-npx projen
-```
-
-This will update your `package.json` with the new dependency. Then run:
-
-```bash
-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.
-
-```typescript
-import { findGitBranch } from '@codedrifters/utils/lib/git-utils';
-
-const branch = findGitBranch();
-// Returns: "feature/1234" or "main" etc.
-```
-
-**Example Usage:**
-
-```typescript
-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.
-
-```typescript
-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:**
-
-```typescript
-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.
-
-```typescript
-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:**
-
-```typescript
-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.
-
-```typescript
-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:**
-
-```typescript
-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).
-
-```typescript
-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).
-
-```typescript
-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:**
-
-```typescript
-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:**
-```typescript
-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):**
-```typescript
-import { findGitBranch, hashString, AWS_STAGE_TYPE, AwsStageType } from '@codedrifters/utils';
-```
-
-## Further Documentation
-
-### Package Information
-
-- [NPM Package](https://www.npmjs.com/package/@codedrifters/utils) - View on NPM
-- [GitHub Repository](https://github.com/codedrifters/packages) - Source code
-
-### Related Packages
-
-- [@codedrifters/constructs](../constructs/README.md) - AWS CDK constructs that use these utilities
-- [@codedrifters/configulator](../configulator/README.md) - 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.
+**NPM:** [@codedrifters/utils](https://www.npmjs.com/package/@codedrifters/utils)

package/package.json

@@ -10,6 +10,7 @@
     "organization": true
   },
   "devDependencies": {
+    "@microsoft/api-extractor": "7.58.7",
     "@types/node": "25.6.0",
     "@typescript-eslint/eslint-plugin": "^8",
     "@typescript-eslint/parser": "^8",
@@ -19,7 +20,9 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-jsdoc": "^62.9.0",
     "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-tsdoc": "^0.5.2",
     "prettier": "^3.8.3",
     "typescript": "^5.9.3",
     "vitest": "3.2.4"
@@ -27,13 +30,13 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "10.33.0",
+      "version": "10.33.1",
       "onFail": "ignore"
     }
   },
   "main": "lib/index.js",
   "license": "MIT",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "types": "lib/index.d.ts",
   "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
   "scripts": {