rootan-probability 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rootan (https://rootan.pro)
+
+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,148 @@
-# Temporary Holding Version
+# rootan-probability — คำนวณ RTP และค่าคาดหมายเพื่อการศึกษา
 
-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.
+ไลบรารี JavaScript/TypeScript ขนาดเล็กจาก [รู้ทัน (rootan.pro)](https://rootan.pro/) สำหรับคำนวณ **ผลขาดทุนคาดหมายจาก RTP** และ **ค่าคาดหมาย (expected value)** เพื่อการศึกษาเรื่องความน่าจะเป็นและความเสี่ยงจากการพนัน
+
+เหมาะกับนักพัฒนาที่ทำเนื้อหาหรือเครื่องมือสอนเรื่องความน่าจะเป็น ครูหรือผู้ทำสื่อการเรียนรู้ และผู้ที่อยากเห็นว่าค่าเฉลี่ยทางคณิตศาสตร์ทำงานอย่างไร เช่น RTP 96% หมายถึงอะไร หรือทำไมสูตรทบเงินจึงไม่เปลี่ยนค่าคาดหมาย
+
+- ไม่มี runtime dependencies
+- ESM พร้อม TypeScript declarations
+- ใช้ได้ทั้ง Node.js 18+ และเบราว์เซอร์ ไม่เรียกเครือข่ายและไม่เก็บข้อมูลผู้ใช้
+- ตรวจข้อมูลเข้าอย่างเข้มงวด ข้อมูลผิดจะ throw แทนการคืนตัวเลขที่ทำให้เข้าใจผิด
+
+> แพ็กเกจนี้ไม่ทำนายผล ไม่แนะนำเกมหรือเว็บใด และไม่ใช่สูตรทำกำไร ค่าคาดหมายคือค่าเฉลี่ยทางทฤษฎีในระยะยาว ผลจริงในระยะสั้นอาจต่างออกไปมาก
+
+## ติดตั้ง
+
+```sh
+npm install rootan-probability
+```
+
+## ตัวอย่างการใช้งาน
+
+ตัวเลขด้านล่างเป็นตัวอย่างสมมติ
+
+```js
+import { expectedLoss, expectedValue } from 'rootan-probability';
+
+// ยอดเดิมพันสะสม 10,000 บาท ที่ RTP สมมติ 96%
+expectedLoss(10_000, 96);
+// → 400 (โดยประมาณ เพราะเป็นทศนิยมของคอมพิวเตอร์)
+
+// ได้ −1 หรือ +1 ด้วยโอกาสเท่ากัน
+expectedValue([
+  { value: -1, probability: 0.5 },
+  { value: 1, probability: 0.5 },
+]);
+// → 0
+
+// เดิมพัน 1 ได้ +35 ถ้าถูก 1 ใน 37 ช่อง และเสีย 1 ถ้าไม่ถูก
+expectedValue([
+  { value: 35, probability: 1 / 37 },
+  { value: -1, probability: 36 / 37 },
+]);
+// → ประมาณ −0.027 ต่อการเดิมพัน 1 หน่วย
+```
+
+TypeScript ใช้ type `Outcome` ได้โดยตรง:
+
+```ts
+import { expectedValue, type Outcome } from 'rootan-probability';
+
+const outcomes: Outcome[] = [{ value: 2, probability: 1 }];
+const ev: number = expectedValue(outcomes); // 2
+```
+
+### ตัวอย่าง: สูตรทบเงินเปลี่ยนค่าคาดหมายได้ไหม
+
+เกมสมมติที่โอกาสชนะแต่ละตา 48% ได้หรือเสียเท่าเงินที่วาง ถ้าใช้สูตรทบเงิน (เพิ่มเดิมพันเท่าตัวหลังเสีย) สูงสุด 3 ตา โดยเริ่มที่ 1 หน่วย
+
+```js
+const lose = 0.52; // โอกาสแพ้แต่ละตา
+
+expectedValue([
+  { value: 1, probability: 0.48 },               // ชนะตาแรก
+  { value: 1, probability: lose * 0.48 },        // แพ้ 1 ตาแล้วชนะ: −1 + 2
+  { value: 1, probability: lose ** 2 * 0.48 },   // แพ้ 2 ตาแล้วชนะ: −1 − 2 + 4
+  { value: -7, probability: lose ** 3 },         // แพ้รวด 3 ตา: −1 − 2 − 4
+]);
+// → ประมาณ −0.125
+```
+
+สูตรนี้ได้ +1 บ่อยถึงราว 86% ของรอบ จึงดูเหมือนได้ผล แต่รอบที่แพ้รวดเสีย 7 หน่วย ค่าคาดหมายรวมจึงยังติดลบ ทบเงินเปลี่ยนแค่รูปแบบการได้เสีย ไม่ได้ทำให้เกมที่ติดลบกลายเป็นบวก อ่านตัวอย่างตัวเลขเพิ่มเติมใน[สูตรทบเงินได้ผลจริงไหม](https://rootan.pro/articles/baccarat-doubling/)
+
+### ใช้ในเบราว์เซอร์
+
+ใช้ผ่าน CDN ที่รองรับ ESM ได้ เช่น
+
+```html
+<script type="module">
+  import { expectedLoss } from 'https://esm.sh/rootan-probability@0.1.0';
+  console.log(expectedLoss(10000, 96));
+</script>
+```
+
+## API
+
+### `expectedLoss(totalStaked, rtpPercent)`
+
+คืนค่า `totalStaked × (1 − rtpPercent ÷ 100)`
+
+RTP (Return to Player) คือสัดส่วนการจ่ายคืนเฉลี่ยในระยะยาว RTP 96% จึงหมายถึงผลขาดทุนคาดหมายประมาณ 4% ของยอดเดิมพันสะสม ไม่ได้แปลว่าเดิมพัน 100 บาทแล้วจะได้คืน 96 บาททุกครั้ง
+
+| พารามิเตอร์ | ชนิด | ขอบเขต | ความหมาย |
+|---|---|---|---|
+| `totalStaked` | `number` | 0 ถึง 100,000,000 | ยอดเดิมพันสะสม นับทุกครั้งที่เดิมพัน ไม่ใช่ยอดฝาก |
+| `rtpPercent` | `number` | 0 ถึง 100 | RTP เป็นเปอร์เซ็นต์ |
+
+ผลลัพธ์: `number` ผลขาดทุนคาดหมายตามทฤษฎี
+
+### `expectedValue(outcomes)`
+
+คืนผลรวมของ `value × probability` ของทุกผลลัพธ์
+
+| พารามิเตอร์ | ชนิด | ขอบเขต | ความหมาย |
+|---|---|---|---|
+| `outcomes` | `Outcome[]` | ไม่ว่าง | รายการผลลัพธ์ที่เป็นไปได้ทั้งหมด |
+| `outcomes[i].value` | `number` | จำนวนจำกัด | ได้ (บวก) หรือเสีย (ลบ) เมื่อเกิดผลลัพธ์นี้ |
+| `outcomes[i].probability` | `number` | 0 ถึง 1 | โอกาสเกิดผลลัพธ์นี้ ทุกรายการรวมกันต้องเป็น 1 |
+
+ผลลัพธ์: `number` ค่าบวกหมายถึงได้เฉลี่ย ค่าลบหมายถึงเสียเฉลี่ย ต่อหนึ่งครั้งในระยะยาว
+
+ผลรวม probability ต่างจาก 1 ได้ไม่เกิน `1e-12` เพื่อรองรับทศนิยมของคอมพิวเตอร์ ฟังก์ชันจะไม่ปรับสัดส่วนให้เองเงียบ ๆ
+
+### ข้อผิดพลาด
+
+| กรณี | Error |
+|---|---|
+| อาร์กิวเมนต์ไม่ใช่ `number` เช่น string, `undefined`, BigInt | `TypeError` |
+| `outcomes` ไม่ใช่ array หรือรายการไม่ใช่ object | `TypeError` |
+| ค่าเป็น `NaN` หรือ `Infinity` | `RangeError` |
+| ค่าอยู่นอกขอบเขตในตาราง | `RangeError` |
+| `outcomes` ว่าง หรือ probability รวมไม่เป็น 1 | `RangeError` |
+| ผลคำนวณล้นเป็น `Infinity` | `RangeError` |
+
+### ค่าคงที่
+
+- `MAX_TOTAL_STAKED` = `100_000_000`
+- `PROBABILITY_TOLERANCE` = `1e-12`
+
+## ข้อจำกัด
+
+- **ค่าคาดหมายไม่ใช่ผลที่รับประกัน** เป็นค่าเฉลี่ยเมื่อทำซ้ำจำนวนมาก ผลจริงในช่วงสั้นอาจได้หรือเสียมากกว่านี้มาก
+- **ไม่บอกโอกาสหมดเงิน** และไม่ได้จำลองการกระจายรางวัลหรือความผันผวน RTP ค่าเดียวไม่พอสำหรับจำลองผลจริง
+- **ยอดเดิมพันสะสมต่างจากยอดฝาก** ถ้าเงินเดิมถูกนำไปเดิมพันซ้ำ ยอดสะสม (เทิร์นโอเวอร์) จะสูงกว่ายอดฝากหลายเท่า ดูวิธีคิดใน[เทิร์นโอเวอร์คืออะไร](https://rootan.pro/articles/turnover-explained/)
+- **ตัวเลขเป็น floating point** ผลลัพธ์ไม่ได้ปัดเป็นสกุลเงิน ให้ชั้นแสดงผลจัดรูปแบบเอง เช่น `toLocaleString` และเปรียบเทียบผลด้วย tolerance แทนการเท่ากันทุกบิต
+
+## อ่านต่อบนรู้ทัน
+
+- [ทดลองเครื่องมือคำนวณบนรู้ทัน](https://rootan.pro/tools/) — กรอกยอดเดิมพันสะสมและ RTP แล้วดูผลขาดทุนคาดหมายทันที
+- [RTP คืออะไร? RTP 96% ไม่ได้แปลว่าจะได้เงินคืน 96 บาท](https://rootan.pro/articles/rtp-explained/) — ความต่างระหว่างค่าเฉลี่ยระยะยาวกับผลการเล่นจริง
+- [บทความหมวดความน่าจะเป็นทั้งหมด](https://rootan.pro/topics/probability/) — ตัวเลขเบื้องหลังเกมและความเข้าใจผิดที่พบบ่อย
+
+หากการพนันเริ่มกระทบเงิน งาน หรือความสัมพันธ์ ดู[ช่องทางขอความช่วยเหลือ](https://rootan.pro/help/) หรือโทรสายด่วนสุขภาพจิต 1323
+
+## รายงานปัญหาและใบอนุญาต
+
+พบปัญหาหรือมีข้อเสนอ แจ้งได้ที่ [หน้าติดต่อรู้ทัน](https://rootan.pro/contact/)
+
+เผยแพร่ภายใต้ [MIT License](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * rootan-probability — คำนวณค่าคาดหมายเพื่อการศึกษา
+ * ไม่ทำนายผลจริง ไม่มี dependencies ไม่เรียกเครือข่าย
+ * https://rootan.pro/tools/
+ */
+/** ยอดเดิมพันสะสมสูงสุดที่รับได้ (เท่ากับขอบเขตเครื่องมือบน rootan.pro) */
+export declare const MAX_TOTAL_STAKED = 100000000;
+/** ผลรวม probability ต่างจาก 1 ได้ไม่เกินค่านี้ เพื่อรองรับทศนิยมของคอมพิวเตอร์ */
+export declare const PROBABILITY_TOLERANCE = 1e-12;
+/** ผลลัพธ์หนึ่งแบบ: ได้/เสีย `value` ด้วยโอกาส `probability` (0–1) */
+export interface Outcome {
+    readonly value: number;
+    readonly probability: number;
+}
+/**
+ * ผลขาดทุนคาดหมายจาก RTP: `totalStaked × (1 − rtpPercent ÷ 100)`
+ *
+ * `totalStaked` คือยอดเดิมพันสะสม (นับทุกครั้งที่เดิมพัน) ไม่ใช่ยอดฝาก
+ * ผลที่ได้เป็นค่าเฉลี่ยทางทฤษฎี ไม่ใช่ยอดที่จะเสียจริง และไม่บอกโอกาสหมดเงิน
+ *
+ * @param totalStaked ยอดเดิมพันสะสม 0 ถึง 100,000,000
+ * @param rtpPercent RTP เป็นเปอร์เซ็นต์ 0 ถึง 100
+ * @throws {TypeError} เมื่ออาร์กิวเมนต์ไม่ใช่ number
+ * @throws {RangeError} เมื่อเป็น NaN, Infinity หรืออยู่นอกขอบเขต
+ * @example expectedLoss(10_000, 96) // ≈ 400
+ */
+export declare function expectedLoss(totalStaked: number, rtpPercent: number): number;
+/**
+ * ค่าคาดหมาย: ผลรวมของ `value × probability` ของทุกผลลัพธ์
+ *
+ * probability ต้องรวมเป็น 1 (คลาดเคลื่อนได้ไม่เกิน 1e-12) ฟังก์ชันไม่ปรับสัดส่วนให้เอง
+ * ค่าบวกหมายถึงได้เฉลี่ย ค่าลบหมายถึงเสียเฉลี่ย ต่อการเล่นหนึ่งครั้งในระยะยาวตามทฤษฎี
+ *
+ * @param outcomes รายการผลลัพธ์ที่ไม่ว่าง
+ * @throws {TypeError} เมื่อ outcomes ไม่ใช่ array หรือรายการมีชนิดข้อมูลผิด
+ * @throws {RangeError} เมื่อรายการว่าง ค่าไม่จำกัด probability นอก 0–1 หรือรวมไม่เป็น 1
+ * @example expectedValue([{ value: -1, probability: 0.5 }, { value: 1, probability: 0.5 }]) // 0
+ */
+export declare function expectedValue(outcomes: readonly Outcome[]): number;

package/dist/index.js

@@ -0,0 +1,83 @@
+/**
+ * rootan-probability — คำนวณค่าคาดหมายเพื่อการศึกษา
+ * ไม่ทำนายผลจริง ไม่มี dependencies ไม่เรียกเครือข่าย
+ * https://rootan.pro/tools/
+ */
+/** ยอดเดิมพันสะสมสูงสุดที่รับได้ (เท่ากับขอบเขตเครื่องมือบน rootan.pro) */
+export const MAX_TOTAL_STAKED = 100000000;
+/** ผลรวม probability ต่างจาก 1 ได้ไม่เกินค่านี้ เพื่อรองรับทศนิยมของคอมพิวเตอร์ */
+export const PROBABILITY_TOLERANCE = 1e-12;
+function assertFiniteNumber(value, name) {
+    if (typeof value !== 'number') {
+        throw new TypeError(`${name} must be a number, received ${typeof value}`);
+    }
+    if (!Number.isFinite(value)) {
+        throw new RangeError(`${name} must be a finite number, received ${value}`);
+    }
+}
+function assertInRange(value, min, max, name) {
+    if (value < min || value > max) {
+        throw new RangeError(`${name} must be between ${min} and ${max}, received ${value}`);
+    }
+}
+function assertFiniteResult(result) {
+    if (!Number.isFinite(result)) {
+        throw new RangeError('result is not a finite number');
+    }
+    return result;
+}
+/**
+ * ผลขาดทุนคาดหมายจาก RTP: `totalStaked × (1 − rtpPercent ÷ 100)`
+ *
+ * `totalStaked` คือยอดเดิมพันสะสม (นับทุกครั้งที่เดิมพัน) ไม่ใช่ยอดฝาก
+ * ผลที่ได้เป็นค่าเฉลี่ยทางทฤษฎี ไม่ใช่ยอดที่จะเสียจริง และไม่บอกโอกาสหมดเงิน
+ *
+ * @param totalStaked ยอดเดิมพันสะสม 0 ถึง 100,000,000
+ * @param rtpPercent RTP เป็นเปอร์เซ็นต์ 0 ถึง 100
+ * @throws {TypeError} เมื่ออาร์กิวเมนต์ไม่ใช่ number
+ * @throws {RangeError} เมื่อเป็น NaN, Infinity หรืออยู่นอกขอบเขต
+ * @example expectedLoss(10_000, 96) // ≈ 400
+ */
+export function expectedLoss(totalStaked, rtpPercent) {
+    assertFiniteNumber(totalStaked, 'totalStaked');
+    assertFiniteNumber(rtpPercent, 'rtpPercent');
+    assertInRange(totalStaked, 0, MAX_TOTAL_STAKED, 'totalStaked');
+    assertInRange(rtpPercent, 0, 100, 'rtpPercent');
+    return assertFiniteResult(totalStaked * (1 - rtpPercent / 100));
+}
+/**
+ * ค่าคาดหมาย: ผลรวมของ `value × probability` ของทุกผลลัพธ์
+ *
+ * probability ต้องรวมเป็น 1 (คลาดเคลื่อนได้ไม่เกิน 1e-12) ฟังก์ชันไม่ปรับสัดส่วนให้เอง
+ * ค่าบวกหมายถึงได้เฉลี่ย ค่าลบหมายถึงเสียเฉลี่ย ต่อการเล่นหนึ่งครั้งในระยะยาวตามทฤษฎี
+ *
+ * @param outcomes รายการผลลัพธ์ที่ไม่ว่าง
+ * @throws {TypeError} เมื่อ outcomes ไม่ใช่ array หรือรายการมีชนิดข้อมูลผิด
+ * @throws {RangeError} เมื่อรายการว่าง ค่าไม่จำกัด probability นอก 0–1 หรือรวมไม่เป็น 1
+ * @example expectedValue([{ value: -1, probability: 0.5 }, { value: 1, probability: 0.5 }]) // 0
+ */
+export function expectedValue(outcomes) {
+    if (!Array.isArray(outcomes)) {
+        throw new TypeError('outcomes must be an array');
+    }
+    if (outcomes.length === 0) {
+        throw new RangeError('outcomes must not be empty');
+    }
+    let total = 0;
+    let probabilitySum = 0;
+    outcomes.forEach((outcome, index) => {
+        if (typeof outcome !== 'object' || outcome === null) {
+            throw new TypeError(`outcomes[${index}] must be an object with value and probability`);
+        }
+        const { value, probability } = outcome;
+        assertFiniteNumber(value, `outcomes[${index}].value`);
+        assertFiniteNumber(probability, `outcomes[${index}].probability`);
+        assertInRange(probability, 0, 1, `outcomes[${index}].probability`);
+        total += value * probability;
+        probabilitySum += probability;
+    });
+    if (Math.abs(probabilitySum - 1) > PROBABILITY_TOLERANCE) {
+        throw new RangeError(`probabilities must sum to 1, received ${probabilitySum}`);
+    }
+    return assertFiniteResult(total);
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "rootan-probability",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "คำนวณผลขาดทุนคาดหมายจาก RTP และค่าคาดหมาย (expected value) เพื่อการศึกษา ไม่มี dependencies ใช้ได้ทั้ง Node.js และเบราว์เซอร์",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/index.test.mjs",
+    "prepack": "npm run build && npm test"
+  },
+  "keywords": [
+    "probability",
+    "expected-value",
+    "rtp",
+    "return-to-player",
+    "expected-loss",
+    "house-edge",
+    "martingale",
+    "education",
+    "math",
+    "thai"
+  ],
+  "homepage": "https://rootan.pro/tools/",
+  "bugs": {
+    "url": "https://rootan.pro/contact/"
+  },
+  "license": "MIT",
+  "author": "รู้ทัน (https://rootan.pro)",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}