{"id":27697906,"url":"https://github.com/robinl/maths-game-problem-generator","last_synced_at":"2025-04-25T16:24:41.635Z","repository":{"id":281453822,"uuid":"945332072","full_name":"RobinL/maths-game-problem-generator","owner":"RobinL","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-28T09:27:27.000Z","size":171,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T10:27:59.921Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RobinL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-09T06:53:46.000Z","updated_at":"2025-03-28T09:27:30.000Z","dependencies_parsed_at":"2025-03-09T07:38:01.950Z","dependency_job_id":null,"html_url":"https://github.com/RobinL/maths-game-problem-generator","commit_stats":null,"previous_names":["robinl/maths-game-problem-generator"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobinL%2Fmaths-game-problem-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobinL%2Fmaths-game-problem-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobinL%2Fmaths-game-problem-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobinL%2Fmaths-game-problem-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RobinL","download_url":"https://codeload.github.com/RobinL/maths-game-problem-generator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250851523,"owners_count":21497706,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-25T16:24:38.675Z","updated_at":"2025-04-25T16:24:41.627Z","avatar_url":"https://github.com/RobinL.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Math Problem Generator\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\u003c!-- Add other badges here if applicable, e.g., npm version, build status --\u003e\n\nA lightweight, dependency-free JavaScript library for generating curriculum-aligned math problems tailored for UK primary school students from Reception to Year 6.\n\n## Overview\n\nThis library provides a simple interface to generate age-appropriate math problems covering addition, subtraction, multiplication, division, and squared numbers. It's designed for educational applications, games, or practice tools targeting UK primary school children (ages 4-11).\n\nThe core functionality revolves around the `generateProblem` function, which creates a problem object containing the question (`expression`) and the `answer`. You can specify the desired `yearLevel` and `type` of problem, or let the library choose randomly based on typical curriculum expectations for the level. The `checkAnswer` function helps validate user input, handling numeric and string inputs gracefully, including tolerance for floating-point comparisons. Utility functions (`getYearLevels`, `getProblemTypes`) and constants (`YEAR_LEVELS`, `PROBLEM_TYPES`) are provided for convenience.\n\n## Key Features\n\n*   **Curriculum-Aligned:** Generates age-appropriate math problems for UK primary school students (Reception to Year 6, ages 4-11).\n*   **Variety of Problem Types:** Supports addition, subtraction, multiplication, division, and squared number problems.\n*   **Adaptive Difficulty:** Problems adjust complexity based on the specified year level.\n*   **Simple API:** Easy to integrate with just a few key functions.\n*   **Flexible Generation:** Specify year level, problem type, or let the library choose randomly.\n*   **Robust Answer Checking:** Handles numeric/string inputs and floating-point comparisons.\n*   **Zero Dependencies:** Lightweight and easy to add to any project.\n*   **ESM Format:** Modern JavaScript module format.\n\n## Installation\n\n```bash\nnpm install maths-game-problem-generator\n```\n\n*(Note: The package name in `package.json` is `maths-game-problem-generator`. Ensure your installation command matches this name).*\n\n## Quick Start\n\n```js\nimport { generateProblem, checkAnswer } from 'maths-game-problem-generator';\n\n// Generate a Year 3 division problem\nconst problem = generateProblem({\n  yearLevel: 'year3',\n  type: 'division'\n});\n\n// The problem object contains expression, answer, and other details\nconsole.log(`Problem: ${problem.expression}`); // Example: \"Problem: 36 ÷ 9\"\nconsole.log(`Answer: ${problem.answer}`);       // Example: \"Answer: 4\"\nconsole.log(`Formatted Answer: ${problem.formattedAnswer}`); // Example: \"Formatted Answer: 4\"\n\n// Check if a user's answer is correct\nconst userAnswer = 4;\nconst isCorrect = checkAnswer(problem, userAnswer);\nconsole.log(`Is the user's answer correct? ${isCorrect}`); // Output: \"Is the user's answer correct? true\"\n```\n\n## Usage Guide\n\nThis guide explains how to use the primary functions of the library.\n\n### Importing\n\nImport the necessary functions and constants from the library:\n\n```js\nimport {\n  generateProblem,\n  checkAnswer,\n  getYearLevels,\n  getProblemTypes,\n  YEAR_LEVELS,\n  PROBLEM_TYPES\n} from 'maths-game-problem-generator';\n\n// Or import the default object\nimport MathProblemGenerator from 'maths-game-problem-generator';\n// const problem = MathProblemGenerator.generateProblem(...);\n```\n\n### Generating Problems (`generateProblem`)\n\nThe `generateProblem` function creates a math problem.\n\n```js\n// Generate a problem with default options (Reception, random type)\nconst defaultProblem = generateProblem();\n\n// Generate a problem for a specific year level (random type)\nconst year2Problem = generateProblem({ yearLevel: 'year2' });\n// Using constants for year level:\nconst year4Problem = generateProblem({ yearLevel: YEAR_LEVELS.YEAR4 });\n\n// Generate a problem of a specific type (default year: Reception)\nconst additionProblem = generateProblem({ type: 'addition' });\n// Using constants for problem type:\nconst multiplicationProblem = generateProblem({ type: PROBLEM_TYPES.MULTIPLICATION });\n\n// Generate a problem for a specific year and type\nconst year5SquaredProblem = generateProblem({\n  yearLevel: YEAR_LEVELS.YEAR5,\n  type: PROBLEM_TYPES.SQUARED\n});\n```\n\nThe function returns a `Problem Object` with the following structure:\n\n*   `expression` (string): The full math problem expression (e.g., \"15 + 7\", \"Half 10\", \"√81\").\n*   `expression_short` (string): A potentially shorter version of the expression, suitable for constrained UI elements (e.g., \"15+7\", \"10÷2\", \"81mod5\"). Falls back to `expression` if no specific short version is defined.\n*   `answer` (number): The correct numerical answer.\n*   `formattedAnswer` (string): The answer formatted as a string, handling potential floating-point inaccuracies for display (e.g., \"0.1\" instead of \"0.1000000001\").\n*   `type` (string): The type of problem generated (e.g., 'addition', 'division').\n*   `yearLevel` (string): The year level the problem was generated for (e.g., 'year1', 'year6').\n\n### Checking Answers (`checkAnswer`)\n\nUse `checkAnswer` to validate a user's response against the problem's correct answer.\n\n```js\nconst problem = generateProblem({ yearLevel: 'year4', type: 'addition' }); // e.g., 45 + 55 = 100\nconsole.log(`Problem: ${problem.expression}`);\n\nlet userAnswer = 100;\nlet isCorrect = checkAnswer(problem, userAnswer);\nconsole.log(`Answer ${userAnswer} is correct? ${isCorrect}`); // true\n\nuserAnswer = \"100\"; // Handles string input\nisCorrect = checkAnswer(problem, userAnswer);\nconsole.log(`Answer \"${userAnswer}\" is correct? ${isCorrect}`); // true\n\nuserAnswer = 99;\nisCorrect = checkAnswer(problem, userAnswer);\nconsole.log(`Answer ${userAnswer} is correct? ${isCorrect}`); // false\n\n// Example with decimals\nconst decimalProblem = generateProblem({ yearLevel: 'year6', type: 'division' }); // e.g., 1 ÷ 4 = 0.25\nconsole.log(`Problem: ${decimalProblem.expression}`);\nisCorrect = checkAnswer(decimalProblem, 0.25); // true\nisCorrect = checkAnswer(decimalProblem, \"0.25\"); // true\nisCorrect = checkAnswer(decimalProblem, 0.250000001); // true (due to tolerance)\nisCorrect = checkAnswer(decimalProblem, 0.24); // false\n```\n\n### Getting Available Options\n\nYou can retrieve lists of supported year levels and problem types.\n\n```js\nconst availableYears = getYearLevels();\nconsole.log('Supported Year Levels:', availableYears);\n// Output: ['reception', 'year1', 'year2', 'year3', 'year4', 'year5', 'year6']\n\nconst availableTypes = getProblemTypes();\nconsole.log('Supported Problem Types:', availableTypes);\n// Output: ['addition', 'subtraction', 'multiplication', 'division', 'squared']\n```\n\n### Using Constants\n\nFor more readable and maintainable code, use the exported constants:\n\n```js\nimport { YEAR_LEVELS, PROBLEM_TYPES } from 'maths-game-problem-generator';\n\nconst problem = generateProblem({\n  yearLevel: YEAR_LEVELS.YEAR6,\n  type: PROBLEM_TYPES.DIVISION\n});\n```\n\n## API Reference\n\n### `generateProblem(options)`\n\nGenerates a math problem based on the specified options.\n\n*   **Parameters:**\n    *   `options` (Object): Configuration options.\n        *   `yearLevel` (string, optional): The school year level (see `YEAR_LEVELS`). Default: `'reception'`.\n        *   `type` (string, optional): The type of math problem (see `PROBLEM_TYPES`). Default: Randomly selected based on `yearLevel`.\n*   **Returns:**\n    *   `(Object)`: A problem object with the following properties:\n        *   `expression` (string): The math problem expression (e.g., \"25 + 17\").\n        *   `expression_short` (string): A shorter representation, if available (e.g., \"25+17\").\n        *   `answer` (number): The correct numerical answer (e.g., `42`).\n        *   `formattedAnswer` (string): The answer formatted as a string for display (e.g., `\"42\"`, `\"0.25\"`).\n        *   `type` (string): The problem type (e.g., `\"addition\"`).\n        *   `yearLevel` (string): The year level (e.g., `\"year3\"`).\n\n### `checkAnswer(problem, userAnswer)`\n\nChecks if a user's answer is correct for a given problem, handling type differences and floating-point tolerance.\n\n*   **Parameters:**\n    *   `problem` (Object): The problem object returned by `generateProblem`.\n    *   `userAnswer` (number | string): The user's submitted answer.\n*   **Returns:**\n    *   `(boolean)`: `true` if the `userAnswer` matches the `problem.answer` within tolerance, `false` otherwise. Returns `false` for non-numeric `userAnswer` strings.\n\n### `getYearLevels()`\n\nReturns an array of all available year level strings supported by the generator.\n\n*   **Returns:**\n    *   `Array\u003cstring\u003e`: List of available year levels (e.g., `['reception', 'year1', ..., 'year6']`).\n\n### `getProblemTypes()`\n\nReturns an array of all available problem type strings supported by the generator.\n\n*   **Returns:**\n    *   `Array\u003cstring\u003e`: List of available problem types (e.g., `['addition', 'subtraction', 'multiplication', 'division', 'squared']`).\n\n### Constants\n\nThe library exports constants for year levels and problem types for convenience and code clarity.\n\n```js\nimport { YEAR_LEVELS, PROBLEM_TYPES } from 'maths-game-problem-generator';\n\n// Example usage:\nconst level = YEAR_LEVELS.YEAR2; // equivalent to 'year2'\nconst type = PROBLEM_TYPES.SUBTRACTION; // equivalent to 'subtraction'\n```\n\n*   **`YEAR_LEVELS`**: An object mapping uppercase year level names to their string values (e.g., `YEAR_LEVELS.RECEPTION` -\u003e `'reception'`, `YEAR_LEVELS.YEAR1` -\u003e `'year1'`, ... `YEAR_LEVELS.YEAR6` -\u003e `'year6'`).\n*   **`PROBLEM_TYPES`**: An object mapping uppercase type names to their string values (e.g., `PROBLEM_TYPES.ADDITION` -\u003e `'addition'`, `PROBLEM_TYPES.SQUARED` -\u003e `'squared'`).\n\n## Year Levels and Problem Types\n\n### Supported Year Levels\n\n*   `reception`: Ages 4-5 (Numbers to 10, simple +/-).\n*   `year1`: Ages 5-6 (Numbers to 20, +/- within 20, basic ×/÷).\n*   `year2`: Ages 6-7 (Numbers to 100, 2-digit +/-, ×/÷ by 2, 5, 10).\n*   `year3`: Ages 7-8 (Numbers to 1000, mental +/-, ×/÷ by 3, 4, 8).\n*   `year4`: Ages 8-9 (Numbers beyond 1000, larger +/-, all tables ×/÷ up to 12x12).\n*   `year5`: Ages 9-10 (Large numbers, decimals, factors, basic squares/cubes, ×/÷ by powers of 10).\n*   `year6`: Ages 10-11 (Advanced decimals, fractions, percentages, complex mental strategies, square/cube recall).\n\n### Supported Problem Types\n\n*   `addition`: Addition problems.\n*   `subtraction`: Subtraction problems.\n*   `multiplication`: Multiplication problems.\n*   `division`: Division problems (including remainder problems in Year 4+).\n*   `squared`: Squared number problems (introduced formally around Year 5/6, simple versions earlier).\n\n## Examples\n\n### Generate problems of different types\n\n```js\nimport { generateProblem, PROBLEM_TYPES, YEAR_LEVELS } from 'maths-game-problem-generator';\n\n// Addition problem for Reception\nconst receptionAdd = generateProblem({\n  yearLevel: YEAR_LEVELS.RECEPTION,\n  type: PROBLEM_TYPES.ADDITION\n});\nconsole.log(receptionAdd);\n\n// Multiplication problem for Year 4\nconst year4Multiply = generateProblem({\n  yearLevel: YEAR_LEVELS.YEAR4,\n  type: PROBLEM_TYPES.MULTIPLICATION\n});\nconsole.log(year4Multiply);\n\n// Squared number problem for Year 6\nconst year6Square = generateProblem({\n  yearLevel: YEAR_LEVELS.YEAR6,\n  type: PROBLEM_TYPES.SQUARED\n});\nconsole.log(year6Square); // e.g., { expression: '√144', ..., answer: 12, ... }\n```\n\n### Generate multiple problems\n\n```js\nimport { generateProblem, YEAR_LEVELS } from 'maths-game-problem-generator';\n\n// Generate 5 random problems for Year 1\nconst problems = Array(5).fill().map(() =\u003e\n  generateProblem({ yearLevel: YEAR_LEVELS.YEAR1 })\n);\n\nproblems.forEach((p, i) =\u003e console.log(`Problem ${i+1}: ${p.expression} = ${p.formattedAnswer}`));\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues or pull requests on the GitHub repository.\n\n## License\n\n[MIT](LICENSE)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobinl%2Fmaths-game-problem-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobinl%2Fmaths-game-problem-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobinl%2Fmaths-game-problem-generator/lists"}