# apteryxxyz/enhanced-ms architecture

> Architecture diagram of the GitHub repository apteryxxyz/enhanced-ms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apteryxxyz/enhanced-ms
- Repository: https://github.com/apteryxxyz/enhanced-ms

## Overview

##### Main components
- API Entry Point: Represent the main “ms” function (exported via src/index.ts) that users call. This function accepts either a number (to format) or a string (to parse).
- Factory Module: (src/factory.ts) which provides the createMs function to generate instances of the ms utility with custom language configurations and default options.
- Formatting Module: (located in src/format) that handles converting milliseconds into a formatted, human-readable duration. Within this, include:
- Helper Files: format-unit.ts, parse-milliseconds.ts, resolve-options.ts – these modules encapsulate logic for unit formatting, value parsing, and option resolution.
- Parsing Module: (located in src/parse) that parses duration strings back into milliseconds.
- Language Support Module: (in src/languages) that holds available language files (en, de, es, fr, it, mi, nl, ru) plus helper utilities (in src/languages/helpers) for building language definitions.
- Time Utility: (src/time.ts) which may encompass additional time/duration related computations.
- Test Suite: Although not part of the runtime architecture, note the tests in the tests directory that verify functionality across different languages.

##### Relationships and Interactions
- Data Flow:
- The user calls the ms function (entry point). Depending on the argument type, the ms function either directs the call to the formatting module (for number inputs) or to the parsing module (for string inputs).
- When formatting durations, the ms function may consult the factory module to apply custom configuration (language, formatOptions) and then delegate the task to the Format module.
- Inside the formatting module, helper functions take charge of resolving options and formatting each unit appropriately.
- When parsing duration strings, the parsing module processes the string into its numeric millisecond value.
- Throughout both processes, the Language module provides localized unit names and definitions that tailor the output to the user's language choice.
- Internal Dependencies:
- The factory module connects the overall configuration with both formatting and parsing, ensuring correct defaults and language rules are applied.
- The language helper utilities abstract language-specific definitions so that the formatting engine remains decoupled from the actual language details.

##### Important Architectural Patterns
- Modularity: The project exhibits a clear separation of concerns where formatting, parsing, language support, and factory configuration are encapsulated in separate modules.
- Extensibility: By isolating language definitions and helper functions, the project allows additional languages and more complex formatting options to be integrated without altering the core logic.
- Reusability: Helper modules (for parsing milliseconds or formatting units) ensure that common functionalities can be maintained and reused across the system.

##### Relevant Technologies
- Typescript: Noted by the .ts file extensions and explicit type definitions across the modules.
- Node Package Manager: Clearly seen through package.json, pnpm-lock.yaml, and the installation instructions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    API["ms() API"]:::core
    click API "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/index.ts"

    %% Factory Module
    Factory["Factory Module"]:::core
    click Factory "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/factory.ts"

    %% Formatting Module
    Format["Formatting Module"]:::core
    click Format "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/format/index.ts"

    %% Parsing Module
    Parse["Parsing Module"]:::core
    click Parse "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/parse/index.ts"

    %% Formatting Helper Functions Subgraph
    subgraph "Formatting Helper Functions"
        FUnit["Format Unit"]:::aux
        click FUnit "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/format/helpers/format-unit.ts"
        
        PMilli["Parse Milliseconds"]:::aux
        click PMilli "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/format/helpers/parse-milliseconds.ts"
        
        ROpt["Resolve Options"]:::aux
        click ROpt "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/format/helpers/resolve-options.ts"
    end

    %% Language Support Module Subgraph
    subgraph "Language Support Module"
        LangMain["Language Definitions"]:::aux
        
        EN["en Language"]:::aux
        click EN "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/languages/en.ts"
        
        DE["de Language"]:::aux
        click DE "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/languages/de.ts"
        
        ES["es Language"]:::aux
        click ES "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/languages/es.ts"
        
        FR["fr Language"]:::aux
        click FR "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/languages/fr.ts"
        
        IT["it Language"]:::aux
        click IT "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/languages/it.ts"
        
        MI["mi Language"]:::aux
        click MI "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/languages/mi.ts"
        
        NL["nl Language"]:::aux
        click NL "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/languages/nl.ts"
        
        RU["ru Language"]:::aux
        click RU "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/languages/ru.ts"
        
        LangHelpers["Language Helpers"]:::aux
        DT["Definition Types"]:::aux
        click DT "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/languages/helpers/definition-types.ts"
        ML["Make Language"]:::aux
        click ML "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/languages/helpers/make-language.ts"
        LangHelpers --> DT
        LangHelpers --> ML
        LangMain --> EN
        LangMain --> DE
        LangMain --> ES
        LangMain --> FR
        LangMain --> IT
        LangMain --> MI
        LangMain --> NL
        LangMain --> RU
        LangMain --> LangHelpers
    end

    %% Time Utility
    TimeUtil["Time Utility"]:::aux
    click TimeUtil "https://github.com/apteryxxyz/enhanced-ms/blob/main/src/time.ts"

    %% Test Suite (dashed for non-runtime components)
    TestSuite["Test Suite"]:::test
    click TestSuite "https://github.com/apteryxxyz/enhanced-ms/tree/main/tests"

    %% Connections
    API -->|"number_input"| Factory
    API -->|"string_input"| Parse
    Factory -->|"config_options"| Format
    Format -->|"uses"| FUnit
    Format -->|"uses"| PMilli
    Format -->|"uses"| ROpt
    Format -->|"time_calculations"| TimeUtil
    Parse -->|"time_calculations"| TimeUtil
    Format -->|"localized_definitions"| LangMain
    Parse -->|"localized_definitions"| LangMain
    TestSuite -.->|"verifies"| API

    %% Styles
    classDef core fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef aux fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef test fill:#F5B7B1,stroke:#C0392B,stroke-width:2px,stroke-dasharray: 5, 5;
```
