Nucleo creates and manages a strongly typed and predictable state container.
It's in this project milestones https://github.com/mtmr0x/nucleo/milestones;
For requesting any feature, please open an issue with the prefix "[FEATURE REQUEST]".
JavaScript 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.
Using NPM:
npm install nucleojs --save
Using Yarn:
yarn add nucleojs
The links below take you to our API_DOCUMENTATION.md file present in this repository with deeper information and documentation to Nucleo usage.
- Installation
- Usage
- Contracts
- Types
- Creating the store
- Dispatching and updating the store
- Get contracts in store
- Subscribing to changes
- Unsubscribing
- Error management
Nucleo is written in TypeScript and compatible with es2016+. Importing for a ECMAScript usage:
import { createStore } from 'nucleojs';Importing from Nucleo source for TypeScript usage just add /src after nucleojs module:
import { createStore } from 'nucleojs/src';import {
NucleoString,
NucleoNumber,
NucleoObject,
createStore
} from 'nucleojs'
const completeNameContract = new NucleoObject({
name: 'completeNameContract',
fields: {
firstName: NucleoString,
lastName: NucleoString
}
});
const userContract = new NucleoObject({
name: 'user', // don't need to be the same name as the variable, but need to be unique
fields: {
name: completeNameContract,
age: NucleoNumber
}
});
const productsContract = new NucleoObject({
name: 'products',
fields: {
title: NucleoString
}
});
const contracts = {
user: userContract,
products: productsContract
};import { createStore } from 'nucleojs';
import * as contracts from './contracts';
const store = createStore(contracts); // send contracts to create the store
const { dispatch, update, cloneState, subscribe } = store; // these 4 functions are returned from store creationNucleo provides two methods of saving data, used for different approaches.
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;
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.
Dispatch function, considering user contract above:
let user = dispatch('user')({ name: { firstName: 'John', lastName: 'Nor' } });
// it'll fail because it's missing age field
user = dispatch('user')({ name: { firstName: 'John', lastName: 'Nor' }, age: 27 });
// it'll save the data to store properly
console.log(user);
/*
{
status: 'OK',
errors: [],
data: {
name: {
firstName: 'John',
lastName: 'Nor'
},
age: 27
},
}
*/Update function, considering user contract above:
const user = update('user')({ name: { firstName: 'Robert' }});
// it'll update only the user first name and only if this item has been already created in the store before
console.log(user);
/*
{
status: 'OK',
errors: [],
data: {
name: {
firstName: 'Robert',
},
},
}
It'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
Check documentation for cloneState in the next section
*/
const newUser = cloneState('user');
console.log(newUser);
/*
{
name: {
firstName: 'Robert',
lastName: 'Nor',
},
age: 27,
}
*/update and dispatch functions have the same signature albeit a discrete behavioral difference (you can find this difference in .
Both are curried functions:
update(<contract_name>)(<data_to_save_in_contract>);dispatch(<contract_name>)(<data_to_save_in_contract>).
<contract_name>: 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.
<data_to_save_in_contract>: 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.
Both return the same object interface:
{
status: 'OK' | 'NOK', // a string return 'OK' for success cases and 'NOK' for errors
errors: [], // in case of errors, it will return the list of errors
data: { ... } // the data you just tried to save in store
}status: a string return 'OK' for success cases and 'NOK' for errors;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.data: This is the exactly same object you tried to save at store for comparison reasons in cases of errors.
The 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.
const user = cloneState('user');
console.log(user);
/*
{
name: {
firstName: 'Robert',
lastName: 'Nor'
},
age: 27
}
*/npm start- Start development mode.npm run nodemon- Start development mode and waiting for changes.npm run tests- Run automated tests.npm run lint- Validate syntax of all Typescript files.npm run compile- Compile for production.
Want to contribute? Follow these recommendations.
To keep better organization of releases we follow the Semantic Versioning 2.0.0 guidelines.