@lovebowls/leaguejs/README.md

A framework-agnostic JavaScript library for managing leagues, teams, and matches

# LeagueJS

A pure JavaScript library for managing leagues, teams, and matches.

> **Note**: This library is currently in alpha status. The API may change without notice.

## Overview

LeagueJS is a framework-agnostic JavaScript library that provides a clean, efficient way to manage leagues, teams, and matches. It follows a class-based approach, allowing you to create and manipulate league data directly. The library supports both CommonJS and ES Modules, making it compatible with various environments including Node.js, browsers, and Wix. With full TypeScript support including declaration files, it offers excellent IDE integration and type safety for all operations.

## Features

- **League Management**
  - Create customizable leagues with configurable point systems
  - Direct operations on league instances
  - JSON import/export for data portability

- **Team Management**
  - Create and manage teams within leagues
  - Track team details and statistics
  - Handle team additions and removals

- **Match Management**
  - Create and record match results between teams
  - Support for match scheduling
  - Comprehensive match history tracking
  - Unique match identifiers using UUID v4

- **League Table Calculations**
  - Automated position table generation
  - Configurable scoring systems (points for wins, draws, losses)
  - Sort by points, shot difference, and shots scored

- **TypeScript Support**
  - Full TypeScript declaration files (.d.ts) for all classes and functions
  - Enhanced IDE autocompletion support for Wix and other environments
  - Comprehensive type definitions for all classes and methods
  - Seamless integration with TypeScript projects
  - Type safety for all classes and methods
  - Comprehensive interface definitions

## Dependencies

- **uuid**: Used for generating unique match identifiers
  - Version: ^11.1.0
  - Purpose: Ensures each match has a globally unique identifier
  - Implementation: Uses UUID v4 for maximum uniqueness

## Installation

```bash
npm install @lovebowls/leaguejs
```

## Usage

### ES Modules (Recommended)
```javascript
import { League, Team, Match } from '@lovebowls/leaguejs';

// Create a new league
const league = new League({
  name: 'Premier League',
  settings: {
    pointsForWin: 3,
    pointsForDraw: 1,
    pointsForLoss: 0
  }
});

// Add teams
const team1 = new Team({ _id: 'arsenal', name: 'Arsenal' });
const team2 = new Team({ _id: 'chelsea', name: 'Chelsea' });
league.addTeam(team1);
league.addTeam(team2);

// Add a match with the result
const match = new Match({
  homeTeam: team1,
  awayTeam: team2,
  date: new Date(),
  result: { homeScore: 2, awayScore: 1 }
});
league.addMatch(match);

// Get team stats
const teamStats = league.getTeamStats(team1._id);

// Get league table
const leagueTable = league.getLeagueTable();
```

### CommonJS
```javascript
const { League, Team, Match } = require('@lovebowls/leaguejs');

// Usage is identical to ES Modules example above
```

### Wix Backend Usage
For Wix backend code, use Direct import:

```javascript
// Method 1: Direct import (recommended)
import { League, Team, Match } from '@lovebowls/leaguejs';

### Data Persistence
To save and load league data:

```javascript
// Convert to JSON for storage
const leagueJSON = league.toJSON();

// Later, load from JSON
const loadedLeague = League.fromJSON(leagueJSON);
```

## API Reference

### League

Represents a league with teams and matches.

#### Methods

- **addTeam(team)** - Add a team to the league
- **removeTeam(teamId)** - Remove a team from the league
- **addMatch(match)** - Add a match to the league
- **getTeam(teamId)** - Get a team by ID
- **getMatch(matchId)** - Get a match by ID
- **getTeamMatches(teamId)** - Get all matches for a team
- **getTeamStats(teamId)** - Get statistics for a team
- **getLeagueTable()** - Get the current league table
- **toJSON()** - Convert league to JSON
- **static fromJSON(jsonData)** - Create a League instance from JSON data

### Team

Represents a team in a league.

#### Properties
- **_id** - Unique identifier for the team
- **name** - Name of the team (defaults to _id if not provided)

#### Methods

- **update(updates)** - Update team details
- **toJSON()** - Convert team to JSON

### Match

Represents a match between two teams.

#### Methods

- **getWinner()** - Determines the winner (team name or 'draw') or null if no result.
- **isDraw()** - Returns true if the match is a draw, false otherwise, or null if no result.
- **setRinkScores(rinkScores)** - Set rink scores for an existing match result
- **getRinkResults()** - Get rink win/draw counts
- **toJSON()** - Convert match to JSON
- **_id** - The unique identifier for the match

## Project Structure

```
leaguejs/
├── src/
│   ├── models/
│   │   ├── League.js
│   │   ├── Team.js
│   │   └── Match.js
│   ├── utils/
│   │   ├── calculators.js
│   │   └── validators.js
│   └── index.js
├── dist/
│   ├── index.js        # ES Module build
│   ├── index.js.map    # Source map for ES Module
│   ├── index.cjs       # CommonJS build
│   └── index.cjs.map   # Source map for CommonJS
├── tests/
├── package.json
├── rollup.config.js
└── README.md
```

## Development

### Source Control

This project uses Git for version control. To clone the repository:

```bash
git clone https://helixteamhub.cloud/lovebowlscouk/projects/leaguejs/repositories/leagueJS/tree/main.git
cd leaguejs
npm install
```

### Building

The library is built using rollup to generate both CommonJS and ES Module formats:

```bash
# Development build with watch mode
npm run dev

# Production build
npm run build
```

### Testing

The library includes comprehensive tests using Jest:

```bash
npm test
```

## License

MIT

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

Please ensure your code follows the existing style and includes appropriate tests.