just-exercise-parser/README.md

A TypeScript library for parsing, normalizing, and generating standardized exercise names

# Exercise Name Formatter

A TypeScript library for parsing, normalizing, and generating standardized exercise names. This library helps fitness applications maintain consistent exercise naming conventions.

## Installation

```bash
npm install just-exercise-parser  
```

or 

```bash
yarn add just-exercise-parser
```

## Features

- Standardize exercise names with consistent formatting
- Parse exercise names into component parts (movement, bodypart, equipment, etc.)
- Generate variations of exercise names using customizable templates
- Normalize names for comparison (e.g., "Bench Press Incline" == "Incline Bench Press")
- Smart handling of pluralization, abbreviations, and common fitness terminology
- Support for alternating exercises
- Customizable configuration for regex replacements and exercise components

## Usage

### Basic Example

```typescript
import { ExerciseNameFormatter } from 'just-exercise-parser';

// Create a formatter with default configuration
const formatter = new ExerciseNameFormatter();

// Standardize an exercise name (This is what you want)
const standardized = formatter.standardizeName("db bench press incline");
console.log(standardized); // "Dumbbell Incline Bench Press"

// Normalize a name for comparison
const normalized = formatter.normalizeName("incline dumbbell chest press");
console.log(normalized); // normalized for comparison - words sorted alphabetically

// Process an exercise name to get components and variations
const processed = formatter.processExerciseName("alternating db bicep curls");
console.log(processed);
// {
//   original: "alternating db bicep curls",
//   parsed: {
//     bodypart: ["bicep"],
//     movement: ["curls"],
//     equipment: ["dumbbell"],
//     modifier: ["alternating"],
//     others: []
//   },
//   variations: ["Alternating Dumbbell Bicep Curls"]
// }
```

### Custom Configuration

You can provide your own configuration object to customize the formatter's behavior:

```typescript
import { ExerciseNameFormatter, ExerciseConfig } from 'just-exercise-parser';

const customConfig: ExerciseConfig = {
  templates: {
    "standard": "${equipment} ${movement} ${bodypart} ${modifier}",
    "alternative": "${bodypart} ${movement} with ${equipment} ${modifier}"
  },
  components: {
    "bodypart": ["abs", "back", "biceps", "chest", /* ... */],
    "movement": ["curl", "press", "raise", /* ... */],
    "equipment": ["dumbbell", "barbell", "kettlebell", /* ... */],
    "modifier": ["alternating", "single arm", "single leg", /* ... */],
    "others": []
  },
  replacements: [
    { pattern: "\\bdb\\b", replacement: "dumbbell", ignoreCase: true },
    { pattern: "\\bbb\\b", replacement: "barbell", ignoreCase: true },
    // Add more replacements as needed
  ]
};

// Create a formatter with custom configuration
const formatter = new ExerciseNameFormatter(customConfig);
```

### Generate Exercise Variations

You can generate multiple variations of an exercise name using different templates:

```typescript
const processed = formatter.processExerciseName(
  "dumbbell incline chest press",
  ["standard", "alternative"]
);

console.log(processed.variations);
// [
//   "Dumbbell Incline Chest Press", 
//   "Chest Press with Dumbbell Incline"
// ]
```

## API Reference

### Classes

#### `ExerciseNameFormatter`

The main class for formatting exercise names.

**Constructor**

```typescript
constructor(config?: ExerciseConfig)
```

- `config`: Optional configuration object. If not provided, default configuration will be used.

**Methods**

- `standardizeName(exerciseName: string): string` - Standardize an exercise name with consistent formatting
- `normalizeName(exerciseName: string, internalName = false): string` - Normalize an exercise name for comparison
- `parseExerciseName(exerciseName: string): ExerciseComponents` - Parse an exercise name into its component parts
- `generateExerciseName(components: Record<string, string[]>, templateName = 'standard'): string` - Generate an exercise name from components using a template
- `processExerciseName(exerciseName: string, templateNames?: string[]): ProcessedExercise` - Process an exercise name and generate variations
- `setConfig(config: ExerciseConfig): void` - Update the configuration
- `cleanExerciseName(exerciseName: string): string` - Clean an exercise name using regex replacements

**Static Methods**

- `toTitleCase(input: string, customExceptions?: string[]): string` - Convert text to title case
- `getDefaultConfig(): ExerciseConfig` - Get the default configuration

### Interfaces

#### `ExerciseConfig`

Configuration structure for the exercise name formatter.

```typescript
interface ExerciseConfig {
  templates: Record<string, string>;
  components: Record<string, string[]>;
  replacements?: RegexReplacementConfig[];
}
```

#### `RegexReplacementConfig`

Configuration structure for regex replacements.

```typescript
interface RegexReplacementConfig {
  pattern: string;
  replacement: string;
  ignoreCase?: boolean;
}
```

#### `ExerciseComponents`

Represents the parsed components of an exercise name.

```typescript
interface ExerciseComponents {
  originalName: string;
  components: Record<string, string[]>;
}
```

#### `ProcessedExercise`

Represents a processed exercise with original name, parsed components, and variations.

```typescript
interface ProcessedExercise {
  original: string;
  parsed: Record<string, string[]>;
  variations: string[];
}
```

## License

MIT