kids-math-generator 1.0.0

package/README.md

@@ -0,0 +1,46 @@
+# @kids/math-generator
+
+A small TypeScript package to generate math questions for grades 1–6.
+
+- **Zero runtime dependencies**
+- **Deterministic option** via `seed`
+
+Key features
+- Generate grade-appropriate math questions (grades 1–6)
+- Difficulty levels: `easy`, `medium`, `hard`, `veryHard`
+- Mixed-operation questions (e.g., `(6 × 4) - 5 = ?`) for higher grades
+- Missing-operand (reverse) questions (e.g., `? × 12 = 144`) for advanced practice
+
+Quick usage (ESM):
+
+```ts
+import { generateQuestion } from '@kids/math-generator';
+
+// Explicit multiplication question
+const q1 = generateQuestion({ grade: 3, operation: 'mul', difficulty: 'easy', seed: 42 });
+console.log(q1.text, '→', q1.answer);
+
+// Explicit mixed question (available for grade >= 5)
+const mixed = generateQuestion({ grade: 5, operation: 'mixed', difficulty: 'hard', seed: 123 });
+console.log(mixed.text, '→', mixed.answer);
+
+// Missing-operand (reverse) question example
+// For deterministic transformation, import the helper and a RNG
+import { makeMissingOperandQuestion, makeRng } from '@kids/math-generator';
+
+const base = generateQuestion({ grade: 6, operation: 'add', difficulty: 'hard', seed: 7 });
+const rng = makeRng(1); // deterministic helper RNG
+const missing = makeMissingOperandQuestion(base, rng);
+console.log(missing.text, '→', missing.answer);
+```
+
+Notes
+- If `operation` is omitted, the generator will pick an operation appropriate for the grade and difficulty. For grades >= 5 and harder difficulties, it may produce mixed problems.
+- Missing-operand reverse questions are automatically produced sometimes for grade >= 6 when `difficulty` allows it; the `makeMissingOperandQuestion` helper is provided for explicit transformations.
+
+Run a quick sample/tests locally:
+
+```bash
+npm run build
+npm test
+```

package/dist/generators/add.d.ts

@@ -0,0 +1,7 @@
+import type { Difficulty, Grade, Question } from '../types.js';
+import type { RNG } from '../utils/random.js';
+export declare function generateAddQuestion(opts: {
+    grade: Grade;
+    difficulty: Difficulty;
+    rng: RNG;
+}): Question;

package/dist/generators/add.js

@@ -0,0 +1,27 @@
+import { getNumberRangeForGrade } from '../rules/gradeRules.js';
+import { getDifficultyModifiers } from '../rules/difficultyRules.js';
+export function generateAddQuestion(opts) {
+    const { grade, difficulty, rng } = opts;
+    const range = getNumberRangeForGrade(grade);
+    const modifiers = getDifficultyModifiers(difficulty);
+    // scale the max by difficulty modifiers
+    const maxVal = Math.max(range.min, Math.floor(range.max * modifiers.scale));
+    let a = rng.randInt(range.min, Math.max(range.min, maxVal));
+    let b = rng.randInt(range.min, Math.max(range.min, maxVal));
+    if (!modifiers.allowCarry) {
+        // ensure no carry in ones place
+        while (((a % 10) + (b % 10)) >= 10) {
+            b = rng.randInt(range.min, Math.max(range.min, maxVal));
+        }
+    }
+    const text = `${a} + ${b} = ?`;
+    const answer = a + b;
+    return {
+        text,
+        answer,
+        operation: 'add',
+        operands: [a, b],
+        grade,
+        difficulty,
+    };
+}

package/dist/generators/div.d.ts

@@ -0,0 +1,7 @@
+import type { Difficulty, Grade, Question } from '../types.js';
+import type { RNG } from '../utils/random.js';
+export declare function generateDivQuestion(opts: {
+    grade: Grade;
+    difficulty: Difficulty;
+    rng: RNG;
+}): Question;

package/dist/generators/div.js

@@ -0,0 +1,37 @@
+import { getNumberRangeForGrade } from '../rules/gradeRules.js';
+import { getDifficultyModifiers } from '../rules/difficultyRules.js';
+export function generateDivQuestion(opts) {
+    const { grade, difficulty, rng } = opts;
+    const range = getNumberRangeForGrade(grade);
+    const modifiers = getDifficultyModifiers(difficulty);
+    // For grade 3, pick multiplication table reverses (no remainder)
+    if (grade === 3) {
+        const b = rng.randInt(1, 10);
+        const answer = rng.randInt(1, 10);
+        const a = b * answer;
+        return {
+            text: `${a} ÷ ${b} = ?`,
+            answer,
+            operation: 'div',
+            operands: [a, b],
+            grade,
+            difficulty,
+        };
+    }
+    const maxDivisor = Math.max(1, Math.floor(range.max * modifiers.scale * 0.01));
+    const divisor = rng.randInt(1, maxDivisor);
+    let quotient = rng.randInt(0, Math.max(0, Math.floor(range.max * modifiers.scale * 0.01)));
+    let dividend = divisor * quotient;
+    if (modifiers.allowRemainder) {
+        // add a remainder smaller than divisor
+        dividend += rng.randInt(0, Math.max(0, divisor - 1));
+    }
+    return {
+        text: `${dividend} ÷ ${divisor} = ?`,
+        answer: Math.floor(dividend / divisor),
+        operation: 'div',
+        operands: [dividend, divisor],
+        grade,
+        difficulty,
+    };
+}

package/dist/generators/missing.d.ts

@@ -0,0 +1,3 @@
+import type { Question } from '../types.js';
+import type { RNG } from '../utils/random.js';
+export declare function makeMissingOperandQuestion(q: Question, rng: RNG): Question;

package/dist/generators/missing.js

@@ -0,0 +1,47 @@
+// Make a missing-operand (reverse) version of a question. It returns a new Question
+// where one operand is hidden with `?` and the answer is the hidden operand's value.
+export function makeMissingOperandQuestion(q, rng) {
+    // Only support textual replacement for typical forms.
+    const op = q.operation;
+    // Helper for binary operations (add, sub, mul, div)
+    if (op === 'add' || op === 'sub' || op === 'mul' || op === 'div') {
+        const [a, b] = q.operands;
+        const hideFirst = rng.randInt(0, 1) === 0;
+        let text = '';
+        let answer = 0;
+        const symbol = op === 'add' ? '+' : op === 'sub' ? '-' : op === 'mul' ? '×' : '÷';
+        if (hideFirst) {
+            // ? op b = result
+            text = `? ${symbol} ${b} = ${q.answer}`;
+            answer = a;
+        }
+        else {
+            // a op ? = result
+            text = `${a} ${symbol} ? = ${q.answer}`;
+            answer = b;
+        }
+        return {
+            ...q,
+            text,
+            answer,
+        };
+    }
+    // For mixed expressions, try replacing one of the operand numbers in the textual expression
+    const operandStrs = q.operands.map((n) => String(n));
+    const idx = rng.randInt(0, Math.max(0, operandStrs.length - 1));
+    const target = operandStrs[idx];
+    // Replace first full-token occurrence of target in text with '?'
+    // Use a regex with word boundaries to avoid partial matches
+    const escaped = target.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp('\\b' + escaped + '\\b');
+    let newText = q.text.replace(re, '?');
+    // If replacement didn't change text (unlikely), fallback to a simple replacement
+    if (newText === q.text) {
+        newText = q.text.replace(target, '?');
+    }
+    return {
+        ...q,
+        text: newText,
+        answer: Number(target),
+    };
+}

package/dist/generators/mixed.d.ts

@@ -0,0 +1,7 @@
+import type { Difficulty, Grade, Question } from '../types.js';
+import type { RNG } from '../utils/random.js';
+export declare function generateMixedQuestion(opts: {
+    grade: Grade;
+    difficulty: Difficulty;
+    rng: RNG;
+}): Question;

package/dist/generators/mixed.js

@@ -0,0 +1,54 @@
+import { getNumberRangeForGrade } from '../rules/gradeRules.js';
+import { getDifficultyModifiers } from '../rules/difficultyRules.js';
+export function generateMixedQuestion(opts) {
+    const { grade, difficulty, rng } = opts;
+    const range = getNumberRangeForGrade(grade);
+    const modifiers = getDifficultyModifiers(difficulty);
+    const max = Math.max(1, Math.floor(range.max * modifiers.scale));
+    // Choose a pattern suitable for the grade/difficulty
+    // Patterns:
+    // 0: (a × b) - c
+    // 1: (a × b) + c
+    // 2: (a + b) × c
+    // 3: (a - b) × c (ensure a-b >=0)
+    const pattern = rng.randInt(0, 3);
+    // Choose numbers with reasonable sizes
+    const a = rng.randInt(1, Math.max(1, Math.floor(Math.sqrt(max))));
+    const b = rng.randInt(1, Math.max(1, Math.floor(Math.sqrt(max))));
+    const c = rng.randInt(1, Math.max(1, Math.floor(Math.sqrt(max))));
+    let text = '';
+    let answer = 0;
+    switch (pattern) {
+        case 0:
+            // (a × b) - c
+            answer = a * b - c;
+            text = `(${a} × ${b}) - ${c} = ?`;
+            break;
+        case 1:
+            // (a × b) + c
+            answer = a * b + c;
+            text = `(${a} × ${b}) + ${c} = ?`;
+            break;
+        case 2:
+            // (a + b) × c
+            answer = (a + b) * c;
+            text = `(${a} + ${b}) × ${c} = ?`;
+            break;
+        case 3:
+        default:
+            // (a - b) × c ensure non-negative
+            const aa = Math.max(a, b);
+            const bb = Math.min(a, b);
+            answer = (aa - bb) * c;
+            text = `(${aa} - ${bb}) × ${c} = ?`;
+            break;
+    }
+    return {
+        text,
+        answer,
+        operation: 'mixed',
+        operands: [a, b, c],
+        grade,
+        difficulty,
+    };
+}

package/dist/generators/mul.d.ts

@@ -0,0 +1,7 @@
+import type { Difficulty, Grade, Question } from '../types.js';
+import type { RNG } from '../utils/random.js';
+export declare function generateMulQuestion(opts: {
+    grade: Grade;
+    difficulty: Difficulty;
+    rng: RNG;
+}): Question;

package/dist/generators/mul.js

@@ -0,0 +1,33 @@
+import { getNumberRangeForGrade } from '../rules/gradeRules.js';
+import { getDifficultyModifiers } from '../rules/difficultyRules.js';
+export function generateMulQuestion(opts) {
+    const { grade, difficulty, rng } = opts;
+    const range = getNumberRangeForGrade(grade);
+    const modifiers = getDifficultyModifiers(difficulty);
+    // For grade 3, use 1-10 tables; for higher grades increase digits scaled by difficulty
+    let a;
+    let b;
+    if (grade === 3) {
+        a = rng.randInt(1, 10);
+        b = rng.randInt(1, 10);
+    }
+    else if (grade === 4) {
+        a = rng.randInt(10, 99);
+        b = rng.randInt(2, 9);
+    }
+    else {
+        const maxA = Math.max(1, Math.floor(range.max * modifiers.scale * 0.1));
+        a = rng.randInt(1, Math.max(1, maxA));
+        b = rng.randInt(1, Math.max(1, Math.floor(12 * modifiers.scale)));
+    }
+    const text = `${a} × ${b} = ?`;
+    const answer = a * b;
+    return {
+        text,
+        answer,
+        operation: 'mul',
+        operands: [a, b],
+        grade,
+        difficulty,
+    };
+}

package/dist/generators/sub.d.ts

@@ -0,0 +1,7 @@
+import type { Difficulty, Grade, Question } from '../types.js';
+import type { RNG } from '../utils/random.js';
+export declare function generateSubQuestion(opts: {
+    grade: Grade;
+    difficulty: Difficulty;
+    rng: RNG;
+}): Question;

package/dist/generators/sub.js

@@ -0,0 +1,24 @@
+import { getNumberRangeForGrade } from '../rules/gradeRules.js';
+import { getDifficultyModifiers } from '../rules/difficultyRules.js';
+export function generateSubQuestion(opts) {
+    const { grade, difficulty, rng } = opts;
+    const range = getNumberRangeForGrade(grade);
+    const modifiers = getDifficultyModifiers(difficulty);
+    const maxVal = Math.max(range.min, Math.floor(range.max * modifiers.scale));
+    let a = rng.randInt(range.min, Math.max(range.min, maxVal));
+    let b = rng.randInt(range.min, Math.max(range.min, maxVal));
+    if (grade < 5) {
+        if (a < b)
+            [a, b] = [b, a];
+    }
+    const text = `${a} - ${b} = ?`;
+    const answer = a - b;
+    return {
+        text,
+        answer,
+        operation: 'sub',
+        operands: [a, b],
+        grade,
+        difficulty,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { Grade, Difficulty, Operation, Question } from './types.js';
+export declare function generateQuestion(options: {
+    grade: Grade;
+    operation?: Operation;
+    difficulty?: Difficulty;
+    seed?: number;
+}): Question;
+export { makeMissingOperandQuestion } from './generators/missing.js';
+export { makeRng } from './utils/random.js';
+export type { Grade, Difficulty, Operation, Question };

package/dist/index.js

@@ -0,0 +1,55 @@
+import { makeRng } from './utils/random.js';
+import { generateAddQuestion } from './generators/add.js';
+import { generateSubQuestion } from './generators/sub.js';
+import { generateMulQuestion } from './generators/mul.js';
+import { generateDivQuestion } from './generators/div.js';
+import { generateMixedQuestion } from './generators/mixed.js';
+import { makeMissingOperandQuestion } from './generators/missing.js';
+import { getDifficultyModifiers } from './rules/difficultyRules.js';
+export function generateQuestion(options) {
+    const { grade, operation, difficulty = 'easy', seed } = options;
+    const rng = makeRng(seed);
+    const modifiers = getDifficultyModifiers(difficulty);
+    // If operation is not specified, pick one. If mixed questions are allowed for the grade/difficulty,
+    // sometimes produce a mixed question.
+    let op;
+    if (operation) {
+        op = operation;
+    }
+    else {
+        if (grade >= 5 && modifiers.allowMixed && rng.rand() < 0.25) {
+            op = 'mixed';
+        }
+        else {
+            op = ['add', 'sub', 'mul', 'div'][Math.floor(rng.rand() * 4)];
+        }
+    }
+    let q;
+    switch (op) {
+        case 'add':
+            q = generateAddQuestion({ grade, difficulty, rng });
+            break;
+        case 'sub':
+            q = generateSubQuestion({ grade, difficulty, rng });
+            break;
+        case 'mul':
+            q = generateMulQuestion({ grade, difficulty, rng });
+            break;
+        case 'div':
+            q = generateDivQuestion({ grade, difficulty, rng });
+            break;
+        case 'mixed':
+            q = generateMixedQuestion({ grade, difficulty, rng });
+            break;
+        default:
+            throw new Error('Unsupported operation');
+    }
+    // Optionally transform into a missing-operand reverse question for higher grades/difficulties
+    if (grade >= 6 && modifiers.allowMissingOperand && rng.randInt(1, 100) <= 20) {
+        q = makeMissingOperandQuestion(q, rng);
+    }
+    return q;
+}
+// Convenience exports for advanced usage
+export { makeMissingOperandQuestion } from './generators/missing.js';
+export { makeRng } from './utils/random.js';

package/dist/rules/difficultyRules.d.ts

@@ -0,0 +1,9 @@
+import type { Difficulty } from '../types.js';
+export interface DifficultyModifiers {
+    scale: number;
+    allowCarry: boolean;
+    allowRemainder: boolean;
+    allowMissingOperand: boolean;
+    allowMixed: boolean;
+}
+export declare function getDifficultyModifiers(difficulty: Difficulty): DifficultyModifiers;

package/dist/rules/difficultyRules.js

@@ -0,0 +1,14 @@
+export function getDifficultyModifiers(difficulty) {
+    switch (difficulty) {
+        case 'easy':
+            return { scale: 0.2, allowCarry: false, allowRemainder: false, allowMissingOperand: false, allowMixed: false };
+        case 'medium':
+            return { scale: 0.5, allowCarry: true, allowRemainder: false, allowMissingOperand: false, allowMixed: false };
+        case 'hard':
+            return { scale: 0.85, allowCarry: true, allowRemainder: true, allowMissingOperand: true, allowMixed: true };
+        case 'veryHard':
+            return { scale: 1.0, allowCarry: true, allowRemainder: true, allowMissingOperand: true, allowMixed: true };
+        default:
+            return { scale: 0.5, allowCarry: true, allowRemainder: false, allowMissingOperand: false, allowMixed: false };
+    }
+}

package/dist/rules/gradeRules.d.ts

@@ -0,0 +1,5 @@
+import type { Grade } from '../types.js';
+export declare function getNumberRangeForGrade(grade: Grade): {
+    min: number;
+    max: number;
+};

package/dist/rules/gradeRules.js

@@ -0,0 +1,18 @@
+export function getNumberRangeForGrade(grade) {
+    switch (grade) {
+        case 1:
+            return { min: 0, max: 20 };
+        case 2:
+            return { min: 0, max: 100 };
+        case 3:
+            return { min: 0, max: 100 };
+        case 4:
+            return { min: 0, max: 1000 };
+        case 5:
+            return { min: 0, max: 10000 };
+        case 6:
+            return { min: 0, max: 100000 };
+        default:
+            return { min: 0, max: 100 };
+    }
+}

package/dist/test/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/index.js

@@ -0,0 +1,38 @@
+import * as assert from 'assert';
+import { generateQuestion } from '../index.js';
+import { makeMissingOperandQuestion } from '../generators/missing.js';
+import { makeRng } from '../utils/random.js';
+function runTests() {
+    console.log('Running basic tests...');
+    // Deterministic results with seed
+    const q1 = generateQuestion({ grade: 1, operation: 'add', difficulty: 'easy', seed: 42 });
+    assert.strictEqual(q1.operation, 'add');
+    assert.strictEqual(q1.grade, 1);
+    const q2 = generateQuestion({ grade: 3, operation: 'mul', difficulty: 'easy', seed: 42 });
+    assert.strictEqual(q2.operation, 'mul');
+    assert.ok(q2.answer >= 1);
+    // Subtraction for grade <5 should not be negative
+    const q3 = generateQuestion({ grade: 2, operation: 'sub', difficulty: 'medium', seed: 7 });
+    assert.ok(q3.answer >= 0, 'Subtraction produced negative answer for grade 2');
+    // Division for grade 3 should have integer answer (no remainder)
+    const q4 = generateQuestion({ grade: 3, operation: 'div', difficulty: 'easy', seed: 123 });
+    assert.strictEqual(q4.answer, Math.floor(q4.operands[0] / q4.operands[1]));
+    // Mixed operation test (explicit)
+    const q5 = generateQuestion({ grade: 5, operation: 'mixed', difficulty: 'hard', seed: 42 });
+    assert.strictEqual(q5.operation, 'mixed');
+    // Compute left-hand expression by parsing q5.text and evaluating (replace × and ÷)
+    const lh = q5.text.split('=')[0].replace(/×/g, '*').replace(/÷/g, '/');
+    // Evaluate safely by creating a Function
+    // eslint-disable-next-line no-new-func
+    const evaluated = Function(`return ${lh}`)();
+    assert.strictEqual(evaluated, q5.answer);
+    // Missing operand transformer test
+    const base = generateQuestion({ grade: 6, operation: 'add', difficulty: 'hard', seed: 7 });
+    const rng = makeRng(1);
+    const missing = makeMissingOperandQuestion(base, rng);
+    assert.ok(missing.text.includes('?'));
+    // missing.answer should equal one of the original operands
+    assert.ok(base.operands.includes(missing.answer));
+    console.log('All tests passed ✅');
+}
+runTests();

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+export type Grade = 1 | 2 | 3 | 4 | 5 | 6;
+export type Operation = 'add' | 'sub' | 'mul' | 'div' | 'mixed';
+export type Difficulty = 'easy' | 'medium' | 'hard' | 'veryHard';
+export interface Question {
+    text: string;
+    answer: number;
+    operation: Operation;
+    operands: number[];
+    grade: Grade;
+    difficulty: Difficulty;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/random.d.ts

@@ -0,0 +1,5 @@
+export type RNG = {
+    rand: () => number;
+    randInt: (min: number, max: number) => number;
+};
+export declare function makeRng(seed?: number): RNG;

package/dist/utils/random.js

@@ -0,0 +1,12 @@
+import { createSeededPRNG } from './seed.js';
+export function makeRng(seed) {
+    const base = createSeededPRNG(seed);
+    return {
+        rand: base,
+        randInt(min, max) {
+            if (min > max)
+                throw new Error('min > max');
+            return Math.floor(base() * (max - min + 1)) + min;
+        },
+    };
+}

package/dist/utils/seed.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A tiny seeded PRNG using a simple LCG. Returns a function that yields [0,1).
+ * Not cryptographically secure but deterministic and dependency-free.
+ */
+export declare function createSeededPRNG(seed?: number): () => number;

package/dist/utils/seed.js

@@ -0,0 +1,16 @@
+/**
+ * A tiny seeded PRNG using a simple LCG. Returns a function that yields [0,1).
+ * Not cryptographically secure but deterministic and dependency-free.
+ */
+export function createSeededPRNG(seed) {
+    if (seed === undefined || seed === null) {
+        return Math.random;
+    }
+    // Ensure a 32-bit unsigned seed
+    let state = seed >>> 0;
+    return function () {
+        // LCG parameters (Numerical Recipes)
+        state = (state * 1664525 + 1013904223) >>> 0;
+        return state / 0x100000000; // 2^32
+    };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+    "name": "kids-math-generator",
+    "version": "1.0.0",
+    "description": "Math question generator for grades 1-6",
+    "keywords": [
+        "math",
+        "generator",
+        "kids",
+        "math",
+        "additin",
+        "division",
+        "multiplication",
+        "division"
+    ],
+    "homepage": "https://github.com/serkanalgur/kids-math-generator#readme",
+    "bugs": {
+        "url": "https://github.com/serkanalgur/kids-math-generator/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/serkanalgur/kids-math-generator.git"
+    },
+    "license": "MIT",
+    "author": "Serkan Algur <kaisercrazy@gmail.com> (https://github.com/serkanalgur)",
+    "type": "module",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "test": "node dist/test/index.js",
+        "prepare": "npm run build"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "undici-types": "^7.16.0"
+    },
+    "devDependencies": {
+        "typescript": "^5.0.0",
+        "@types/node": "^25.0.3"
+    }
+}