@coffeeandfun/maths-captcha
Version:
Maths-Captcha is a simple Node.js module that generates random math questions to verify human interaction. It creates math problems like addition, subtraction, multiplication, division, powers, percentages, sequences, and algebra, and checks if the user's
386 lines (282 loc) • 11.1 kB
Markdown
# 🧮 @coffeeandfun/maths-captcha
A small Node.js library that generates simple maths questions and checks the answers. Use it as a friendly alternative to image based CAPTCHAs. ✨
Examples of what it can ask:
- `7 + 3`
- `25% of 80`
- `√64`
- `2x + 3 = 11`
- `2, 4, 6, 8, ?`
It runs in plain JavaScript. There are no servers to call, no images to load, and no fonts to download.
## 📦 Install
```bash
npm install @coffeeandfun/maths-captcha
```
Requires Node.js 16 or newer.
## 🚀 Quick start
```js
import {
generateRandomMathQuestion,
validateAnswer,
} from '@coffeeandfun/maths-captcha';
const question = generateRandomMathQuestion();
console.log(question.question);
// "7 + 3"
const isCorrect = validateAnswer(question, '10');
console.log(isCorrect);
// true
```
That's the whole loop: generate a question, show it to the user, then check what they typed.
## 📝 What you get back
Every question is a plain object with the same shape:
```js
{
question: '7 + 3', // The text to show the user
answer: '10', // The correct answer as a string
numericAnswer: 10, // The correct answer as a number
operation: '+', // The operator or category
operands: [7, 3], // The numbers used to build the question
type: 'arithmetic', // Which question type produced it
}
```
Some types add a `style` field (for example, `square`, `cube`, `geometric`).
## 🎲 Question types
By default the library only asks basic arithmetic. You can switch on more types when you want harder or more varied questions.
| Type | Example | Notes |
| ------------ | ---------------- | ------------------------------------ |
| `arithmetic` | `7 + 3` | `+` `-` `*` `/` and `%` (modulo) |
| `power` | `5^2`, `√64` | Squares, cubes, perfect square roots |
| `percentage` | `25% of 80` | Always whole-number answers |
| `pemdas` | `(2 + 3) * 4` | Order of operations |
| `solve-x` | `2x + 3 = 11` | Solve for `x` |
| `sequence` | `2, 4, 6, 8, ?` | Arithmetic and geometric patterns |
Turn on extra types with `setConfig`:
```js
import {
setConfig,
generateRandomMathQuestion,
} from '@coffeeandfun/maths-captcha';
setConfig({
QUESTION_TYPES: ['arithmetic', 'power', 'percentage', 'solve-x'],
});
const question = generateRandomMathQuestion();
// e.g. { question: '√64', answer: '8', type: 'power', style: 'sqrt', ... }
```
## ✅ Checking answers
There are three ways to check an answer. Pick the one that fits how strict you want to be.
### `validateAnswer(question, userAnswer)`
Strict. Whole numbers must be typed as whole numbers.
```js
validateAnswer({ answer: '15' }, '15'); // ✅ true
validateAnswer({ answer: '15' }, '15.0'); // ❌ false
validateAnswer({ answer: '15' }, '16'); // ❌ false
```
### `validateAnswerFlexible(question, userAnswer)`
Friendly. Accepts the same number written different ways.
```js
const q = { answer: '4.00', numericAnswer: 4, operation: '/' };
validateAnswerFlexible(q, '4'); // ✅ true
validateAnswerFlexible(q, '4.0'); // ✅ true
validateAnswerFlexible(q, '4.00'); // ✅ true
validateAnswerFlexible(q, '3.99'); // ❌ false
```
### `validateAnswerWithFeedback(question, userAnswer)`
Returns an object that explains the result. Useful when you want to show the user why their answer was wrong.
```js
validateAnswerWithFeedback(question, 'abc');
// {
// isValid: false,
// reason: 'Invalid numeric format',
// userInput: 'abc',
// expected: '10'
// }
```
### Batch checks
If you have many answers to check at once:
```js
validateAnswers([
{ question: q1, answer: '10' },
{ question: q2, answer: '7' },
]);
// [
// { question: '5 + 5', isValid: true, expectedAnswer: '10' },
// { question: '14 - 7', isValid: true, expectedAnswer: '7' },
// ]
```
## ⚙️ Configuration
```js
import {
setConfig,
getConfig,
resetConfig,
} from '@coffeeandfun/maths-captcha';
setConfig({
DIVISION_PRECISION: 3,
NUMBER_RANGE: { min: 1, max: 50 },
OPERATIONS: ['+', '-', '*'],
QUESTION_TYPES: ['arithmetic', 'power'],
AVOID_NEGATIVE_RESULTS: true,
AVOID_DIVISION_BY_ZERO: true,
});
getConfig(); // Read the current settings
resetConfig(); // Restore the defaults
```
### Default settings
| Option | Default |
| ------------------------ | ---------------------- |
| `DIVISION_PRECISION` | `2` |
| `NUMBER_RANGE` | `{ min: 1, max: 100 }` |
| `OPERATIONS` | `['+', '-', '*', '/']` |
| `QUESTION_TYPES` | `['arithmetic']` |
| `AVOID_NEGATIVE_RESULTS` | `true` |
| `AVOID_DIVISION_BY_ZERO` | `true` |
| `MAX_ATTEMPTS` | `10` |
| `TOLERANCE` | `1e-10` |
### Difficulty examples
Easy mode for kids:
```js
setConfig({
QUESTION_TYPES: ['arithmetic'],
OPERATIONS: ['+'],
NUMBER_RANGE: { min: 1, max: 10 },
});
```
Harder mode for adults:
```js
setConfig({
QUESTION_TYPES: ['arithmetic', 'pemdas', 'solve-x', 'sequence'],
NUMBER_RANGE: { min: 1, max: 50 },
});
```
## 📚 Generating in bulk
```js
import { generateMultipleQuestions } from '@coffeeandfun/maths-captcha';
const ten = generateMultipleQuestions(10);
```
## 🎯 Generating with limits
If you need a question that fits specific bounds:
```js
import { generateQuestionWithConstraints } from '@coffeeandfun/maths-captcha';
const easy = generateQuestionWithConstraints({
operations: ['+'],
numberRange: { min: 1, max: 10 },
maxResult: 20,
});
```
If the library cannot produce a question that fits, it throws. Wrap the call in a `try` block if you want to handle that.
## 🔌 Adding your own question type
You can plug in your own generator. It just needs to return a question object in the standard shape.
```js
import {
registerQuestionType,
setConfig,
generateRandomMathQuestion,
} from '@coffeeandfun/maths-captcha';
registerQuestionType('double', () => {
const n = Math.floor(Math.random() * 20) + 1;
return {
question: `Double ${n}`,
answer: String(n * 2),
numericAnswer: n * 2,
operation: 'custom',
operands: [n],
type: 'double',
};
});
setConfig({ QUESTION_TYPES: ['double'] });
generateRandomMathQuestion();
// { question: 'Double 7', answer: '14', ... }
```
To remove it later:
```js
import { unregisterQuestionType } from '@coffeeandfun/maths-captcha';
unregisterQuestionType('double');
```
To see every type that is currently available:
```js
import { listQuestionTypes } from '@coffeeandfun/maths-captcha';
listQuestionTypes();
// ['arithmetic', 'power', 'percentage', 'pemdas', 'solve-x', 'sequence', 'double']
```
## 🌐 Using it with Express
Generate the question on the server and store it in the session. Validate the answer on the server too. Never trust the client to check itself.
```js
import express from 'express';
import session from 'express-session';
import {
generateRandomMathQuestion,
validateAnswer,
} from '@coffeeandfun/maths-captcha';
const app = express();
app.use(express.json());
app.use(session({
secret: 'change-me',
resave: false,
saveUninitialized: true,
}));
app.get('/captcha', (req, res) => {
const question = generateRandomMathQuestion();
req.session.captcha = question;
res.json({ question: question.question });
});
app.post('/verify', (req, res) => {
const correct = validateAnswer(req.session.captcha, req.body.answer);
res.json({ correct });
});
```
## 📖 API reference
### Generators
| Function | What it does |
| ----------------------------------------------------- | ------------------------------------------------- |
| `generateRandomMathQuestion(precisionOrConfig?)` | Returns one question. |
| `generateMultipleQuestions(count, precisionOrConfig?)`| Returns an array of questions. |
| `generateQuestionWithConstraints(constraints)` | Returns a question that fits the given limits. |
| `registerQuestionType(name, generator)` | Adds your own question type. |
| `unregisterQuestionType(name)` | Removes a custom question type. |
| `listQuestionTypes()` | Lists every available type. |
### Validators
| Function | What it does |
| ----------------------------------------- | ------------------------------------------------ |
| `validateAnswer(question, answer)` | Strict check. Returns `true` or `false`. |
| `validateAnswerStrict(question, answer)` | The same as `validateAnswer`. Kept for clarity. |
| `validateAnswerFlexible(question, answer)`| Accepts equivalent decimal forms. |
| `validateAnswerWithFeedback(question, a)` | Returns an object explaining the result. |
| `validateAnswers(pairs)` | Checks many `{ question, answer }` pairs at once.|
| `checkIfSolvedCorrectly(question, answer)`| Alias for `validateAnswer`. |
### Configuration
| Function | What it does |
| ----------------- | ------------------------------------------- |
| `getConfig()` | Returns a copy of the current settings. |
| `setConfig(obj)` | Merges `obj` into the active settings. |
| `resetConfig()` | Restores the default settings. |
### Helpers
| Function | What it does |
| --------------------------------- | ---------------------------------------------------------------------- |
| `getQuestionStats(question)` | Returns `{ operands, result, operation, difficulty, hasDecimals }`. |
| `calculateDifficulty(question)` | Returns a difficulty score from 1 to 10. |
| `normalizeNumericString(value)` | Trims trailing zeros from a numeric string. For example, `5.00` → `5`. |
## 🧪 Testing
```bash
npm test # Run every test
npm run v1 # Run only the version 1 tests
npm run v2 # Run only the version 2 tests
npm run v3 # Run only the version 3 tests
```
The library ships with 87 tests covering question generation, every validator, edge cases, and the new question types.
## ⬆️ Upgrading from version 2
Version 3 is a clean rewrite split into small modules. The public API is the same, so existing code keeps working without changes. The new features (extra question types, custom generators, `resetConfig`) are opt in.
If you only ever called `generateRandomMathQuestion` and `validateAnswer`, you do not need to change anything.
## 📄 License
MIT. See [LICENSE](LICENSE). 🧡