{"id":49199819,"url":"https://github.com/mattriffle/tennisjs","last_synced_at":"2026-04-23T13:09:03.500Z","repository":{"id":197304595,"uuid":"698404317","full_name":"mattriffle/tennisjs","owner":"mattriffle","description":"A Typescript library for scoring tennis matches","archived":false,"fork":false,"pushed_at":"2025-08-22T01:51:47.000Z","size":149,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-22T02:20:59.469Z","etag":null,"topics":["scoring","tennis","typescript"],"latest_commit_sha":null,"homepage":"https://tennisjs.org","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattriffle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-09-29T20:54:22.000Z","updated_at":"2025-08-22T01:51:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"c7e5d4c8-44e5-4178-85e9-ec27295c7b46","html_url":"https://github.com/mattriffle/tennisjs","commit_stats":null,"previous_names":["mattriffle/tennisjs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mattriffle/tennisjs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattriffle%2Ftennisjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattriffle%2Ftennisjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattriffle%2Ftennisjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattriffle%2Ftennisjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattriffle","download_url":"https://codeload.github.com/mattriffle/tennisjs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattriffle%2Ftennisjs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32181529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T11:42:27.955Z","status":"ssl_error","status_checked_at":"2026-04-23T11:42:18.877Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["scoring","tennis","typescript"],"created_at":"2026-04-23T13:09:02.518Z","updated_at":"2026-04-23T13:09:03.495Z","avatar_url":"https://github.com/mattriffle.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp\u003e\n  \u003ca href=\"https://github.com/mattriffle/tennisjs\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/mattriffle/tennisjs-vue/main/src/assets/tennisjs.png\" alt=\"tennisjs-vue logo\" width=\"200\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## What is it?\n\nA Typescript package for scoring tennis matches, keeping track of each point and how it was won, as well as various statistics. It provides functions enabling the front-end to use either LocalStorage API or a back-end system for persistence.\n\n**Version 3.0+ Features:**\n\n- **Unified API**: Consistent interface for both singles and doubles matches\n- **Enhanced Statistics**: Comprehensive player and team statistics\n- **Better TypeScript Support**: Improved type safety and developer experience\n\n## Where can I find it?\n\nhttps://github.com/mattriffle/tennisjs/\n\n-or-\n\nhttps://tennisjs.org\n\n-or-\n\n`npm install tennisjs`\n\n## Is there an FE available?\n\nFind TennisJS Vue at: https://github.com/mattriffle/tennisjs-vue/\n\n## Basic Usage\n\n### New Unified API (Recommended)\n\nThe new unified API provides a consistent interface for both singles and doubles matches with enhanced features and better type safety.\n\n#### Singles Match\n\n```javascript\nimport { TennisMatch, PointOutcome } from \"tennisjs\";\n\n// Create a new best-of-3 sets singles match\nconst match = new TennisMatch(\"Player 1\", \"Player 2\", 3);\n\n// Score a point for Player 1 (Ace)\nmatch.scorePoint(1, PointOutcome.Ace);\n\n// Score a point for Player 2 (Winner)\nmatch.scorePoint(2, PointOutcome.Winner);\n\n// Get a comprehensive match summary\nconst summary = match.getMatchSummary();\nconsole.log(summary);\n\n// Get a simple string representation of the score\nconsole.log(summary.matchScore); // e.g., \"6-3, 4-6, 2-0\"\n\n// Undo the last point\nmatch.removePoint();\n\n// Save/load match state\nconst json = match.toJSON();\nconst restoredMatch = TennisMatch.fromJSON(json);\n```\n\n#### Doubles Match\n\n```javascript\nimport { TennisMatch, PointOutcome } from \"tennisjs\";\n\n// Create a new best-of-3 sets doubles match\nconst doublesMatch = new TennisMatch(\n  [\"Alice\", \"Bob\"], // Team 1\n  [\"Charlie\", \"Diana\"], // Team 2\n  3\n);\n\n// Get player IDs from the match summary\nconst summary = doublesMatch.getMatchSummary();\nconst aliceId = summary.participants[1].info.players.a.id;\nconst bobId = summary.participants[1].info.players.b.id;\nconst charlieId = summary.participants[2].info.players.a.id;\nconst dianaId = summary.participants[2].info.players.b.id;\n\n// Score a point for Team 1 (Ace by Alice)\ndoublesMatch.scorePoint(1, PointOutcome.Ace, aliceId);\n\n// Score a point for Team 2 (Winner by Charlie)\ndoublesMatch.scorePoint(2, PointOutcome.Winner, charlieId);\n\n// Get updated match summary with individual player statistics\nconst updatedSummary = doublesMatch.getMatchSummary();\nconsole.log(updatedSummary.participants[1].stats); // Team 1 stats\nconsole.log(updatedSummary.score.server.current); // Current server ID\n\n// Serving rotation is handled automatically\nconsole.log(updatedSummary.score.server.rotation); // Current rotation order\n```\n\n### Resuming a Match\n\n#### New Unified API\n\n```javascript\nimport { UnifiedTennisMatch } from \"tennisjs\";\n\n// Load from localStorage (default)\nconst resumedMatch = TennisMatch.load();\n\nif (resumedMatch) {\n  console.log(\"Match resumed!\", resumedMatch.getMatchSummary());\n} else {\n  console.log(\"No saved match found.\");\n}\n\n// Load from custom source\nconst customLoader = () =\u003e {\n  // Load from your custom storage (database, API, etc.)\n  return localStorage.getItem(\"myCustomMatch\");\n};\n\nconst customMatch = TennisMatch.load(customLoader);\n```\n\n### Custom Save Behavior\n\n```javascript\nimport { TennisMatch, PointOutcome } from \"tennisjs\";\n\nconst customSave = (match) =\u003e {\n  // Example: Send the match state to a server\n  // fetch('/api/save-match', {\n  //   method: 'POST',\n  //   body: JSON.stringify(match.toJSON()),\n  // });\n  console.log(\"Match state saved!\", match.toJSON());\n};\n\nconst match = new TennisMatch(\"Player 1\", \"Player 2\", 3, customSave);\n\nmatch.scorePoint(1, PointOutcome.Ace);\n\n// Manual save\nconst json = match.toJSON();\nlocalStorage.setItem(\"myMatch\", JSON.stringify(json));\n\n// Manual load\nconst savedJson = JSON.parse(localStorage.getItem(\"myMatch\") || \"{}\");\nconst restoredMatch = TennisMatch.fromJSON(savedJson);\n```\n\n## Migration Guide\n\nFor existing projects using the legacy API, the unified API provides backward compatibility to ensure smooth migration.\n\n### Drop-in Replacement\n\n```javascript\n// Before (legacy API)\nimport { TennisMatch } from \"tennisjs\";\nconst match = new TennisMatch(\"P1\", \"P2\", 3);\n\n// After (unified API - minimal changes)\nimport { TennisMatch } from \"tennisjs\";\nconst match = new TennisMatch(\"P1\", \"P2\", 3);\n// All existing methods work exactly the same\n```\n\n### Benefits of Migrating\n\n- **Better Type Safety**: Full TypeScript support with proper enums\n- **Enhanced Features**: Individual player stats, better serialization\n- **Consistent API**: Same interface for singles and doubles\n- **Future-Proof**: All new features will be added to the unified API\n- **Backward Compatible**: Legacy code continues to work\n\n## Unified Doubles Support Features\n\nThe unified API provides enhanced doubles support with consistent behavior across both singles and doubles matches.\n\n### Serving Rotation\n\n- **Regular Games**: One player serves the entire game\n- **Rotation Order**: Team1-PlayerA → Team2-PlayerA → Team1-PlayerB → Team2-PlayerB → repeat\n- **Tiebreak**: Server changes after 1st point, then every 2 points\n- **New Set**: The team that received first in the previous set serves first\n\n### Individual Player Statistics\n\nEach player in doubles has comprehensive individual statistics tracked:\n\n- **Serving Stats**: Aces, double faults, service winners, first/second serve percentage\n- **Return Stats**: Return winners, break points won/played\n- **Rally Stats**: Winners, unforced errors, net points\n- **Overall**: Points won/played, service games played\n\n### Enhanced Match Summary Structure\n\n```javascript\n// Unified match summary (works for both singles and doubles)\n{\n  meta: {\n    matchType: 'doubles',\n    status: 'in-progress',\n    format: { sets: 3, tiebreakAt: 6, finalSetTiebreak: true }\n  },\n  score: {\n    sets: [1, 0],\n    games: [3, 2],\n    points: { values: [15, 0], type: 'game' },\n    server: {\n      current: 'player-id',\n      rotation: ['p1-a', 'p2-a', 'p1-b', 'p2-b']\n    },\n    winner: undefined\n  },\n  participants: {\n    1: {\n      info: { name: 'Team 1', type: 'team', players: { a: {...}, b: {...} } },\n      stats: {\n        // Team-level stats\n        serving: { aces: 2, doubleFaults: 0 },\n        // Individual player stats\n        playerStats: {\n          'player-a-id': { serving: { aces: 1 } },\n          'player-b-id': { serving: { aces: 1 } }\n        }\n      }\n    },\n    2: { /* same structure */ }\n  },\n  matchScore: '6-3, 3-2',\n  setHistory: [/* completed sets */]\n}\n```\n\n### Player-Specific Scoring\n\n```javascript\nimport { TennisMatch, PointOutcome } from \"tennisjs\";\n\nconst match = new TennisMatch([\"Alice\", \"Bob\"], [\"Charlie\", \"Diana\"], 3);\n\n// Get player IDs from the match participants\nconst summary = match.getMatchSummary();\nconst aliceId = summary.participants[1].info.players.a.id;\nconst bobId = summary.participants[1].info.players.b.id;\nconst charlieId = summary.participants[2].info.players.a.id;\nconst dianaId = summary.participants[2].info.players.b.id;\n\n// Score a point with specific player attribution\nmatch.scorePoint(1, PointOutcome.Ace, aliceId);\n\n// Get individual player stats\nconst updatedSummary = match.getMatchSummary();\nconst aliceStats = updatedSummary.participants[1].stats.playerStats?.[aliceId];\nconsole.log(`Alice's aces: ${aliceStats?.serving.aces}`);\n\n// You can also access team-level stats\nconst team1Stats = updatedSummary.participants[1].stats;\nconsole.log(`Team 1 total aces: ${team1Stats.serving.aces}`);\n```\n\n## Where to send bugs?\n\nhttps://github.com/mattriffle/tennisjs/issues\n\n## Didn't you used to brag about this library being vanilla Javascript?\n\nYes. And that version is still available on the v1 branch of the repo. Enjoy. It has both the scoring library and the vanilla HTML/CSS/JS front end.\n\n## What happened to being such a purist?\n\nI ended up doing a lot of Typescript and Vue at work, so I updated this to use (and even more so practice) those skills.\n\n## LICENSE\n\nCopyright 2025 Matthew Riffle\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattriffle%2Ftennisjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattriffle%2Ftennisjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattriffle%2Ftennisjs/lists"}