@zephyr424/wb-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zephyr424
+
+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

@@ -0,0 +1,271 @@
+# wb-sdk
+
+> A developer-friendly spaced repetition engine for vocabulary building
+
+[![npm version](https://img.shields.io/npm/v/wb-sdk.svg)](https://www.npmjs.com/package/wb-sdk)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Zephyr424/wb-sdk/blob/main/LICENSE)
+
+**wb-sdk** is a lightweight, plug-and-play spaced repetition engine designed for developers who want to integrate intelligent vocabulary review into their applications.
+
+Stop reinventing the wheel — just `npm install wb-sdk` and start building.
+
+---
+
+## ✨ Features
+
+- 🧠 **SM-2 Algorithm** — Industry-standard spaced repetition, proven to optimize memory retention
+- 📚 **Built-in Word Management** — Add, search, remove, and organize words effortlessly
+- 🔁 **Review Scheduling** — Automatically calculates what to review and when
+- 📊 **Progress Tracking** — Get stats on mastered words, retention rate, and future review forecasts
+- 🧩 **Minimal API** — Intuitive `wb.word` and `wb.review` interfaces
+- 📦 **Zero Dependencies** — Lightweight and fast, no bloat
+
+---
+
+## 🚀 Installation
+
+```bash
+npm install wb-sdk
+```
+### Or with Yarn:
+```bash
+yarn add wb-sdk
+```
+
+---
+
+## 🏃 Quick Start
+```javascripts
+const { WordBank } = require('wb-sdk');
+
+// Create a new word bank
+const wb = new WordBank();
+
+// Add some words
+wb.word.add({ id: '1', word: 'apple', definition: 'a fruit' });
+wb.word.add({ id: '2', word: 'benevolent', definition: 'kind and generous' });
+wb.word.add({ id: '3', word: 'ephemeral', definition: 'lasting for a short time' });
+
+// See all words
+console.log(wb.word.list());
+
+// Get today's review queue
+const due = wb.review.getDue();
+console.log(`📚 ${due.length} words due for review today:`);
+due.forEach(w => console.log(`  - ${w.word}: ${w.definition}`));
+
+// Submit a review (quality: 0 = forgot, 5 = perfect recall)
+wb.review.submit('1', 4);  // "apple" reviewed with quality 4/5
+
+// Check your progress
+console.log(wb.review.progress());
+// { total: 3, mastered: 0, remaining: 3, daysToMaster: 1 }
+```
+
+---
+
+## 📖 API Documentation
+
+### `wb.word` — Word Management
+
+| Method | Parameters | Returns | Description |
+| :--- | :--- | :--- | :--- |
+| `list()` | — | `Word[]` | Returns all words in the bank |
+| `get(id)` | `id: string` | `Word \| null` | Retrieves a word by ID, returns `null` if not found |
+| `add(data)` | `data: WordData` | `Word` | Adds a new word to the bank |
+| `remove(id)` | `id: string` | `void` | Deletes a word from the bank |
+| `search(keyword)` | `keyword: string` | `Word[]` | Searches words by word or definition (case‑insensitive) |
+| `top(n)` | `n: number` | `Word[]` | Returns the top `n` words with the most review repetitions |
+
+**Usage Examples:**
+
+```javascript
+// List all words
+wb.word.list();
+
+// Get by ID
+wb.word.get('apple');
+
+// Add a new word
+wb.word.add({ id: 'grok', word: 'grok', definition: 'to understand intuitively' });
+
+// Remove by ID
+wb.word.remove('grok');
+
+// Search
+wb.word.search('bene');  // Returns ["benevolent", "beneficial", ...]
+
+// Top 10 most practiced
+wb.word.top(10);
+```
+---
+
+### `wb.review` — Review Scheduling
+
+| Method | Parameters | Returns | Description |
+| :--- | :--- | :--- | :--- |
+| `getDue([today])` | `today?: Date` | `Word[]` | Returns all words due for review today (or on a custom date) |
+| `submit(id, quality)` | `id: string, quality: number` | `Word` | Records your review performance and updates SM‑2 state |
+| `forecast([days])` | `days?: number` | `Object` | Predicts how many words will be due each day for the next N days |
+| `progress()` | — | `Object` | Returns an overview of your learning progress |
+
+**Usage Examples:**
+
+```javascript
+// Get today's review queue
+const due = wb.review.getDue();
+console.log(`📚 ${due.length} words due today`);
+
+// Get due words on a specific date
+const dueOnChristmas = wb.review.getDue(new Date('2026-12-25'));
+
+// Submit a review with quality 4/5
+const updated = wb.review.submit('apple', 4);
+console.log(`Next review in ${updated.interval} days`);
+
+// Forecast review load for the next 7 days
+const forecast = wb.review.forecast(7);
+console.log(forecast);
+// { "2026-09-01": 5, "2026-09-02": 8, "2026-09-03": 3, ... }
+
+// Get overall progress stats
+const stats = wb.review.progress();
+console.log(stats);
+// { total: 5000, mastered: 1200, remaining: 3800, daysToMaster: 760 }
+```
+**`quality` — Review Quality Scale:**
+
+| Score | Meaning |
+| :--- | :--- |
+| `5` | Perfect recall |
+| `4` | Good recall, slight hesitation |
+| `3` | Recalled with difficulty |
+| `2` | Forgot, but recognized |
+| `1` | Almost forgot |
+| `0` | Completely forgot |
+
+**`progress()` — Return Fields:**
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `total` | `number` | Total words in the bank |
+| `mastered` | `number` | Words with interval ≥ 30 days |
+| `remaining` | `number` | Words not yet mastered |
+| `daysToMaster` | `number` | Estimated days until all words are mastered |
+
+### 📋 Summary Table — All Methods
+
+| Module | Method | Brief |
+| :--- | :--- | :--- |
+| `wb.word` | `list()` | Get all words |
+| `wb.word` | `get(id)` | Get word by ID |
+| `wb.word` | `add(data)` | Add a new word |
+| `wb.word` | `remove(id)` | Delete a word |
+| `wb.word` | `search(keyword)` | Search words |
+| `wb.word` | `top(n)` | Get most practiced words |
+| `wb.review` | `getDue([today])` | Get review queue |
+| `wb.review` | `submit(id, quality)` | Submit review |
+| `wb.review` | `forecast([days])` | Predict review load |
+| `wb.review` | `progress()` | Get learning stats |
+| `—` | `loadPreset(name)` | Load built-in word list |
+
+---
+
+## 🧠 How It Works
+
+wb-sdk implements the **SM-2 algorithm**, the same one used by Anki and other popular flashcard apps. Each time you review a word and rate your recall (0–5), the engine:
+
+- Adjusts the word's **ease factor** based on your performance
+- Calculates the optimal **next review interval**
+- Tracks your **progress** and predicts future review workload
+
+This ensures you spend time on words you're about to forget — maximizing efficiency.
+
+---
+
+## 📦 Built-in Example
+
+The package includes an example script that demonstrates the core features of `wb-sdk` in action.
+
+### Run the example
+
+Make sure you are in the project root directory, then execute:
+
+```bash
+node example.js
+```
+
+### What it does
+
+The example:
+- Creates a new `WordBank` instance
+- Loads a built-in preset of 3 demo words (`apple`, `book`, `cat`)
+- Lists all words
+- Retrieves today's due words (initially all words are due)
+- Submits a review for the first word with quality `4` (good recall)
+- Shows learning progress stats
+- Prints a 7‑day forecast of review load
+
+### Expected output (sample)
+
+```text
+All words: [
+  Word { id: '1', word: 'apple', definition: 'a fruit', ... },
+  Word { id: '2', word: 'book', definition: 'a set of pages', ... },
+  Word { id: '3', word: 'cat', definition: 'a small animal', ... }
+]
+
+Words due for review today:
+- apple: a fruit
+- book: a set of pages
+- cat: a small animal
+
+Submitted review for apple (quality 4/5)
+
+Learning progress: { total: 3, mastered: 0, remaining: 3, daysToMaster: 1 }
+
+7-day review forecast: {
+  '2026-09-01': 0,
+  '2026-09-02': 0,
+  '2026-09-03': 1,
+  '2026-09-04': 0,
+  '2026-09-05': 0,
+  '2026-09-06': 0,
+  '2026-09-07': 0
+}
+```
+**Note**: The actual output may vary slightly depending on the current date and your review history.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! If you have ideas, bug fixes, or improvements, feel free to:
+
+- Open an [issue](https://github.com/Zephyr424/wb-sdk/issues) to report bugs or suggest features
+- Submit a [pull request](https://github.com/Zephyr424/wb-sdk/pulls) with your changes
+
+Please make sure your code follows the existing style and includes appropriate tests if applicable.
+
+Thank you for helping make `wb-sdk` better!
+
+---
+
+## 📄 License
+
+MIT © [Zephyr424](https://github.com/Zephyr424)
+
+See the [LICENSE](./LICENSE) file for details.；
+
+---
+
+## ⭐ Show Your Support
+
+If you find `wb-sdk` useful, please consider giving it a star ⭐ on GitHub — it means a lot and helps others discover the project.
+
+Thank you for using `wb-sdk`!
+
+---
+
+> Built with ❤️ by a developer who believes learning should be smart, not hard.
+---

package/example.js

@@ -0,0 +1,27 @@
+const { WordBank } = require('./index');
+
+// 创建一个词库实例
+const wb = new WordBank();
+
+// 加载内置演示词库
+wb.loadPreset('demo');
+
+console.log('所有单词:', wb.word.list());
+
+// 模拟复习
+console.log('\n今天需要复习的单词:');
+const due = wb.review.getDue();
+due.forEach(w => console.log(`- ${w.word}: ${w.definition}`));
+
+// 模拟提交复习反馈（假设对第一个词评价为4分）
+if (due.length > 0) {
+  const first = due[0];
+  wb.review.submit(first.id, 4);
+  console.log(`\n已提交复习: ${first.word} (质量4/5)`);
+}
+
+// 查看进度
+console.log('\n学习进度:', wb.review.progress());
+
+// 显示预测未来7天复习量
+console.log('\n未来7天预测复习量:', wb.review.forecast(7));

package/index.js

@@ -0,0 +1,2 @@
+const WordBank = require('./src/wordBank');
+module.exports = WordBank;

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@zephyr424/wb-sdk",
+  "version": "0.1.0",
+  "description": "A developer-friendly spaced repetition engine for vocabulary building",
+  "main": "index.js",
+  "scripts": {
+    "test": "node example.js"
+  },
+  "keywords": ["vocabulary", "spaced-repetition", "flashcards", "learning"],
+  "author": "Your Name",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yourusername/wb-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/wb-sdk/issues"
+  },
+  "homepage": "https://github.com/yourusername/wb-sdk#readme"
+}

package/src/models.js

@@ -0,0 +1,32 @@
+class Word {
+  constructor({ id, word, definition, repetitions = 0, interval = 0, easeFactor = 2.5, lastReviewed = null }) {
+    this.id = id;
+    this.word = word;
+    this.definition = definition;
+    this.repetitions = repetitions;
+    this.interval = interval;
+    this.easeFactor = easeFactor;
+    this.lastReviewed = lastReviewed ? new Date(lastReviewed) : null;
+  }
+
+  isDue(today = new Date()) {
+    if (!this.lastReviewed) return true;
+    const dueDate = new Date(this.lastReviewed);
+    dueDate.setDate(dueDate.getDate() + this.interval);
+    return today >= dueDate;
+  }
+
+  toJSON() {
+    return {
+      id: this.id,
+      word: this.word,
+      definition: this.definition,
+      repetitions: this.repetitions,
+      interval: this.interval,
+      easeFactor: this.easeFactor,
+      lastReviewed: this.lastReviewed ? this.lastReviewed.toISOString() : null
+    };
+  }
+}
+
+module.exports = Word;

package/src/reviewManager.js

@@ -0,0 +1,39 @@
+const Scheduler = require('./scheduler');
+
+class ReviewManager {
+  constructor(parent) {
+    this.parent = parent;
+  }
+
+  getDue(today = new Date()) {
+    return this.parent.word.list().filter(w => w.isDue(today));
+  }
+
+  submit(id, quality) {
+    const word = this.parent.word.get(id);
+    if (!word) throw new Error(`Word with id ${id} not found`);
+    return Scheduler.schedule(word, quality);
+  }
+
+  forecast(days = 7, from = new Date()) {
+    const forecast = {};
+    for (let i = 1; i <= days; i++) {
+      const d = new Date(from);
+      d.setDate(d.getDate() + i);
+      const due = this.parent.word.list().filter(w => w.isDue(d)).length;
+      forecast[d.toISOString().slice(0,10)] = due;
+    }
+    return forecast;
+  }
+
+  progress() {
+    const words = this.parent.word.list();
+    const total = words.length;
+    const mastered = words.filter(w => w.interval >= 30).length;
+    const remaining = total - mastered;
+    const daysToMaster = Math.ceil(remaining / 5);
+    return { total, mastered, remaining, daysToMaster };
+  }
+}
+
+module.exports = ReviewManager;

package/src/scheduler.js

@@ -0,0 +1,25 @@
+class Scheduler {
+  static schedule(word, quality) {
+    const now = new Date();
+    if (quality < 3) {
+      word.repetitions = 0;
+      word.interval = 1;
+    } else {
+      if (word.repetitions === 0) {
+        word.interval = 1;
+      } else if (word.repetitions === 1) {
+        word.interval = 6;
+      } else {
+        word.interval = Math.round(word.interval * word.easeFactor);
+      }
+      word.repetitions += 1;
+      let ease = word.easeFactor + (0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02));
+      ease = Math.min(2.5, Math.max(1.3, ease));
+      word.easeFactor = ease;
+    }
+    word.lastReviewed = now;
+    return word;
+  }
+}
+
+module.exports = Scheduler;

package/src/wordBank.js

@@ -0,0 +1,29 @@
+const WordManager = require('./wordManager');
+const ReviewManager = require('./reviewManager');
+
+class WordBank {
+  constructor(initialWords = []) {
+    this.words = {};
+    this.word = new WordManager(this);
+    this.review = new ReviewManager(this);
+
+    if (initialWords && initialWords.length) {
+      initialWords.forEach(w => this.word.add(w));
+    }
+  }
+
+  loadPreset(name) {
+    const presets = {
+      demo: [
+        { id: '1', word: 'apple', definition: 'a fruit' },
+        { id: '2', word: 'book', definition: 'a set of pages' },
+        { id: '3', word: 'cat', definition: 'a small animal' }
+      ]
+    };
+    const words = presets[name];
+    if (!words) throw new Error(`Preset ${name} not found`);
+    words.forEach(w => this.word.add(w));
+  }
+}
+
+module.exports = WordBank;

package/src/wordManager.js

@@ -0,0 +1,39 @@
+const Word = require('./models');
+
+class WordManager {
+  constructor(parent) {
+    this.parent = parent;
+  }
+
+  list() {
+    return Object.values(this.parent.words);
+  }
+
+  get(id) {
+    return this.parent.words[id] || null;
+  }
+
+  add(wordData) {
+    const word = new Word(wordData);
+    this.parent.words[word.id] = word;
+    return word;
+  }
+
+  remove(id) {
+    delete this.parent.words[id];
+  }
+
+  search(keyword) {
+    const lower = keyword.toLowerCase();
+    return this.list().filter(w =>
+      w.word.toLowerCase().includes(lower) ||
+      w.definition.toLowerCase().includes(lower)
+    );
+  }
+
+  top(n) {
+    return this.list().sort((a, b) => b.repetitions - a.repetitions).slice(0, n);
+  }
+}
+
+module.exports = WordManager;