@spotlab/range 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James DiGioia
+
+Permission 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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE 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.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @spotlab/range
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A poker range-string parser and serializer, compiled from Rust
+([`spotlab-range`](../../crates/spotlab-range)) to wasm. No React, no DOM —
+suitable for a Node script, a server, a CLI, or a browser/Electron renderer.
+
+```ts
+import { initRange, parseRange, formatRange } from "@spotlab/range";
+
+await initRange(); // once, at startup; idempotent, returns the same promise
+const hands = parseRange("AKs:0.5,QQ"); // synchronous from here on
+formatRange(hands); // "AKs:0.5,QQ"
+```
+
+## Why an explicit `initRange()`
+
+Instantiating a wasm module is asynchronous, and top-level `await` is not
+available in every consumer's bundle output — a CommonJS build has no way to
+express it. Call `initRange()` once at startup and await it; every other export
+is synchronous afterward, and throws `RangeNotInitializedError` if called
+before it resolves. `initRange()` itself is idempotent on success and
+retryable after a failure — a rejected call does not poison later calls.
+
+## No bundler step for consumers
+
+The `.wasm` binary is base64-inlined into the published JavaScript at build
+time (`scripts/inline-wasm.mjs`), so this package ships as a single
+self-contained ESM file with no binary asset, no `.wasm` import, and no
+loader configuration for the consumer — even though the package's own build
+bundles with Vite. The trade is roughly 33% extra payload size for
+eliminating bundler/asset-loading configuration across every consuming
+environment. The build asserts a size budget on the shipped bundle
+(`scripts/check-size.mjs`); see the package's `build:size` script.
+
+Concretely: the release `.wasm` is 132 KiB and the inlined module 176 KiB,
+and the overhead survives compression largely intact — roughly 28% gzipped.
+That is a deliberate trade for consumers loading from disk, where the
+absolute difference is immaterial. If you are serving this over a network
+and the overhead is material for you, please open an issue — shipping the
+raw `.wasm` alongside the inlined build, as a separate entry point, is
+straightforward and worth doing for a real use case.
+
+## Errors
+
+- `SpotlabInputError` — the input you gave was rejected: a range string
+  failed the grammar, a hand token didn't resolve to a combo, or a frequency
+  fell outside `[0, 1]`. `.kind` is `"invalid"` or `"frequencyOutOfRange"`.
+  Shared across `@spotlab` packages — a sibling package should reuse this
+  class rather than minting its own.
+- `RangeInitError` — `initRange()` could not instantiate the wasm module.
+  Carries the underlying failure as `.cause`.
+- `RangeNotInitializedError` — a function export other than `initRange` was
+  called before it resolved. `RANKS`, `SUITS`, and `COMBOS` are static data
+  generated from the Rust crate's own constants and are readable immediately,
+  with no `initRange()` call required.
+
+## License
+
+MIT — see `LICENSE`.

package/dist/errors.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The input you gave an `@spotlab/range` export was rejected: a range string
+ * failed the grammar, a hand token didn't resolve to a combo, or a frequency
+ * fell outside `[0, 1]`. Mirrors the Rust crate's `RangeParseError`,
+ * deserialized from the `#[serde(tag = "type", content = "data")]` shape the
+ * wasm shim throws across the boundary.
+ *
+ * This is the shared input-rejection error for `@spotlab` packages — a
+ * sibling package (e.g. `@spotlab/hand-matrix`) should reuse this class
+ * rather than minting its own.
+ *
+ * Deliberately not named `RangeError` — that is a JavaScript built-in.
+ */
+export declare class SpotlabInputError extends Error {
+    readonly name = "SpotlabInputError";
+    readonly kind: "invalid" | "frequencyOutOfRange";
+    readonly combo?: string;
+    readonly frequency?: number;
+    private constructor();
+    /**
+     * Build a `SpotlabInputError` from whatever the wasm boundary threw. A
+     * well-formed `RawSpotlabInputError` (itself the Rust crate's
+     * `RangeParseError`, serialized across the boundary) round-trips as-is;
+     * anything else (e.g. a raw deserialization failure at the `format_range` /
+     * `to_combo_weights` JS-value boundary, which cannot carry the structured
+     * Rust error) is wrapped as `kind: "invalid"` with the failure's own
+     * message.
+     */
+    static fromWasm(raw: unknown): SpotlabInputError;
+}
+/**
+ * `initRange()` could not instantiate the wasm module — corrupt bytes, no
+ * `WebAssembly` global, out of memory. Carries the underlying failure as
+ * `cause`. `initRange()` is retryable after this: see its own doc comment.
+ */
+export declare class RangeInitError extends Error {
+    readonly name = "RangeInitError";
+}
+/** Thrown when any export other than `initRange` is called before it has resolved. */
+export declare class RangeNotInitializedError extends Error {
+    readonly name = "RangeNotInitializedError";
+    constructor(fnName: string);
+}

package/dist/generated/constants.d.ts

@@ -0,0 +1,6 @@
+/** The 13 rank characters, ascending (`'2'..'A'`). */
+export declare const RANKS: readonly ["2", "3", "4", "5", "6", "7", "8", "9", "T", "J", "Q", "K", "A"];
+/** The 4 suit characters (`c`, `d`, `h`, `s`). */
+export declare const SUITS: readonly ["c", "d", "h", "s"];
+/** The 169 canonical combos in the hand matrix's row-major order. */
+export declare const COMBOS: readonly ["AA", "AKs", "AQs", "AJs", "ATs", "A9s", "A8s", "A7s", "A6s", "A5s", "A4s", "A3s", "A2s", "AKo", "KK", "KQs", "KJs", "KTs", "K9s", "K8s", "K7s", "K6s", "K5s", "K4s", "K3s", "K2s", "AQo", "KQo", "QQ", "QJs", "QTs", "Q9s", "Q8s", "Q7s", "Q6s", "Q5s", "Q4s", "Q3s", "Q2s", "AJo", "KJo", "QJo", "JJ", "JTs", "J9s", "J8s", "J7s", "J6s", "J5s", "J4s", "J3s", "J2s", "ATo", "KTo", "QTo", "JTo", "TT", "T9s", "T8s", "T7s", "T6s", "T5s", "T4s", "T3s", "T2s", "A9o", "K9o", "Q9o", "J9o", "T9o", "99", "98s", "97s", "96s", "95s", "94s", "93s", "92s", "A8o", "K8o", "Q8o", "J8o", "T8o", "98o", "88", "87s", "86s", "85s", "84s", "83s", "82s", "A7o", "K7o", "Q7o", "J7o", "T7o", "97o", "87o", "77", "76s", "75s", "74s", "73s", "72s", "A6o", "K6o", "Q6o", "J6o", "T6o", "96o", "86o", "76o", "66", "65s", "64s", "63s", "62s", "A5o", "K5o", "Q5o", "J5o", "T5o", "95o", "85o", "75o", "65o", "55", "54s", "53s", "52s", "A4o", "K4o", "Q4o", "J4o", "T4o", "94o", "84o", "74o", "64o", "54o", "44", "43s", "42s", "A3o", "K3o", "Q3o", "J3o", "T3o", "93o", "83o", "73o", "63o", "53o", "43o", "33", "32s", "A2o", "K2o", "Q2o", "J2o", "T2o", "92o", "82o", "72o", "62o", "52o", "42o", "32o", "22"];

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { Hand, HandFrequency } from './types.js';
+export { initRange } from './init.js';
+export declare const RANKS: readonly string[];
+export declare const SUITS: readonly string[];
+export declare const COMBOS: readonly string[];
+export { SpotlabInputError, RangeInitError, RangeNotInitializedError, } from './errors.js';
+export { Hand } from './types.js';
+export type { HandFrequency } from './types.js';
+/** Parse a range string into its expanded hand-keyed form. */
+export declare function parseRange(input: string): HandFrequency[];
+/** Render a hand-keyed range back to its compacted string form. */
+export declare function formatRange(hands: HandFrequency[]): string;
+/** The canonical combo a hand token belongs to (e.g. `AsKd` -> `AKo`). */
+export declare function comboOf(hand: string): string;
+/** Every concrete hand of a canonical combo, already canonical. */
+export declare function handsOfCombo(combo: string): Hand[];
+/**
+ * Collapse a hand-keyed range to the mean weight per combo. `serde-wasm-bindgen`
+ * serializes the underlying Rust map as a JS `Map`, not a plain object.
+ */
+export declare function toComboWeights(hands: HandFrequency[]): Map<string, number>;
+/** Every hand in the deck at weight 1 — the unconstrained range. */
+export declare function fullRange(): HandFrequency[];