{"id":14155511,"url":"https://github.com/mtmr0x/nucleo","last_synced_at":"2026-04-17T19:33:28.795Z","repository":{"id":33568236,"uuid":"138371058","full_name":"mtmr0x/nucleo","owner":"mtmr0x","description":"🏋️‍♀️ Nucleo is a strongly typed and predictable state container library for JavaScript ecosystem written in TypeScript","archived":false,"fork":false,"pushed_at":"2025-02-19T14:24:28.000Z","size":882,"stargazers_count":113,"open_issues_count":2,"forks_count":3,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-10-08T02:51:24.612Z","etag":null,"topics":["flux","javascript","nucleo","redux","state-management","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mtmr0x.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null}},"created_at":"2018-06-23T04:25:21.000Z","updated_at":"2024-07-11T00:09:40.000Z","dependencies_parsed_at":"2024-06-21T18:55:29.206Z","dependency_job_id":"f65a7423-6f04-4073-b150-f6305ff03a0f","html_url":"https://github.com/mtmr0x/nucleo","commit_stats":{"total_commits":114,"total_committers":5,"mean_commits":22.8,"dds":0.2543859649122807,"last_synced_commit":"9d76749da067be8792d2d4ddc98598d285452023"},"previous_names":["nucleojs/nucleo"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/mtmr0x/nucleo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtmr0x%2Fnucleo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtmr0x%2Fnucleo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtmr0x%2Fnucleo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtmr0x%2Fnucleo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mtmr0x","download_url":"https://codeload.github.com/mtmr0x/nucleo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtmr0x%2Fnucleo/sbom","scorecard":{"id":666681,"data":{"date":"2025-08-11","repo":{"name":"github.com/mtmr0x/nucleo","commit":"3812f1f4697edcb1d5900bd8872e9539960ebbd8"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.3,"checks":[{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":0,"reason":"Found 0/7 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENCE.md:0","Info: FSF or OSI recognized license: MIT License: LICENCE.md:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 24 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":2,"reason":"8 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw","Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275","Warn: Project is vulnerable to: GHSA-4q6p-r6v2-jvc5","Warn: Project is vulnerable to: GHSA-ww39-953v-wcq6","Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv","Warn: Project is vulnerable to: GHSA-mwcw-c2x4-8c55","Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw","Warn: Project is vulnerable to: GHSA-76p7-773f-r4q5"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-21T18:17:03.739Z","repository_id":33568236,"created_at":"2025-08-21T18:17:03.739Z","updated_at":"2025-08-21T18:17:03.739Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31943476,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-17T17:29:20.459Z","status":"ssl_error","status_checked_at":"2026-04-17T17:28:47.801Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["flux","javascript","nucleo","redux","state-management","typescript"],"created_at":"2024-08-17T08:03:44.767Z","updated_at":"2026-04-17T19:33:28.780Z","avatar_url":"https://github.com/mtmr0x.png","language":"TypeScript","funding_links":[],"categories":["typescript"],"sub_categories":[],"readme":"# Nucleo\n\nNucleo creates and manages a strongly typed and predictable state container.\n\n## Roadmap\n\nIt's in this project milestones https://github.com/mtmr0x/nucleo/milestones;\n\nFor requesting any feature, please open an issue with the prefix \"[FEATURE REQUEST]\".\n\n## Why\n\nJavaScript is a really dynamic language which we can't always rely in the language resilience from types perspective. Every project has types problems and developers can not make sure all the time the data is predictable. Inspired by how GraphQL does a great job with safety and trustful data and Redux by its simplicity on storing state, Nucleo was idealized to make sure the data model (contracts) and the data types are expected and reliable.\n\n## Installation\n\nUsing NPM:\n\n```\nnpm install nucleojs --save\n```\n\nUsing Yarn:\n\n```\nyarn add nucleojs\n```\n\n## Documentation\n\nThe links below take you to our `API_DOCUMENTATION.md` file present in this repository with deeper information and documentation to Nucleo usage.\n\n- [Installation](API_DOCUMENTATION.md#installation)\n- [Usage](API_DOCUMENTATION.md#usage)\n- [Contracts](API_DOCUMENTATION.md#contracts)\n- [Types](API_DOCUMENTATION.md#types)\n  - [NucleoObject](API_DOCUMENTATION.md#creating-nucleoobject)\n    - [Anatomy](API_DOCUMENTATION.md#nucleoobject-anatomy)\n    - [Usage](API_DOCUMENTATION.md#nucleoobject-usage)\n  - [NucleoList](API_DOCUMENTATION.md#creating-nucleolist)\n    - [Anatomy](API_DOCUMENTATION.md#nucleolist-anatomy)\n    - [Usage](API_DOCUMENTATION.md#nucleolist-usage)\n  - [NucleoString](API_DOCUMENTATION.md#creating-nucleostring)\n  - [NucleoNumber](API_DOCUMENTATION.md#creating-nucleonumber)\n  - [NucleoBoolean](API_DOCUMENTATION.md#creating-nucleoboolean)\n  - [NucleoStringAssertion](API_DOCUMENTATION.md#creating-nucleostringassertion)\n    - [Anatomy](API_DOCUMENTATION.md#nucleostringassertion-anatomy)\n    - [Usage](API_DOCUMENTATION.md#nucleostringassertion-usage)\n  - [NucleoNumberAssertion](API_DOCUMENTATION.md#creating-nucleonumberassertion)\n    - [Anatomy](API_DOCUMENTATION.md#nucleonumberassertion-anatomy)\n    - [Usage](API_DOCUMENTATION.md#nucleonumberassertion-usage)\n- [Creating the store](API_DOCUMENTATION.md#creating-the-store)\n- [Dispatching and updating the store](API_DOCUMENTATION.md#dispatching-and-updating-the-store)\n- [Get contracts in store](API_DOCUMENTATION.md#get-contracts-in-store)\n- [Subscribing to changes](API_DOCUMENTATION.md#subscribing-to-changes)\n- [Unsubscribing](API_DOCUMENTATION.md#unsubscribing)\n- [Error management](API_DOCUMENTATION.md#error-management)\n\n## Basic usage\n\nNucleo is written in TypeScript and compatible with es2016+. Importing for a ECMAScript usage:\n\n```javascript\nimport { createStore } from 'nucleojs';\n```\n\nImporting from Nucleo source for TypeScript usage just add `/src` after nucleojs module:\n\n```javascript\nimport { createStore } from 'nucleojs/src';\n```\n\n### Defining a data model (contract):\n\n```javascript\nimport {\n  NucleoString,\n  NucleoNumber,\n  NucleoObject,\n  createStore\n} from 'nucleojs'\n\nconst completeNameContract = new NucleoObject({\n  name: 'completeNameContract',\n  fields:  {\n    firstName: NucleoString,\n    lastName: NucleoString\n  }\n});\n\nconst userContract = new NucleoObject({\n  name: 'user', // don't need to be the same name as the variable, but need to be unique\n  fields: {\n    name: completeNameContract,\n    age: NucleoNumber\n  }\n});\n\nconst productsContract = new NucleoObject({\n  name: 'products',\n  fields: {\n    title: NucleoString\n  }\n});\n\nconst contracts = {\n  user: userContract,\n  products: productsContract\n};\n\n```\n\n### Creating the store\n\n```javascript\nimport { createStore } from 'nucleojs';\nimport * as contracts from './contracts';\n\nconst store = createStore(contracts); // send contracts to create the store\nconst { dispatch, update, cloneState, subscribe } = store; // these 4 functions are returned from store creation\n```\n\n### Dispatching and updating the store\n\nNucleo provides two methods of saving data, used for different approaches.\n\n**dispatch:** works for saving data according to the full contract, used to save the very first contract state in the store or to update the whole contract in the store;\n\n**update:** works for updating parts of data, it performs a index search in the object and save it. `update` will fail if you try to first save a contract to the store using it.\n\n---\n\nDispatch function, considering user contract above:\n\n```javascript\n\nlet user = dispatch('user')({ name: { firstName: 'John', lastName: 'Nor' } });\n// it'll fail because it's missing age field\n\nuser = dispatch('user')({ name: { firstName: 'John', lastName: 'Nor' }, age: 27 });\n// it'll save the data to store properly\n\nconsole.log(user);\n/*\n{\n  status: 'OK',\n  errors: [],\n  data: {\n    name: {\n      firstName: 'John',\n      lastName: 'Nor'\n    },\n    age: 27\n  },\n}\n*/\n```\n\nUpdate function, considering user contract above:\n\n```javascript\nconst user = update('user')({ name: { firstName: 'Robert' }});\n// it'll update only the user first name and only if this item has been already created in the store before\n\nconsole.log(user);\n/*\n{\n  status: 'OK',\n  errors: [],\n  data: {\n    name: {\n      firstName: 'Robert',\n    },\n  },\n}\n\nIt'll return the data you asked to save. To receive the new store, you will have to clone this state or subscribe to Nucleo changes through subscribe function\nCheck documentation for cloneState in the next section\n*/\nconst newUser = cloneState('user');\nconsole.log(newUser);\n/*\n{\n  name: {\n    firstName: 'Robert',\n    lastName: 'Nor',\n  },\n  age: 27,\n}\n*/\n```\n\n#### Update and Dispatch function signature\n\n`update` and `dispatch` functions have the same signature albeit a discrete behavioral difference (you can find this difference in .\n\n**Both are curried functions:**\n\n - `update(\u003ccontract_name\u003e)(\u003cdata_to_save_in_contract\u003e)`;\n - `dispatch(\u003ccontract_name\u003e)(\u003cdata_to_save_in_contract\u003e)`.\n\n`\u003ccontract_name\u003e`: a `string` for the contract name you want to update or dispatch. It's the `name` field for every new `NucleoObject` in the contracts definition. Those must be unique. You can find more information about contracts in API_DOCUMENTATION.md.\n\n`\u003cdata_to_save_in_contract\u003e`: must follow its contract model. For understanding how to use `update` and `dispatch` for saving data, check API_DOCUMENTATION.md in \"Dispatching and updating the store\" section.\n\n**Both return the same object interface:**\n\n```javascript\n{\n  status: 'OK' | 'NOK', // a string return 'OK' for success cases and 'NOK' for errors\n  errors: [], // in case of errors, it will return the list of errors\n  data: { ... } // the data you just tried to save in store\n}\n```\n\n - `status`: a string return 'OK' for success cases and 'NOK' for errors;\n - `errors`: a list of objects containing the errors in this operation. Usually related to contract violations. You can find more details in API_DOCUMENTATION.md at \"Error management\" area.\n - `data`: This is the exactly same object you tried to save at store for comparison reasons in cases of errors.\n\n### Getting a state clone from store\n\nThe `cloneState` function receives one argument which is the contract name in store, performs a deep clone using the contracts data model as a map to predict the key/values of that contract and be able to return it with great performance.\n\n```javascript\nconst user = cloneState('user');\nconsole.log(user);\n/*\n{\n  name: {\n    firstName: 'Robert',\n    lastName: 'Nor'\n  },\n  age: 27\n}\n*/\n```\n\n## Development\n\n### Tasks available\n\n- `npm start` - Start development mode.\n- `npm run nodemon` - Start development mode and waiting for changes.\n- `npm run tests` - Run automated tests.\n- `npm run lint` - Validate syntax of all Typescript files.\n- `npm run compile` - Compile for production.\n\n## Contributing\n\nWant to contribute? [Follow these recommendations](https://github.com/mtmr0x/nucleo/blob/master/CONTRIBUTING.md).\n\n## Versioning\n\nTo keep better organization of releases we follow the [Semantic Versioning 2.0.0](http://semver.org/) guidelines.\n\n## Licence\n\n[MIT Licence](https://github.com/mtmr0x/nucleo/blob/master/LICENCE.md) © [Matheus Marsiglio](http://mtmr0x.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtmr0x%2Fnucleo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmtmr0x%2Fnucleo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtmr0x%2Fnucleo/lists"}