@tungstenstudio/outschart-generator 1.0.0-rc.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Tungsten Studio
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# @tungstenstudio/outschart-generator
+
+Darts outs/checkout chart generator with pre-computed lookups and a miss-aware recommendation engine.
+
+## Features
+
+- **Instant lookups** — pre-computed double-out and single-out charts, zero computation
+- **Generation engine** — brute-force enumerate all possible checkouts (82K double-out, 242K single-out)
+- **Miss-aware recommendations** — scoring algorithm using physical dartboard layout, segment areas, and bust risk
+- **Preferred targets** — filter checkouts to your favorite finishing doubles/targets
+- **Notation presets** — format charts for different regional conventions (british, american, or custom)
+- **Zero dependencies** — pure TypeScript, works in Node.js and browsers
+
+## Install
+
+```
+npm install @tungstenstudio/outschart-generator
+```
+
+## Quick Start
+
+```ts
+import { getCheckout, getCheckoutChart, getBogeyNumbers } from '@tungstenstudio/outschart-generator';
+
+// Instant lookup
+getCheckout(170, 'double');
+// { darts: ['T20', 'T20', 'Bull'], numDarts: 3 }
+
+getCheckout(40, 'double');
+// { darts: ['D20'], numDarts: 1 }
+
+// Full chart
+const chart = getCheckoutChart('double');
+
+// Bogey numbers (no checkout possible)
+getBogeyNumbers('double');
+// [159, 162, 163, 165, 166, 168, 169]
+```
+
+## API
+
+### Lookup Functions (pre-computed, instant)
+
+#### `getCheckout(score, outMode?)`
+Returns the recommended checkout for a single score, or `null` if not checkable.
+
+```ts
+getCheckout(92, 'double')
+// { darts: ['T20', 'D16'], numDarts: 2 }
+```
+
+#### `getCheckoutChart(outMode?, range?)`
+Returns the full checkout chart, optionally filtered by score range.
+
+```ts
+getCheckoutChart('single', { min: 1, max: 60 })
+```
+
+#### `getBogeyNumbers(outMode?)`
+Returns scores that cannot be finished in 3 darts.
+
+#### `isCheckable(score, outMode?)`
+Returns `true` if the score has a checkout in the pre-computed chart.
+
+### Generation Engine (computational)
+
+#### `generateAllCheckouts(options)`
+Brute-force enumerates ALL possible checkouts.
+
+```ts
+const result = generateAllCheckouts({ outMode: 'double' });
+// result.totalOptions === 82047
+// result.checkouts[170].options === [['T20', 'T20', 'Bull']]
+```
+
+#### `generateRecommended(options)`
+Generates a miss-aware recommended chart using the scoring algorithm.
+
+```ts
+const result = generateRecommended({
+  outMode: 'single',
+  includeAlternates: true,
+  altThreshold: 1.0,
+  overrides: { 100: { darts: ['T20', '20', '20'] } },
+});
+```
+
+#### `filterByPreferredTargets(checkouts, preferredTargets)`
+Filters enumerated checkouts to only those finishing on preferred targets.
+
+```ts
+const all = generateAllCheckouts({ outMode: 'double' });
+const filtered = filterByPreferredTargets(all.checkouts, ['D20', 'D16']);
+```
+
+### Notation / Internationalization
+
+#### `formatDart(dart, notation)`
+Formats a single dart label using a notation preset or custom map.
+
+```ts
+import { formatDart, NOTATIONS } from '@tungstenstudio/outschart-generator';
+
+formatDart('T20', NOTATIONS.british)  // 'T20'
+formatDart('Bull', NOTATIONS.british) // 'DB'
+formatDart('25', NOTATIONS.american)  // 'SB'
+formatDart('20', NOTATIONS.explicit)  // 'S20'
+```
+
+#### `formatCheckoutChart(chart, notation)`
+Formats an entire checkout chart. Accepts a preset name string or a `NotationMap` object.
+
+```ts
+import { getCheckoutChart, formatCheckoutChart } from '@tungstenstudio/outschart-generator';
+
+const chart = getCheckoutChart('double');
+
+// Use a built-in preset by name
+const british = formatCheckoutChart(chart, 'british');
+british[170].darts // ['T20', 'T20', 'DB']
+
+// Use a fully custom notation
+const custom = formatCheckoutChart(chart, {
+  treble: 'Triple ',
+  double: 'Double ',
+  single: '',
+  bull: 'Bullseye',
+  outerBull: 'Outer Bull',
+});
+custom[170].darts // ['Triple 20', 'Triple 20', 'Bullseye']
+```
+
+#### `NOTATIONS`
+Built-in notation presets:
+
+| Preset | Treble | Double | Single | Bull | 25 |
+|--------|--------|--------|--------|------|------|
+| `default` | `T20` | `D20` | `20` | `Bull` | `25` |
+| `british` | `T20` | `D20` | `S20` | `DB` | `SB` |
+| `american` | `T20` | `D20` | `20` | `DB` | `SB` |
+| `explicit` | `T20` | `D20` | `S20` | `Bull` | `25` |
+
+### Utilities
+
+#### `parseTarget(str)`
+Parses dart notation into components.
+
+```ts
+parseTarget('D16') // { bed: 'double', number: 16, value: 32 }
+parseTarget('T20') // { bed: 'treble', number: 20, value: 60 }
+parseTarget('Bull') // { bed: 'Bull', number: null, value: 50 }
+```
+
+#### `formatTarget(bed, number)`
+Inverse of `parseTarget` — formats a bed/number pair into label and value.
+
+### Types
+
+- `OutMode` — `'double' | 'single'`
+- `CheckoutEntry` — `{ darts: string[]; numDarts: number; alternates?: string[][] }`
+- `CheckoutChart` — `Record<number, CheckoutEntry>`
+- `ParsedTarget` — `{ bed: BedType; number: number | null; value: number }`
+- `NotationMap` — `{ treble: string; double: string; single: string; bull: string; outerBull: string }`
+- `OutsChartError` — Custom error class with semantic codes
+
+## Demo
+
+See the [live demo](https://tungstenstudio.gitlab.io/libs/outschart-generator/) for an interactive chart with preferred targets and export.
+
+## Development
+
+```bash
+npm install
+npm run test        # Run tests
+npm run typecheck   # Type-check
+npm run build       # Build ESM + CJS + DTS
+npm run build:demo  # Build demo IIFE bundle
+npm run dev         # Build demo and serve locally
+npm run verify      # Run all checks
+```
+
+## License
+
+ISC