{"id":20852311,"url":"https://github.com/minizinc/minizinc-js","last_synced_at":"2025-04-07T09:16:31.781Z","repository":{"id":63393076,"uuid":"563650452","full_name":"MiniZinc/minizinc-js","owner":"MiniZinc","description":"Use MiniZinc in the browser or with NodeJS","archived":false,"fork":false,"pushed_at":"2025-03-10T08:30:49.000Z","size":1212,"stargazers_count":38,"open_issues_count":3,"forks_count":8,"subscribers_count":10,"default_branch":"develop","last_synced_at":"2025-03-31T08:12:20.663Z","etag":null,"topics":["constraint-programming","integer-programming","javascript","linear-programming","minizinc","nodejs","optimisation-problem","sat-solver","typescript-definitions","webassembly"],"latest_commit_sha":null,"homepage":"https://js.minizinc.dev","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MiniZinc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2022-11-09T03:16:51.000Z","updated_at":"2025-03-25T15:24:12.000Z","dependencies_parsed_at":"2024-05-10T07:23:30.325Z","dependency_job_id":"582cd390-7a34-461a-a7dd-0a45af4d5dcc","html_url":"https://github.com/MiniZinc/minizinc-js","commit_stats":{"total_commits":70,"total_committers":4,"mean_commits":17.5,"dds":0.5142857142857142,"last_synced_commit":"a6a82c5ff3f2ec96223ce7e077b6f25d46ae88b7"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MiniZinc%2Fminizinc-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MiniZinc%2Fminizinc-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MiniZinc%2Fminizinc-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MiniZinc%2Fminizinc-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MiniZinc","download_url":"https://codeload.github.com/MiniZinc/minizinc-js/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247622988,"owners_count":20968575,"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":["constraint-programming","integer-programming","javascript","linear-programming","minizinc","nodejs","optimisation-problem","sat-solver","typescript-definitions","webassembly"],"created_at":"2024-11-18T03:17:10.676Z","updated_at":"2025-04-07T09:16:31.759Z","avatar_url":"https://github.com/MiniZinc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"JavaScript interface for MiniZinc\n=================================\n\n[![Latest documentation](https://img.shields.io/badge/docs-latest-blue)](https://js.minizinc.dev/docs/stable)\n[![Latest package](https://img.shields.io/npm/v/minizinc/latest?color=blue)](https://www.npmjs.com/package/minizinc)\n[![Edge documentation](https://img.shields.io/badge/docs-edge-orange)](https://js.minizinc.dev/docs/develop)\n[![Edge package](https://img.shields.io/npm/v/minizinc/edge?color=orange)](https://www.npmjs.com/package/minizinc)\n\nThis package provides a JavaScript API for [MiniZinc](https://minizinc.dev)\nfor use in web browsers using WebAssembly, or in NodeJS using a native\ninstallation of MiniZinc.\n\nThis library powers the [MiniZinc Playground](https://minizinc.dev/solve).\n\n## Getting started\n\n### Using a CDN (recommended)\n\nUsing ECMAScript modules:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import { Model } from 'https://cdn.jsdelivr.net/npm/minizinc/dist/minizinc.mjs';\n  const model = new Model();\n  model.addFile('test.mzn', 'var 1..3: x;');\n  const solve = model.solve({\n    options: {\n      solver: 'gecode',\n      'all-solutions': true\n    }\n  });\n  solve.on('solution', solution =\u003e {\n    console.log(solution.output.json);\n  });\n  solve.then(result =\u003e {\n    console.log(result.status);\n  });\n\u003c/script\u003e\n```\n\nUsing a traditional script:\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/minizinc/dist/minizinc.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  const model = new MiniZinc.Model();\n  model.addFile('test.mzn', 'var 1..3: x;');\n  const solve = model.solve({\n    options: {\n      solver: 'gecode',\n      'all-solutions': true\n    }\n  });\n  solve.on('solution', solution =\u003e {\n    console.log(solution.output.json);\n  });\n  solve.then(result =\u003e {\n    console.log(result.status);\n  });\n\u003c/script\u003e\n```\n\n### Self-hosting WebAssembly files\n\nIf you're using a bundler, you can add the library to your project:\n\n```sh\nnpm install minizinc\n```\n\nThen import it with:\n\n```js\nimport * as MiniZinc from 'minizinc';\n```\n\nThese three files need to be served by your webserver (found in `node_modules/minizinc/dist`):\n\n- `minizinc-worker.js`\n- `minizinc.wasm`\n- `minizinc.data`\n\nIf you place them alongside your bundled script, they should be found automatically.\nOtherwise, their URLs can be specified during [initialisation](#initialisation).\n\n### In NodeJS\n\nThis requires an existing [installation of MiniZinc](https://github.com/MiniZinc/MiniZincIDE/releases).\n\nAdd the library with:\n\n```sh\nnpm install minizinc\n```\n\nThen import it with:\n\n```js\n// If using ESM\nimport * as MiniZinc from 'minizinc';\n// If using CommonJS\nconst MiniZinc = require('minizinc');\n```\n\nIf you have added MiniZinc to your `PATH`, it will be found automatically.\nOtherwise, you can specify the executable path during [initialisation](#initialisation).\n\n## Usage\n\n### Initialisation\n\nInitialisation happens automatically when the library is used, or by calling\n[`init(...)`](https://js.minizinc.dev/docs/stable/functions/init.html). This can be used to ensure\nthat the WebAssembly files start loading immediately, or to specify a different URL for the worker\n(or path to the MiniZinc executable if using NodeJS).\n\nIn the browser:\n\n```js\nMiniZinc.init({\n  // If omitted, searches for minizinc-worker.js next to the minizinc library script\n  workerURL: 'http://localhost:3000/path/to/my-own-worker.js',\n  // If these are omitted, searches next to the worker script\n  wasmURL: 'http://localhost:3000/path/to/minizinc.wasm',\n  dataURL: 'http://localhost:3000/path/to/minizinc.data'\n}).then(() =\u003e {\n  console.log('Ready');\n});\n```\n\nIn NodeJS:\n\n```js\nMiniZinc.init({\n  // Executable name\n  minizinc: 'minizinc',\n  // Search paths (can omit to use PATH)\n  minizincPaths: ['/home/me/.local/bin', '/usr/local/bin']\n});\n```\n\nBy default, the NodeJS version tries to find MiniZinc on your `PATH`.\n\n### Creating Models\n\nThe main entrypoint for using the library is through the\n[`Model`](https://js.minizinc.dev/docs/stable/classes/Model.html) class:\n\n```js\nconst model = new MiniZinc.Model();\n// Add a file with a given name and string contents\nmodel.addFile('test.mzn', 'var 1..3: x; int: y;');\n// If you're using NodeJS, you can add files from the filesystem directly\nmodel.addFile('test.mzn');\n// Add model code from a string\nmodel.addString('int: z;');\n// Add data in DZN format\nmodel.addDznString('y = 1;');\n// Add data from a JSON object\nmodel.addJSON({z: 2});\n```\n\n### Solving\n\nSolving is done using the [`Model.solve(...)`](https://js.minizinc.dev/docs/stable/classes/Model.html#solve) method,\nwhich takes an object with `options` in [`.mpc`](https://minizinc.dev/doc-latest/en/command_line.html#ch-param-files)\nformat.\n\n```js\nconst solve = model.solve({\n  options: {\n    solver: 'gecode',\n    'time-limit': 10000,\n    statistics: true\n  }\n});\n// You can listen for events\nsolve.on('solution', solution =\u003e console.log(solution.output.json));\nsolve.on('statistics', stats =\u003e console.log(stats.statistics));\n// And/or wait until complete\nsolve.then(result =\u003e {\n  console.log(result.solution.output.json);\n  console.log(result.statistics);\n});\n```\n\nDuring solving, MiniZinc emits events which can be subscribed to/unsubscribed from using the\n[`SolveProgress.on`](https://js.minizinc.dev/docs/stable/interfaces/SolveProgress.html#on) /\n[`SolveProgress.off`](https://js.minizinc.dev/docs/stable/interfaces/SolveProgress.html#off)\nmethods. The events are those which appear in\n[Machine-readable JSON output format](https://minizinc.dev/doc-latest/en/json-stream.html),\nwith the addition of the [`exit`](https://js.minizinc.dev/docs/stable/interfaces/ExitMessage.html)\nevent, which can be used to detect when solving finishes (if you do not wish to await the \n[`SolveProgress`](https://js.minizinc.dev/docs/stable/interfaces/SolveProgress.html) object).\n\nBy default, `--output-mode json` is used, allowing you to retrieve the model variable values\ndirectly from the solution objects. Use\n[`Model.solve({ jsonOutput: false, ...})`](https://js.minizinc.dev/docs/stable/classes/Model.html#solve)\n(and optionally specify a different `output-mode` in the `options`) to disable this behaviour.\n\n## Documentation\n\nFor more detailed documentation of all available options and functionality, visit the \n[API documentation](https://js.minizinc.dev/docs/stable/).\n\n## Building\n\n### Compiling MiniZinc for WebAssembly \n\nThe WebAssembly build of MiniZinc requires [Emscripten](https://emscripten.org/).\n\n```sh\n# Clone MiniZinc\ngit clone https://github.com/MiniZinc/libminizinc minizinc\n\n# Download solvers (or you can build them yourself using emscripten)\ncd minizinc\nMZNARCH=wasm ./download_vendor\n\n# Configure MiniZinc\nemcmake cmake -S . -B build \\\n  -DCMAKE_FIND_ROOT_PATH=\"/\" \\\n  -DCMAKE_BUILD_TYPE=Release \\\n  -DGecode_ROOT=\"$PWD/vendor/gecode\" \\\n  -DOsiCBC_ROOT=\"$PWD/vendor/cbc\" \\\n  -DCMAKE_PREFIX_PATH=\"$PWD/vendor/highs/lib/cmake/highs:$PWD/vendor/chuffed/lib/cmake/chuffed\" \\\n  -DCMAKE_INSTALL_PREFIX=\"../minizinc-install\"\n\n# Build MiniZinc\ncmake --build build --config Release --target install\n```\n\nThe WebAssembly build of MiniZinc can also be obtained from the [build workflow](https://github.com/MiniZinc/minizinc-js/actions/workflows/build.yml) as the `minizinc` artifact.\n\n### Building MiniZinc JS\n\n1. Run `npm install` to install dependencies.\n2. Place the `bin/` folder of the WebAssembly build of MiniZinc inside this directory.\n   Alternatively set the `MZN_WASM_DIR` environment variable to the installation directory of the\n   WebAssembly build of MiniZinc.\n3. Run `npm run build` to build the package. The built files are in the `dist/` directory.\n4. Run `npm run docs` to build the documentation. The output files are in the `docs/` directory.\n\n## Testing\n\nWhen testing, the [`web-worker`](https://www.npmjs.com/package/web-worker) library is used to emulate Web Worker\nsupport in NodeJS. This allows us to test both the browser version using WebAssembly, as well as the native version.\n\nRun `npm test` to run tests using [Jest](https://jestjs.io).\n\n## License\n\nThis library is distributed under the Mozilla Public License Version 2.0. See LICENSE for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminizinc%2Fminizinc-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fminizinc%2Fminizinc-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminizinc%2Fminizinc-js/lists"}