├── .babelrc ├── .editorconfig ├── .eslintrc.yml ├── .gitignore ├── .npmignore ├── .nvmrc ├── .travis.yml ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── docs ├── built-in-helper-functions.md ├── cell-definitions.md ├── table-model-api.md └── table-model-demo.gif ├── package.json ├── src ├── ag-grid-utils.js ├── cell.js ├── cell.spec.js ├── demo │ ├── .babelrc │ ├── .eslintrc.yml │ ├── demo.js │ ├── grid.js │ ├── index.html │ ├── index.js │ ├── index.scss │ ├── row-defs.js │ └── webpack.config.js ├── example.spec.js ├── helper-functions.js ├── index.js ├── index.spec.js ├── model.js ├── table-model.js ├── table-model.spec.js ├── transaction.js ├── utils.js └── validation.js ├── webpack.config.js └── yarn.lock /.babelrc: -------------------------------------------------------------------------------- 1 | { 2 | "presets": ["@babel/preset-env"] 3 | } 4 | -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | indent_style = space 5 | indent_size = 2 6 | charset = utf-8 7 | trim_trailing_whitespace = true 8 | insert_final_newline = true 9 | -------------------------------------------------------------------------------- /.eslintrc.yml: -------------------------------------------------------------------------------- 1 | root: true 2 | 3 | env: 4 | mocha: true 5 | 6 | extends: 7 | - xo-space/esnext 8 | 9 | rules: 10 | curly: 11 | - error 12 | - multi-or-nest 13 | keyword-spacing: 14 | - error 15 | - overrides: 16 | catch: 17 | after: false 18 | for: 19 | after: false 20 | if: 21 | after: false 22 | while: 23 | after: false 24 | new-cap: 25 | - error 26 | - capIsNew: false 27 | no-return-assign: 28 | - error 29 | - except-parens 30 | object-curly-spacing: 31 | - error 32 | - always 33 | space-before-function-paren: 34 | - error 35 | - never 36 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /dist 2 | /node_modules 3 | /.idea 4 | 5 | /*.iml 6 | -------------------------------------------------------------------------------- /.npmignore: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/target/table-model/fdbc9054a5751617df1e0b32b961cf87dc789874/.npmignore -------------------------------------------------------------------------------- /.nvmrc: -------------------------------------------------------------------------------- 1 | 14.15.1 2 | 3 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: node_js 2 | 3 | before_deploy: 4 | - yarn build 5 | 6 | deploy: 7 | on: 8 | branch: master 9 | provider: npm 10 | email: "GameDevFox@gmail.com" 11 | api_key: "$NPM_TOKEN" 12 | skip_cleanup: true 13 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to make participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, gender identity and expression, level of experience, 9 | nationality, personal appearance, race, religion, or sexual identity and 10 | orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at 59 | [TTS-OpenSource-Office@target.com](mailto:TTS-OpenSource-Office@target.com). All 60 | complaints will be reviewed and investigated and will result in a response that 61 | is deemed necessary and appropriate to the circumstances. The project team is 62 | obligated to maintain confidentiality with regard to the reporter of an incident. 63 | Further details of specific enforcement policies may be posted separately. 64 | 65 | Project maintainers who do not follow or enforce the Code of Conduct in good 66 | faith may face temporary or permanent repercussions as determined by other 67 | members of the project's leadership. 68 | 69 | ## Attribution 70 | 71 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 72 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 73 | 74 | [homepage]: https://www.contributor-covenant.org 75 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to table-model 2 | 3 | ### Issues 4 | Issues are always welcome! You can expect conversation. 5 | 6 | ### Pull Requests 7 | 8 | These rules must be followed for any contributions to be merged into master. A Git installation is required. 9 | 10 | 1. Fork this repo 11 | 1. Create a branch 12 | 1. Make a desired changes 13 | 1. Validate your changes meet your desired use case 14 | 1. Ensure documentation has been updated 15 | 1. Open a pull-request: you can expect discussion 16 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2018 Target Brands, Inc. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![Build Status](https://www.travis-ci.org/target/table-model.svg?branch=master)](https://www.travis-ci.org/target/table-model) 2 | 3 | # TableModel - [Live Demo](https://target.github.io/table-model/) 4 | 5 | TableModel is an in-memory data model that automatically calculates your data based on provided equations. 6 | It keeps track of dependencies between data and equations and automatically updates cells quickly and efficiently. 7 | 8 | TableModel works especially well with UI components like AgGrid because it simplifies your data flow and can add 9 | additional features such as predicting which cells in your table are going to be impacted by a change (see below). 10 | 11 | ### Preview: AgGrid powered by TableModel ([AgGrid not included](https://www.ag-grid.com/)) 12 | 13 | ![TableModel Animated GIF](https://github.com/target/table-model/blob/master/docs/table-model-demo.gif?raw=true) 14 | 15 | ## Getting Started 16 | 17 | Install table-model: 18 | 19 | ``` 20 | npm install --save-dev table-model 21 | ``` 22 | 23 | Import the 'table-model' module into your project: 24 | 25 | ES6+ 26 | ``` 27 | import TableModel from 'table-model'; 28 | ``` 29 | CommonJS 30 | ``` 31 | const TableModel = require('table-model'); 32 | ``` 33 | 34 | ## Usage 35 | A unit test of the following example can be found at `src/example.spec.js` 36 | ``` 37 | // Formulas 38 | const totalEquation = d => d.row('a') + d.row('b') + d.row('c'); 39 | const extraEquation = d => d.row('b') * d.row('c'); 40 | 41 | // This builds a formula that matches a given color 42 | const colorTotals = color => { 43 | return d => { 44 | // Get the 'total's from all rows with the matching color 45 | const numbers = d.rowsWhere({ type: color }, 'total'); 46 | // Sum up the numbers to get to total 47 | return numbers.reduce((total, num) => total + num, 0); 48 | }; 49 | }; 50 | 51 | // This array contains a list of our rows and their cells 52 | const rowDefs = [ 53 | // Row 1 54 | { 55 | meta: { id: 1, type: 'red' }, 56 | cells: { a: 10, b: 20, c: 30, total: totalEquation } 57 | }, 58 | // Row 2 59 | { 60 | meta: { id: 2, type: 'green' }, 61 | // Rows don't have to have the same types of cells 62 | cells: { a: 12, b: 45, c: 38, d: 1234, total: totalEquation, extra: extraEquation } 63 | }, 64 | // Row 3 65 | { 66 | meta: { id: 3, type: 'red' }, 67 | cells: { a: 100, b: 200, c: 300, total: totalEquation } 68 | }, 69 | // Totals 70 | { 71 | meta: { id: 4 }, 72 | cells: { redTotal: colorTotals('red'), greenTotal: colorTotals('green') } 73 | } 74 | ]; 75 | 76 | const listener = updates => console.log('UPDATES:', updates); 77 | 78 | const table = TableModel({ rowDefs, listener }); 79 | 80 | // Output: All cell values are included in the first update 81 | 82 | // UPDATES: { 83 | // 1: { a: 10, b: 20, c: 30, total: 60 }, 84 | // 2: { a: 12, b: 45, c: 38, d: 1234, total: 95, extra: 1710 }, 85 | // 3: { a: 100, b: 200, c: 300, total: 600 }, 86 | // 4: { redTotal: 660, greenTotal: 95 } 87 | // }); 88 | 89 | table.update({ 2: { c: 123 } }); 90 | 91 | // Output: Only cells that were impacted by the update are included after that 92 | 93 | // UPDATES: { 94 | // 2: { c: 123, total: 180, extra: 5535 }, 95 | // 4: { greenTotal: 180 } 96 | // }); 97 | ``` 98 | 99 | ## Docs 100 | 101 | ### [Cell Definitions](./docs/cell-definitions.md) 102 | ### [TableModel API](./docs/table-model-api.md) 103 | ### [Built-in Helper Functions](./docs/built-in-helper-functions.md) 104 | 105 | ## Why? 106 | 107 | #### Fast 108 | > Because TableModel analyzes your equations, it knows which other values and equations are impacted by 109 | > any given change. This ensures that when a change happens, TableModel only does the minimum amount of work 110 | it needs to do. 111 | 112 | #### Testable 113 | > If you're using a UI library like AgGrid to do your calculations for you, it can add an additional 114 | > layer of complexity when trying to test. AgGrid requires a DOM to run and test with. This is not ideal 115 | > for the simplicity and performance of your tests. 116 | > 117 | > By using TableModel to handle your data, you can write units tests for your equations which are 118 | > simple and easy to write, and decoupled from the view. See an example TableModel unit test at `src/example.spec.js`. 119 | 120 | #### Maintainable 121 | > If your data model has a lot of calculations your code base can get complicated very quickly, 122 | > for example, maintaining the proper order of the calculations, and determining which values need to be recalculated 123 | > (or not) when another values changes. 124 | > 125 | > TableModel abstracts all this complexity away for you. All you have to do is define simple 126 | > equations, feed TableModel your data, and it'll take care of the rest. **TableModel automatically manages the 127 | > dependencies between your equations.** If you need to make changes down the road, you only have to update your 128 | > equations. 129 | 130 | #### Separation of Concerns -or- "Do one thing and do it well" 131 | > If you're using a library like AgGrid to render your data in a UI component, you might 132 | > realize that AgGrid is REALLY good at presenting data, but has some limitations when trying 133 | > to handle calculations, for example, trying to operate on data in multiple rows. 134 | > 135 | > By using TableModel with AgGrid, you can use AgGrid to do what it does best (display data - the View) 136 | > and let TableModel take care of what it does best (calculation and data management - the Model). 137 | 138 | ## Features 139 | 140 | * Automatic Updates 141 | * Setter Functions 142 | * Update Prediction 143 | * Custom Helpers Functions 144 | * Custom PreLink Callback for Optimization 145 | * AgGrid Support 146 | 147 | ## Who uses TableModel? 148 | 149 | * Target 150 | * ... that's it so far. (Send a PR if you use TableModel 😎) 151 | -------------------------------------------------------------------------------- /docs/built-in-helper-functions.md: -------------------------------------------------------------------------------- 1 | # Built-in Helper Functions 2 | 3 | ## Cell Helpers 4 | These functions return a cell's value or an array of cell values to be used in getter and setter functions. 5 | 6 | __Note:__ These helpers are the helper functions that you can supply at initialization that are wrapped to return cell values instead of the cells themselves. These helpers should not be used to supply cell arguments to setter helpers. 7 | 8 | * __row(cellName)__ 9 | 10 | Returns a single cell's value from the current row by name 11 | 12 | * __prevRow(cellName)__ 13 | 14 | Returns a single cell's value from the previous row by name 15 | 16 | * __rowsWhere(criteria, cellName)__ 17 | 18 | Returns a cell's value from each row by name where criteria matches the metadata attributes found on each row. For example if I call `rowsWhere({ color: red, even: true }, 'count')` it will return the `count` cell from every row that has at least the `color: red` and `even: true` properties in the row's `meta` object. 19 | 20 | Note: ALL properties given in `criteria` must match for the row to match the rule and return it's cell. 21 | 22 | ## Setter Helpers 23 | These functions update cells based on the given values. 24 | 25 | * __set(value, cells)__ 26 | 27 | Updates all cells with the given value. `cells` can either be a single cell or an array of cells 28 | 29 | * __spread(value, cells)__ 30 | 31 | Increments or decrements an array of cells proportionally to each other 32 | 33 | * __data.cells__ 34 | 35 | This in an object that contains pure copies of the cell helper functions that return cells instead of cell values. These should be used for getting references to cells to pass to setter helper functions. 36 | 37 | ## Other Helpers 38 | 39 | * __meta(name)__ 40 | 41 | Returns the meta property for the given row. For example, if the metadata for my current row is: 42 | ``` 43 | { a: 123, b: 'hello' } 44 | ``` 45 | calling `meta('a')` will return `123` for all cells in that row. 46 | 47 | * __preLink()__ 48 | 49 | Returns a reference to the preLink data returned by the `preLink` function provided at initialization. 50 | -------------------------------------------------------------------------------- /docs/cell-definitions.md: -------------------------------------------------------------------------------- 1 | # Cell Definitions 2 | 3 | You can define cell definitions in one of 3 flavors: 4 | 5 | ## 1. Base Value 6 | 7 | This is the easiest method. You simply specify an initial value that you'd like the cell to be. TableModel will automatically create a `getter` and `setter` formula that will get and set this value. 8 | 9 | ``` 10 | const numCell = 13; 11 | const stringCell = 'Hello World'; 12 | ``` 13 | 14 | Base Values can be an array or an object as well 15 | 16 | ``` 17 | const arrayCell = [1, 2, 3, 4, 5]; 18 | const objCell = { name: 'James', hp: '200', gold; '1200' }; 19 | ``` 20 | 21 | ## 2. Getter Function 22 | 23 | This defines a cell whose value is based off of other cells or data. The function you provide will be the getter for your cell. This getter function will be called any time the value of any of the dependant cell's values are updated. For example, the getter function will be called when either the `width` or `height` cells are updated in the same row. 24 | 25 | The getter function takes a single argument which in an object which you can call whatever you'd like. In this case we call it `d` for `data`. This object contains all your helper functions that you can use to make it easier to write getter functions. 26 | 27 | For example, if I wanted to reference a cell in the previous week (let's say I wanted to compare inventory levels to see how much I bought / sold) I could call `d.prevRow('inventoryCount)` which would be a lot easier than manually sorting through all the row data to find that row and cell yourself. It also makes your cell definition look cleaner and more like a mathematical formula. 28 | 29 | The value that's returned from the getter function is the new calculated value for that cell. 30 | 31 | Note: You will not be able to update any cell that only has a getter function. 32 | 33 | ``` 34 | const areaCell = d => d.row('width') * d.row('height'); 35 | ``` 36 | 37 | Note: The previous example is shorthand for the third method and is the same as not specifing a setter: 38 | 39 | ``` 40 | const areaCell = { 41 | get: d => d.row('width') * d.row('height'); 42 | } 43 | ``` 44 | 45 | Somtimes you may want to reference what the previous value of the cell was. 46 | Using `d.row('areaCell')` would cause infinitely recursing function calls so you can reference the old value like so: 47 | ``` 48 | const areaCell = { 49 | get: (d, oldValue) => // do something 50 | } 51 | ``` 52 | 53 | ## 3. Getter/Setter Object 54 | 55 | This is the option that gives you the most flexibility. This is done by defining an object with both a `get` property with the cell's getter function and a `set` property with the cell's setter function. This is useful if you want equations or formulas which can be manipulated both ways. 56 | 57 | For example: If I have a row that has `width`, `height` and `area`, a simple set of cell definitions might look like this: 58 | 59 | ``` 60 | const rowDefinition = { 61 | width: 100, 62 | height: 20, 63 | area: d => d.row('width') * d.row('height') 64 | } 65 | ``` 66 | 67 | However, we learned from the last section that I can't update a cell that only has a getter function, as is the case with `area`. However, we know that mathematically I __COULD__ change the area and then update the width or height to balance the equation. 68 | 69 | We can do this with TableModel be specifing a setter function with `set`: 70 | 71 | ``` 72 | const rowDefinition = { 73 | width: 100, 74 | height: 20, 75 | area: { 76 | get: d => d.row('width') * d.row('height') 77 | set: (d, value, oldValue) => d.set(value / d.row('width'), d.cells.row('height')) 78 | } 79 | } 80 | ``` 81 | 82 | Note: I'm using `data.cells.row('height')` instead of `data.row('height')` since the latter would return the value, but I want to reference the cell. `data.cells` includes a set of helper functions which return cells instead of cells values that you can use for these special setter function helpers. 83 | 84 | You should recognize the getter function from the previous example. It's exactly the same, we've just moved it to the `get` property in our object. 85 | 86 | We've also added a `set` property with our setter function. A setter function takes 3 arguments, `[data, value, oldValue]` where `data` is the same argument passed to the getter function. The `value` is the new value the cell is being updated to and the `oldValue` is the value of the cell before the update. 87 | 88 | ### The `data.set(value, cells)` helper 89 | 90 | What's going on in our setter function is that we're calling a special helper function called `set`. The `set` helper takes two arguments, a value for the first argument and a cell or array of cells for the second argument. Calling `set(value, cells)` will update all the given cells with the value provided. 91 | 92 | Going back to our example, we can see that the initial value of `area` would be `2000`. If we update `area` to `3000`, we see that the setter function would take that new value of `3000`, divide it by the current `width` which is `100` to get a value of `30`. We take this value of `30` and set it to the cell in the second argument of `set` which is height. After our update our row would look like this: 93 | 94 | ``` 95 | // Inital row values are: 96 | { 97 | width: 100, 98 | height: 20, 99 | area: 2000 100 | } 101 | 102 | tableModel.update({ myRow: { area: 3000 }}); 103 | 104 | // Final row values are 105 | { 106 | width: 100, 107 | height: 30, // Included in update 108 | area: 3000 // Included in update 109 | } 110 | ``` 111 | 112 | ### The `data.spread(value, cells)` helper 113 | 114 | The `spread` method is another special function you'll probably only ever use in setter functions. It takes similar arguments as `set` except it will *"spread"* the given value over the given cells instead of setting the value. What that means is that it would increase or decrease each cells value proportionally. This is seen from the following example: 115 | 116 | ``` 117 | const rowDefinition = { 118 | a: 100, 119 | b: 200, 120 | c: 300, 121 | d: 400 122 | total: { 123 | get: d => d.row('a') + d.row('b') + d.row('c') + d.row('d'); 124 | set: (d, value, oldValue) => { 125 | const allcells = [d.row('a'), d.row('b'), d.row('c'), d.row('d')]; 126 | d.spread(value - oldValue, allCells); 127 | } 128 | } 129 | } 130 | 131 | // Inital row values are: 132 | { 133 | a: 100, 134 | b: 200, 135 | c: 300, 136 | d: 400 137 | total: 1000 138 | } 139 | 140 | tableModel.update({ myRow: { total: 1500 }}); 141 | 142 | // Final row values are 143 | { 144 | a: 150, 145 | b: 300, 146 | c: 450, 147 | d: 600 148 | total: 1500 149 | } 150 | ``` 151 | 152 | Note: It's important to note that the `value` in `spread` is `500` which represents the amount of the change instead of the final value itself. 153 | -------------------------------------------------------------------------------- /docs/table-model-api.md: -------------------------------------------------------------------------------- 1 | # TableModel API 2 | 3 | ## const tableModel = TableModel({ rowDefs, helpers, listener, preLink }) 4 | 5 | - __rowDefs: (Required)__ This is an array of row definitions which define the data and/or formulas that will be used in the underlying cells. A row definition takes the form of an object `{ meta: {}, cells {} }` where `meta` is an object of generic data specific to the row and `cells` is an object where the keys are the cell name and the values are the cell definition. 6 | 7 | ``` 8 | const rowDefs = [ 9 | // Row 1 10 | { 11 | meta: { id: 1, type: 'red' }, 12 | cells: { a: 10, b: 20, c: 30, total: totalEquation } 13 | }, 14 | // Row 2 15 | { 16 | meta: { id: 2, type: 'green' }, 17 | // Rows don't have to have the same types of cells 18 | cells: { a: 12, b: 45, c: 38, d: 1234, total: totalEquation, extra: extraEquation } 19 | }, 20 | // Row 3 21 | { 22 | meta: { id: 3, type: 'red' }, 23 | cells: { a: 100, b: 200, c: 300, total: totalEquation } 24 | }, 25 | // Totals 26 | { 27 | meta: { id: 4 }, 28 | cells: { redTotal: colorTotals('red'), greenTotal: colorTotals('green') } 29 | } 30 | ]; 31 | ``` 32 | - __helpers:__ You can provide an optional object here to extend the built-in helper functions which are available for use in your cell definitions. This is an object where the keys are the helper name and the values are helper functions. The helper functions take the form of a function that returns a function which returns a cell or an array of cells. 33 | 34 | ``` 35 | const helpers = { 36 | byColor: input => { 37 | return cellName => { 38 | const thisColor = input.meta.color; 39 | const rows = input.rows; 40 | 41 | return rows.filter(row => row.meta.color === thisColor).map(row => row[cellName]); 42 | }; 43 | } 44 | } 45 | 46 | ``` 47 | 48 | The outer function gets called with an `input` argument that contains various data that is avilable to the helper method. The contents of the `input` may be different for each invocation depending on the cell in which the helper is called. 49 | 50 | The inner function is the function that actually gets used and called in the cell definitions. This function can have whatever arguments you'd like to provide to the user. 51 | 52 | __IMPORTANT:__ 53 | The return value of the inner function must be either a cell or an array of cells. Table model will automatically resolve the value of the cell for use in the formula. 54 | 55 | - __listener:__ You can specify an optional listener here at initialization that will be called with the first cell update that will include a complete set of all the values for all the cells in your table. If you use the `tableModel.listen(listenerFn)` to add a listener after TableModel has been initialized, it will receive later updates, but not the first complete update. 56 | 57 | - __prelink:__ You can specify an optional callback function here. This preLink function will be called __AFTER__ all the cells have been built but __BEFORE__ the linking and initial calculation process has started. The prelink function is called with an array of rows containing cell objects instead of cell definitions. Any data returned by this method is made available to helper functions via the `input` argument. This is useful if you'd like to build a cache of cells to use in helper functions or to perform any other optimizations here. 58 | 59 | An example of a good use case for this would be taking an array of rows that represent certain days and grouping them by month and storing the results in an object. A helper function can use this cache to do faster lookups for all days that are in a given week instead of searching the entire dataset over and over again each time the helper method is called. 60 | 61 | ``` 62 | const prelink = rows => { 63 | const daysInMonth = _.groupBy(rows, row => row.meta.month); 64 | return { daysInMonth }; 65 | } 66 | ``` 67 | ... and in your helper method ... 68 | 69 | ``` 70 | const helpers = { 71 | monthDays: input => { 72 | return (month, cellName) => { 73 | const daysInMonth = input.preLink.daysInMonth; 74 | const dayRows = daysInMonth(month); 75 | const cells = dayRows.map(row => row[cellName]); 76 | return cells; 77 | } 78 | } 79 | }; 80 | ``` 81 | ... and in your cell definition ... 82 | 83 | ``` 84 | const monthTotal = d => { 85 | const pointsForAllDaysInMonth = d.monthDays(10, 'points'); 86 | const total = pointsForAllDaysInMonth.reduce((x, y) => x + y); 87 | return total; 88 | } 89 | ``` 90 | 91 | ## tableModel.listen(listenerFn) 92 | This adds a listener function to TableModel that will be called with all subsequent updates. Each listener function gets called with an object where the keys are the row ids and the values are an object containing the new values for any cells in that row that were updated by the last update. The first update returned by TableModel will include a complete set of the values of all cells like so: 93 | 94 | ``` 95 | { 96 | 1: { a: 10, b: 20, c: 30, total: 60 }, 97 | 2: { a: 12, b: 45, c: 38, d: 1234, total: 95, extra: 1710 }, 98 | 3: { a: 100, b: 200, c: 300, total: 600 }, 99 | 4: { redTotal: 660, greenTotal: 95 } 100 | } 101 | ``` 102 | 103 | Subsequent updates will contain only the rows and cells that were impacted by the update: 104 | 105 | ``` 106 | { 107 | 2: { c: 123, total: 180, extra: 5535 }, 108 | 4: { greenTotal: 180 } 109 | } 110 | ``` 111 | 112 | Note: In order to catch the first complete update from TableModel, your listener must be added at initialization. If you use this method, your listener won't be added in time to receive the first complete update. 113 | 114 | ## tableModel.update(changes) 115 | This triggers an update on TableModel and will update or set all values supplied. The only argument is an object which is similar in structure to the objects received by the listener functions: the object keys being row ids and the object values being key-value pairs of the cellNames and values of those cells to be updated. 116 | 117 | ``` 118 | table.update({ 119 | 2: { a: 123, c: 456 } 120 | 3: { b: 789 } 121 | }); 122 | ``` 123 | 124 | If this update contains a cell that can't be updated (either because it's not a "base value" equation) or because it has no setter in its equation) it'll throw an exception with details. An exception will also be thrown if TableModel notices that you are trying to update a cell which would also be impacted by an update of another cell, since the values of these updates might not match. 125 | 126 | ## tableModel.willAffect(changes) 127 | This method takes the exact same argument type as `tableModel.update(changes)`. However, instead of triggering an update it will perform a "dry run" on the cells instead and keep track of which cells are impacted by the update without actually updating the values of any cells. This allows you to do "update prediction" allowing you check which cells will be affected by a call to `tableModel.update(changes)` before you actually make the update. 128 | 129 | The value returned by this function is an object where the keys are row ids and the values are an array of cellNames which represent the cells in that row that would be affected by the update. 130 | 131 | ``` 132 | let affectedCells = tableModel.willAffect({ 2: { asp: 10 } }); 133 | console.log(affectedCells); 134 | 135 | // Outputs: 136 | { 137 | 2: ['asp', 'doubleAsp', 'sales'], 138 | 3: ['prevDoubleAsp'] 139 | } 140 | ``` 141 | 142 | ## tableModel.rows 143 | You can access the rows object directly from the instance object. You should not make changes to this object after initialization. You should supply a `preLink` function if you'd like to make changes or optimizations to the cells before linking. 144 | 145 | ## tableModel.preLinkData 146 | You can access the preLinkData directly from the instance object. You should not make changes to this object after initialization. 147 | -------------------------------------------------------------------------------- /docs/table-model-demo.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/target/table-model/fdbc9054a5751617df1e0b32b961cf87dc789874/docs/table-model-demo.gif -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "table-model", 3 | "version": "1.6.0", 4 | "description": "A library to manage and automate data and calculations", 5 | "keywords": [ 6 | "table", 7 | "model", 8 | "data", 9 | "calculation", 10 | "formula", 11 | "aggrid" 12 | ], 13 | "repository": "https://github.com/target/table-model", 14 | "author": "Edward Nicholes Jr.", 15 | "license": "MIT", 16 | "main": "dist/table-model.js", 17 | "scripts": { 18 | "build": "webpack", 19 | "clean": "rm -rf ./dist", 20 | "test": "mocha-webpack --require jsdom-global/register --webpack-config webpack.config.js src/index.spec.js", 21 | "test:watch": "mocha-webpack --watch --require jsdom-global/register --webpack-config webpack.config.js src/index.spec.js" 22 | }, 23 | "devDependencies": { 24 | "@babel/core": "^7.12.10", 25 | "@babel/preset-env": "^7.12.10", 26 | "ag-grid": "^17.1.1", 27 | "ag-grid-react": "^24.1.1", 28 | "babel-loader": "^8.2.2", 29 | "babel-preset-react": "^6.24.1", 30 | "eslint": "^7.15.0", 31 | "eslint-config-xo-react": "^0.23.0", 32 | "eslint-config-xo-space": "^0.25.0", 33 | "eslint-loader": "^4.0.2", 34 | "eslint-plugin-react": "^7.21.5", 35 | "html-webpack-plugin": "^4.5.0", 36 | "js-logger": "^1.6.1", 37 | "jsdom": "^16.4.0", 38 | "jsdom-global": "^3.0.2", 39 | "mocha": "^7.2.0", 40 | "mocha-webpack": "^2.0.0-beta.0", 41 | "node-sass": "^7.0.0", 42 | "prettier": "^2.2.1", 43 | "react": "^17.0.1", 44 | "react-dom": "^17.0.1", 45 | "react-dom-factories": "^1.0.2", 46 | "sass-loader": "^10.1.0", 47 | "should": "^13.2.3", 48 | "sinon": "^9.2.1", 49 | "source-map-support": "^0.5.19", 50 | "style-loader": "^2.0.0", 51 | "webpack": "^4.44.2", 52 | "webpack-cli": "^4.2.0", 53 | "webpack-dev-server": "^3.11.0" 54 | } 55 | } 56 | -------------------------------------------------------------------------------- /src/ag-grid-utils.js: -------------------------------------------------------------------------------- 1 | import _ from 'lodash'; 2 | 3 | export const initAgGridData = (agGridApi, tableModelUpdate) => { 4 | const rowData = _.map(tableModelUpdate, (cells, rowId) => { 5 | const gridRow = { ...cells }; 6 | gridRow.id = parseInt(rowId, 10); 7 | return gridRow; 8 | }); 9 | 10 | agGridApi.setRowData(rowData); 11 | }; 12 | 13 | export const updateAgGrid = (agGridApi, tableModelUpdate) => { 14 | _.each(tableModelUpdate, (rowUpdates, rowId) => { 15 | const node = agGridApi.getRowNode(rowId); 16 | 17 | let { data } = node; 18 | data = Object.assign(data, rowUpdates); 19 | node.setData(data); 20 | }); 21 | }; 22 | 23 | const noValueChange = params => params.newValue === params.oldValue; 24 | 25 | export const updateTable = (table, agGridUpdate) => { 26 | const rowId = agGridUpdate.node.id; 27 | const cell = agGridUpdate.colDef.field; 28 | 29 | if(noValueChange(agGridUpdate)) 30 | return; 31 | 32 | const update = {}; 33 | update[rowId] = {}; 34 | update[rowId][cell] = agGridUpdate.newValue; 35 | 36 | table.update(update); 37 | }; 38 | 39 | export const buildHighlighter = tableModel => { 40 | let affectedRows = null; 41 | 42 | const begin = params => { 43 | const rowId = params.data.id; 44 | const cellName = params.colDef.field; 45 | const { api } = params; 46 | 47 | const update = {}; 48 | update[rowId] = {}; 49 | update[rowId][cellName] = null; 50 | 51 | affectedRows = tableModel.willAffect(update); 52 | 53 | const rowNodes = []; 54 | _.each(affectedRows, (affectedCells, rowId) => { 55 | const node = params.api.getRowNode(rowId); 56 | 57 | if(node) { 58 | const { data } = node; 59 | data.affectedCells = affectedCells; 60 | rowNodes.push(node); 61 | } 62 | }); 63 | api.refreshCells({ rowNodes, force: true }); 64 | }; 65 | 66 | const end = params => { 67 | const rowNodes = []; 68 | const { api } = params; 69 | _.each(affectedRows, (affectedCells, rowId) => { 70 | const node = params.api.getRowNode(rowId); 71 | if(node) { 72 | delete node.data.affectedCells; 73 | rowNodes.push(node); 74 | } 75 | }); 76 | api.refreshCells({ rowNodes, force: true }); 77 | affectedRows = null; 78 | }; 79 | 80 | return { begin, end }; 81 | }; 82 | -------------------------------------------------------------------------------- /src/cell.js: -------------------------------------------------------------------------------- 1 | import _ from 'lodash'; 2 | 3 | import Model from './model'; 4 | import Transaction from './transaction'; 5 | 6 | const Cell = ({ id, formula, data, helperFactory }) => { 7 | const cell = { 8 | id, 9 | dependents: [], 10 | dependencies: [], 11 | setterDependents: [] 12 | }; 13 | 14 | const model = Model(formula); 15 | 16 | const get = (trx = {}) => { 17 | const { cellStack, dryRun, init, stale, updates } = trx; 18 | 19 | // Add and link dependant 20 | if(init) { 21 | const dependentCell = cellStack[cellStack.length - 1]; 22 | 23 | if(dependentCell) { 24 | cell.dependents.push(dependentCell); 25 | dependentCell.dependencies.push(cell); 26 | } 27 | } 28 | 29 | const isStale = stale && stale[id] !== undefined; 30 | if(!isStale) { 31 | // Only call this getter once per transaction 32 | if(updates && updates[id] !== undefined) 33 | return updates[id]; 34 | 35 | // If not stale, return cached model value 36 | if(!updates || !init) 37 | return model.value; 38 | } 39 | 40 | // Update helpers with current trx 41 | const helpers = helperFactory(trx); 42 | 43 | if(cellStack) 44 | cellStack.push(cell); 45 | const value = model.getter(helpers, model.value); 46 | if(cellStack) 47 | cellStack.pop(); 48 | 49 | // Update model 50 | if(!dryRun) 51 | model.value = value; 52 | 53 | // Update trx 54 | if(updates) { 55 | updates[id] = value; 56 | delete stale[id]; 57 | } 58 | 59 | // Mark dependents as stale and update 60 | if(updates && !init && stale) { 61 | cell.dependents.forEach(dep => { 62 | const cellId = dep.id; 63 | 64 | if(updates[cellId] === undefined) 65 | stale[cellId] = dep; 66 | }); 67 | } 68 | 69 | return value; 70 | }; 71 | 72 | let set; 73 | if(model.setter) { 74 | set = (value, trx) => { 75 | // Only call this setter once per transaction 76 | const { cellStack, dryRun, stale, updates } = trx; 77 | if(updates && updates[id]) 78 | return; 79 | 80 | // Update helpers with current trx 81 | const helpers = helperFactory(trx); 82 | 83 | // Placeholder 84 | updates[id] = true; 85 | 86 | // Update this cell 87 | if(cellStack) 88 | cellStack.push(cell); 89 | model.setter(helpers, value, model.value); 90 | if(cellStack) 91 | cellStack.pop(); 92 | 93 | // Update model and trx 94 | if(!dryRun) 95 | model.value = value; 96 | 97 | // Update trx 98 | updates[id] = value; 99 | delete stale[id]; 100 | 101 | // Update dependants 102 | if(stale) { 103 | cell.dependents.forEach(dep => { 104 | const cellId = dep.id; 105 | 106 | if(updates[cellId] === undefined) 107 | stale[cellId] = dep; 108 | }); 109 | } 110 | 111 | // Process stale cells 112 | if(cellStack.length === 0) { 113 | while(_.size(stale)) 114 | _.values(stale).forEach(cell => cell.get(trx)); 115 | } 116 | }; 117 | } else { 118 | set = () => { 119 | throw new Error('This cell doesn\'t have a setter'); 120 | }; 121 | } 122 | 123 | const willAffect = () => { 124 | const trx = Transaction({ dryRun: true }); 125 | set(model.value, trx); 126 | 127 | return trx.updates; 128 | }; 129 | 130 | const hasSetter = model.setter !== undefined; 131 | Object.assign(cell, { data, get, set, hasSetter, willAffect }); 132 | return cell; 133 | }; 134 | 135 | export default Cell; 136 | -------------------------------------------------------------------------------- /src/cell.spec.js: -------------------------------------------------------------------------------- 1 | import _ from 'lodash'; 2 | import should from 'should'; 3 | 4 | import Cell from './cell'; 5 | import Transaction from './transaction'; 6 | 7 | import { buildHelperFactory } from './utils'; 8 | 9 | const helperFns = { 10 | cellHelpers: { 11 | row: input => { 12 | return cellNames => { 13 | const { testCells } = input; 14 | let result; 15 | if(_.isArray(cellNames)) 16 | result = cellNames.map(cellName => testCells[cellName]); 17 | else 18 | result = testCells[cellNames]; 19 | 20 | return result; 21 | }; 22 | } 23 | }, 24 | otherHelpers: { 25 | set: input => { 26 | return (value, cells) => { 27 | const { trx } = input; 28 | if(_.isArray(cells)) 29 | cells.forEach(cell => cell.set(value, trx)); 30 | else 31 | cells.set(value, trx); 32 | }; 33 | }, 34 | spread: input => { 35 | return (value, cells) => { 36 | const { trx } = input; 37 | const total = cells.reduce((total, cell) => total + cell.get(trx), 0); 38 | cells.forEach(cell => { 39 | const oldValue = cell.get(trx); 40 | const proportion = oldValue / total; 41 | const delta = value * proportion; 42 | const newValue = oldValue + delta; 43 | 44 | cell.set(newValue, trx); 45 | }); 46 | }; 47 | } 48 | } 49 | }; 50 | 51 | const helperFactory = buildHelperFactory(helperFns); 52 | 53 | describe('Cell', () => { 54 | let data; 55 | 56 | beforeEach(() => { 57 | const testCells = _.mapValues({ alpha: 10, beta: 20, delta: 100, omega: 1234 }, (value, name) => { 58 | return Cell({ id: name, formula: value, helperFactory }); 59 | }); 60 | data = { testCells }; 61 | }); 62 | 63 | it('should support `value` formula', () => { 64 | const helperFactory = buildHelperFactory(helperFns, data); 65 | const cell = Cell({ id: 'cell', formula: 100, helperFactory, data }); 66 | 67 | let trx = Transaction({ init: true }); 68 | cell.get(trx).should.eql(100); 69 | 70 | trx = Transaction(); 71 | cell.set(50, trx); 72 | 73 | cell.get().should.eql(50); 74 | }); 75 | 76 | it('should support complex `value` formulas', () => { 77 | const helperFactory = buildHelperFactory(helperFns, data); 78 | const cell = Cell({ id: 'cell', formula: { name: 'James', gold: 200 }, helperFactory, data }); 79 | 80 | let trx = Transaction({ init: true }); 81 | cell.get(trx).should.eql({ name: 'James', gold: 200 }); 82 | 83 | trx = Transaction(); 84 | cell.set({ name: 'Sarah', gold: 5000 }, trx); 85 | 86 | cell.get().should.eql({ name: 'Sarah', gold: 5000 }); 87 | }); 88 | 89 | it('should support `function` formula', () => { 90 | const helperFactory = buildHelperFactory(helperFns, data); 91 | const cell = Cell({ id: 'cell', formula: d => d.row('alpha') + d.row(['delta', 'omega']).reduce((x, y) => x + y, 0) + 10, helperFactory, data }); 92 | const cell2 = Cell({ id: 'cell2', formula: d => d.row('alpha') * d.row('beta'), helperFactory, data }); 93 | 94 | let trx = Transaction({ init: true }); 95 | cell.get(trx).should.eql(1354); 96 | cell2.get(trx).should.eql(200); 97 | 98 | should(() => { 99 | trx = Transaction(); 100 | cell.set(50, trx); 101 | }).throw('This cell doesn\'t have a setter'); 102 | 103 | cell.get().should.eql(1354); 104 | 105 | cell.dependencies.length.should.eql(3); 106 | cell2.dependencies.length.should.eql(2); 107 | 108 | const { alpha, beta, delta, omega } = data.testCells; 109 | 110 | alpha.dependents.length.should.eql(2); 111 | beta.dependents.length.should.eql(1); 112 | delta.dependents.length.should.eql(1); 113 | omega.dependents.length.should.eql(1); 114 | 115 | trx = Transaction(); 116 | alpha.set(123, trx); 117 | 118 | trx.updates.should.deepEqual({ 119 | alpha: 123, 120 | cell: 1467, 121 | cell2: 2460 122 | }); 123 | }); 124 | 125 | it('should only call a getter formula once per transaction', () => { 126 | let count = 0; 127 | const helperFactory = buildHelperFactory(helperFns, data); 128 | 129 | const cell = Cell({ id: 'cell', formula: d => { 130 | count++; 131 | return d.row('alpha') + 10; 132 | }, helperFactory, data }); 133 | 134 | const trx = Transaction({ init: true }); 135 | cell.get(trx).should.eql(20); 136 | 137 | cell.get().should.eql(20); 138 | cell.get().should.eql(20); 139 | cell.get().should.eql(20); 140 | cell.get().should.eql(20); 141 | cell.get().should.eql(20); 142 | cell.get().should.eql(20); 143 | 144 | count.should.eql(1); 145 | }); 146 | 147 | it('should only call a getter formula once per transaction when value 0', () => { 148 | const helperFactory = buildHelperFactory(helperFns, data); 149 | 150 | let count = 0; 151 | const formula = d => { 152 | count++; 153 | return d.row('alpha') * 0; 154 | }; 155 | 156 | data.testCells.gamma = Cell({ id: 'gamma', formula, helperFactory, data }); 157 | const cell = Cell({ id: 'cell', formula: d => { 158 | return d.row('gamma') + 10; 159 | }, helperFactory, data }); 160 | 161 | const trx = Transaction({ init: true }); 162 | data.testCells.gamma.get(trx).should.eql(0); 163 | cell.get(trx).should.eql(10); 164 | 165 | cell.get().should.eql(10); 166 | cell.get().should.eql(10); 167 | cell.get().should.eql(10); 168 | cell.get().should.eql(10); 169 | cell.get().should.eql(10); 170 | cell.get().should.eql(10); 171 | count.should.eql(1); 172 | }); 173 | 174 | it('should support `object` formula', () => { 175 | const helperFactory = buildHelperFactory(helperFns, data); 176 | const cell = Cell({ id: 'cell', formula: { 177 | get: d => d.row('alpha') + 10, 178 | set: (d, value) => d.set(value - 10, d.cells.row('alpha')) 179 | }, helperFactory, data }); 180 | 181 | let trx = Transaction({ init: true }); 182 | cell.get(trx).should.eql(20); 183 | 184 | trx = Transaction(); 185 | cell.set(50, trx); 186 | 187 | trx.updates.should.deepEqual({ 188 | alpha: 40, 189 | cell: 50 190 | }); 191 | 192 | cell.get().should.eql(50); 193 | data.testCells.alpha.get().should.eql(40); 194 | }); 195 | 196 | it('should return the previous value', () => { 197 | const cell = Cell({ id: 'cell', formula: { 198 | get: (d, oldValue) => oldValue || 0, 199 | set: (d, value) => value 200 | }, helperFactory, data }); 201 | 202 | let trx = Transaction({ init: true }); 203 | cell.get(trx).should.eql(0); 204 | 205 | trx = Transaction(); 206 | cell.set(10, trx); 207 | cell.get().should.eql(10); 208 | 209 | trx = Transaction(); 210 | cell.set(20, trx); 211 | cell.get().should.eql(20); 212 | }); 213 | }); 214 | -------------------------------------------------------------------------------- /src/demo/.babelrc: -------------------------------------------------------------------------------- 1 | { 2 | "presets": ["env", "react"] 3 | } 4 | -------------------------------------------------------------------------------- /src/demo/.eslintrc.yml: -------------------------------------------------------------------------------- 1 | env: 2 | browser: true 3 | 4 | extends: 5 | - xo-react/space 6 | -------------------------------------------------------------------------------- /src/demo/demo.js: -------------------------------------------------------------------------------- 1 | import React from 'react'; 2 | import Grid from './grid'; 3 | 4 | const Demo = () => ( 5 |
6 |

TableModel ag-Grid Demo - https://github.com/target/table-model

7 | 8 |
9 | ); 10 | export default Demo; 11 | -------------------------------------------------------------------------------- /src/demo/grid.js: -------------------------------------------------------------------------------- 1 | /* eslint-disable */ 2 | import 'ag-grid/dist/styles/ag-grid.css'; 3 | import 'ag-grid/dist/styles/ag-theme-balham.css'; 4 | 5 | import { AgGridReact } from 'ag-grid-react'; 6 | import _ from 'lodash'; 7 | import React, { Component } from 'react'; 8 | 9 | import { updateTable, buildHighlighter } from '../ag-grid-utils'; 10 | import TableModel from '../index'; 11 | import rowDefs from './row-defs'; 12 | 13 | const rowDefsById = {}; 14 | _.each(rowDefs, row => rowDefsById[row.meta.id] = row); 15 | 16 | console.log('RowDefs:', rowDefs); 17 | console.log('RowDefsById:', rowDefsById); 18 | 19 | const twoDigits = ({ value }) => { 20 | if(!value) 21 | return null; 22 | 23 | return value.toFixed(2); 24 | }; 25 | 26 | class Grid extends Component { 27 | constructor(props) { 28 | super(props); 29 | 30 | this.onAGGridUpdate = params => { 31 | updateTable(this.state.tableModel, params); 32 | }; 33 | 34 | this.state = { 35 | agGrid: { 36 | columnDefs: [ 37 | { headerName: 'Week', field: 'meta.id', width: 75 }, 38 | { headerName: 'Color', field: 'meta.color', width: 75 }, 39 | { headerName: 'Population', field: 'population', width: 120, editable: true, cellClass: 'editable', valueFormatter: twoDigits }, 40 | { headerName: 'Food', field: 'food', width: 80, editable: true, cellClass: 'editable', valueFormatter: twoDigits }, 41 | { headerName: 'Health', field: 'health', width: 80, valueFormatter: twoDigits }, 42 | { headerName: 'Prev. Health', field: 'prevHealth', width: 115, valueFormatter: twoDigits }, 43 | { headerName: 'Health Delta', field: 'healthDelta', width: 115, valueFormatter: twoDigits }, 44 | { headerName: 'Rolling Food', field: 'rolling', width: 115, valueFormatter: twoDigits }, 45 | { headerName: 'Food By Color', field: 'colorSum', width: 125, valueFormatter: twoDigits }, 46 | ], 47 | defaultColDef: { 48 | valueSetter: this.onAGGridUpdate, 49 | cellClassRules: { 50 | affected: params => this.isAffectedCell(params) 51 | } 52 | }, 53 | getRowNodeId: data => data.id, 54 | onCellEditingStarted: params => this.onCellEditingStarted(params), 55 | onCellEditingStopped: params => this.onCellEditingStopped(params) 56 | }, 57 | }; 58 | } 59 | 60 | isAffectedCell(params) { 61 | const { affectedCells } = params.data; 62 | const { field } = params.colDef; 63 | 64 | return affectedCells && affectedCells.includes(field); 65 | } 66 | 67 | onCellEditingStarted(params) { 68 | this.state.highlighter.begin(params); 69 | } 70 | 71 | onCellEditingStopped(params) { 72 | this.state.highlighter.end(params); 73 | } 74 | 75 | onGridReady(params) { 76 | const { api } = params; 77 | 78 | let data = {}; 79 | 80 | const listener = update => { 81 | data = _.merge(data, update); 82 | 83 | const rowData = _.map(data, (row, id) => { 84 | const result = Object.assign({}, row); 85 | const meta = rowDefsById[id].meta; 86 | 87 | result.id = meta.id; 88 | result.meta = meta; 89 | 90 | return result; 91 | }); 92 | 93 | console.log('rowData', rowData); 94 | api.setRowData(rowData); 95 | }; 96 | 97 | const tableModel = TableModel({ rowDefs, listener }); 98 | const highlighter = buildHighlighter(tableModel); 99 | this.setState({ tableModel, highlighter }); 100 | } 101 | 102 | render() { 103 | return ( 104 |
105 |

Double-click on "Population" or "Food" to edit values and preview cells that will be impacted by the change

106 |

Ex. Double-click on 200 under "Food" in the first row and change it to 10000

107 | 108 | this.onGridReady(params)} {...this.state.agGrid} /> 109 | 110 |

111 | 112 | Cells that are editable 113 |

114 | 115 |

116 | 117 | Cells that will be affected by update 118 |

119 | 120 |

Formulas loaded into TableModel:

121 | 132 |
133 | ); 134 | } 135 | } 136 | export default Grid; 137 | -------------------------------------------------------------------------------- /src/demo/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | TableModel Demo 9 | 10 | 11 | 14 | 15 |
16 | 17 | 18 | -------------------------------------------------------------------------------- /src/demo/index.js: -------------------------------------------------------------------------------- 1 | import './index.scss'; 2 | 3 | import React from 'react'; 4 | import { render } from 'react-dom'; 5 | 6 | import Demo from './demo'; 7 | 8 | render(, document.getElementById('table-model-demo')); 9 | -------------------------------------------------------------------------------- /src/demo/index.scss: -------------------------------------------------------------------------------- 1 | body { 2 | position: absolute; 3 | top: 0; 4 | left: 0; 5 | 6 | width: 100%; 7 | height: 100%; 8 | 9 | margin: 0; 10 | } 11 | 12 | #table-model-demo { 13 | box-sizing: border-box; 14 | 15 | height: 100%; 16 | padding: 4px; 17 | 18 | .demo { 19 | display: flex; 20 | flex-direction: column; 21 | height: 100%; 22 | 23 | h1 { 24 | margin-top: 0; 25 | padding-top: 10px; 26 | } 27 | 28 | h3 { 29 | margin-top: 0; 30 | } 31 | 32 | .example { 33 | display: inline-block; 34 | 35 | width: 50px; 36 | height: 20px; 37 | 38 | margin-right: 4px; 39 | 40 | position: relative; 41 | top: 6px; 42 | } 43 | 44 | .highlight-example { 45 | border: 2px dashed blue; 46 | } 47 | 48 | .editable-example { 49 | padding: 2px; 50 | background-color: aquamarine; 51 | } 52 | 53 | .grid { 54 | width: 900px; 55 | height: 300px; 56 | 57 | .editable { 58 | background-color: aquamarine; 59 | } 60 | 61 | .affected { 62 | border: 2px dashed blue; 63 | } 64 | } 65 | } 66 | } 67 | -------------------------------------------------------------------------------- /src/demo/row-defs.js: -------------------------------------------------------------------------------- 1 | /* eslint-disable */ 2 | import _ from 'lodash'; 3 | 4 | const data = [ 5 | { id: 1, color: 'red', population: 100, food: 200 }, 6 | { id: 2, color: 'green', population: 150, food: 250 }, 7 | { id: 3, color: 'red', population: 175, food: 225 }, 8 | { id: 4, color: 'green', population: 215, food: 300 }, 9 | { id: 5, color: 'red', population: 285, food: 325 }, 10 | { id: 6, color: 'green', population: 300, food: 400 }, 11 | { id: 7, color: 'red', population: 335, food: 600 }, 12 | { id: 8, color: 'green', population: 400, food: 1000 }, 13 | ]; 14 | 15 | const metaFields = ['id', 'color']; 16 | 17 | const rowEquations = { 18 | health: { 19 | get: data => data.row('food') / data.row('population'), 20 | set: (data, health) => data.set(health * data.row('population'), data.cells.row('food')) 21 | }, 22 | prevHealth: data => data.prevRow('health'), 23 | healthDelta: data => data.row('health') - data.row('prevHealth'), 24 | rolling: data => data.prevRow('rolling') + data.row('food'), 25 | colorSum: data => { 26 | const values = data.rowsWhere({ color: data.meta('color') }, 'food'); 27 | return _.reduce(values, (total, value) => total + value); 28 | } 29 | }; 30 | 31 | const rowDefs = data.map(row => { 32 | const cells = Object.assign({}, rowEquations, row); 33 | return { 34 | meta: _.pick(row, metaFields), 35 | cells: _.omit(cells, metaFields) 36 | }; 37 | }); 38 | 39 | const firstRow = rowDefs[0]; 40 | firstRow.cells.rolling = data => data.row('food'); 41 | 42 | rowDefs.push({ 43 | meta: { 44 | id: 'TOTALS', 45 | }, 46 | cells: { 47 | population: { 48 | get: data => { 49 | const redCells = data.rowsWhere({ color: 'red' }, 'population'); 50 | const greenCells = data.rowsWhere({ color: 'green' }, 'population'); 51 | return _.reduce([...redCells, ...greenCells], (total, value) => total + value) 52 | }, 53 | set: (data, value, oldValue) => { 54 | const redCells = data.cells.rowsWhere({ color: 'red' }, 'population'); 55 | const greenCells = data.cells.rowsWhere({ color: 'green' }, 'population'); 56 | data.spread(value - oldValue, [...redCells, ...greenCells]); 57 | } 58 | }, 59 | food: { 60 | get: data => { 61 | const redCells = data.rowsWhere({ color: 'red' }, 'food'); 62 | const greenCells = data.rowsWhere({ color: 'green' }, 'food'); 63 | return _.reduce([...redCells, ...greenCells], (total, value) => total + value) 64 | }, 65 | set: (data, value, oldValue) => { 66 | const redCells = data.cells.rowsWhere({ color: 'red' }, 'food'); 67 | const greenCells = data.cells.rowsWhere({ color: 'green' }, 'food'); 68 | data.spread(value - oldValue, [...redCells, ...greenCells]); 69 | } 70 | } 71 | } 72 | }); 73 | 74 | export default rowDefs; 75 | -------------------------------------------------------------------------------- /src/demo/webpack.config.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | const HtmlWebpackPlugin = require('html-webpack-plugin'); 4 | 5 | module.exports = { 6 | entry: './src/demo/index.js', 7 | output: { 8 | path: process.cwd() + '/dist/demo', 9 | filename: 'index.js' 10 | }, 11 | 12 | module: { 13 | rules: [ 14 | { 15 | test: /\.s?css$/, 16 | use: [{ 17 | loader: 'style-loader' 18 | }, { 19 | loader: 'css-loader' 20 | }, { 21 | loader: 'sass-loader' 22 | }] 23 | }, 24 | { 25 | test: /\.js$/, 26 | exclude: /node_modules/, 27 | use: [{ 28 | loader: 'eslint-loader' 29 | }], 30 | enforce: 'pre' 31 | }, 32 | { 33 | test: /\.js$/, 34 | exclude: /node_modules/, 35 | use: [{ 36 | loader: 'babel-loader' 37 | }] 38 | } 39 | ] 40 | }, 41 | 42 | devtool: 'source-map', 43 | 44 | plugins: [ 45 | new HtmlWebpackPlugin({ template: './src/demo/index.html' }) 46 | ] 47 | }; 48 | -------------------------------------------------------------------------------- /src/example.spec.js: -------------------------------------------------------------------------------- 1 | import sinon from 'sinon'; 2 | 3 | import TableModel from './index'; 4 | 5 | describe('example', () => { 6 | it('should work', () => { 7 | // Formulas 8 | const totalEquation = d => d.row('a') + d.row('b') + d.row('c'); 9 | const extraEquation = d => d.row('b') * d.row('c'); 10 | 11 | // This builds a formula that matches a given color 12 | const colorTotals = color => { 13 | return d => { 14 | // Get the 'total's from all rows with the matching color 15 | const numbers = d.rowsWhere({ type: color }, 'total'); 16 | // Sum up the numbers to get to total 17 | return numbers.reduce((total, num) => total + num, 0); 18 | }; 19 | }; 20 | 21 | // This array contains a list of our rows and their cells 22 | const rowDefs = [ 23 | // Row 1 24 | { 25 | meta: { id: 1, type: 'red' }, 26 | cells: { a: 10, b: 20, c: 30, total: totalEquation } 27 | 28 | }, 29 | // Row 2 30 | { 31 | meta: { id: 2, type: 'green' }, 32 | // Rows don't have to have the same types of cells 33 | cells: { a: 12, b: 45, c: 38, d: 1234, total: totalEquation, extra: extraEquation } 34 | 35 | }, 36 | // Row 3 37 | { 38 | meta: { id: 3, type: 'red' }, 39 | cells: { a: 100, b: 200, c: 300, total: totalEquation } 40 | 41 | }, 42 | // Totals 43 | { 44 | meta: { id: 4 }, 45 | cells: { redTotal: colorTotals('red'), greenTotal: colorTotals('green') } 46 | } 47 | ]; 48 | 49 | const listener = sinon.spy(); 50 | 51 | const table = TableModel({ rowDefs, listener }); 52 | 53 | listener.callCount.should.eql(1); 54 | listener.getCall(0).args[0].should.deepEqual({ 55 | 1: { a: 10, b: 20, c: 30, total: 60 }, 56 | 2: { a: 12, b: 45, c: 38, d: 1234, total: 95, extra: 1710 }, 57 | 3: { a: 100, b: 200, c: 300, total: 600 }, 58 | 4: { redTotal: 660, greenTotal: 95 } 59 | }); 60 | 61 | table.update({ 2: { c: 123 } }); 62 | 63 | listener.callCount.should.eql(2); 64 | listener.getCall(1).args[0].should.deepEqual({ 65 | 2: { c: 123, total: 180, extra: 5535 }, 66 | 4: { greenTotal: 180 } 67 | }); 68 | }); 69 | }); 70 | -------------------------------------------------------------------------------- /src/helper-functions.js: -------------------------------------------------------------------------------- 1 | import _ from 'lodash'; 2 | 3 | import { isSuperSet } from './utils'; 4 | 5 | const helperFns = { 6 | // Functions that return either a cell or an array of cells 7 | cellHelpers: { 8 | row: input => cellName => input.row[cellName], 9 | prevRow: input => cellName => { 10 | const { rows, rowIndex } = input; 11 | const prevRow = rows[rowIndex - 1]; 12 | return prevRow ? prevRow[cellName] : null; 13 | }, 14 | rowsWhere: input => (rowCriteria, cellName) => { 15 | const rows = _.filter(input.rows, row => isSuperSet(row.meta, rowCriteria)); 16 | return rows.map(row => row[cellName]); 17 | } 18 | }, 19 | 20 | // Functions that return arbitrary data (ideally values, rather than objects, arrays, etc.) 21 | otherHelpers: { 22 | meta: input => prop => input.row.meta[prop], 23 | preLink: input => () => input.preLink, 24 | set: input => (value, cells) => { 25 | const { trx } = input; 26 | 27 | if(_.isArray(cells)) 28 | cells.forEach(cell => cell.set(value, trx)); 29 | else 30 | cells.set(value, trx); 31 | }, 32 | spread: input => (value, cells) => { 33 | const { trx } = input; 34 | 35 | const total = cells.reduce((total, cell) => total + cell.get(), 0); 36 | cells.forEach(cell => { 37 | const oldValue = cell.get(); 38 | const delta = total === 0 ? (value / cells.length) : (value * (oldValue / total)); 39 | const newValue = oldValue + delta; 40 | 41 | cell.set(newValue, trx); 42 | }); 43 | } 44 | } 45 | }; 46 | 47 | export default helperFns; 48 | -------------------------------------------------------------------------------- /src/index.js: -------------------------------------------------------------------------------- 1 | import Cell from './cell'; 2 | import TableModel from './table-model'; 3 | import * as agGrid from './ag-grid-utils'; 4 | 5 | TableModel.Cell = Cell; 6 | TableModel.agGrid = agGrid; 7 | 8 | export default TableModel; 9 | -------------------------------------------------------------------------------- /src/index.spec.js: -------------------------------------------------------------------------------- 1 | import 'should'; 2 | 3 | const context = require.context('.', true, /\.spec.js$/); 4 | context.keys().forEach(context); 5 | -------------------------------------------------------------------------------- /src/model.js: -------------------------------------------------------------------------------- 1 | import _ from 'lodash'; 2 | 3 | const Model = formula => { 4 | let model; 5 | 6 | if(_.isPlainObject(formula) && formula.get) { 7 | model = { 8 | getter: formula.get, 9 | setter: formula.set, 10 | value: null 11 | }; 12 | } else if(_.isFunction(formula)) { 13 | model = { 14 | getter: formula, 15 | value: null 16 | }; 17 | } else { 18 | // Is plain value 19 | model = { base: true, value: formula }; 20 | 21 | model.getter = () => model.value; 22 | model.setter = () => {}; // No-op here, this will be handler in the cell setter 23 | } 24 | 25 | return model; 26 | }; 27 | 28 | export default Model; 29 | -------------------------------------------------------------------------------- /src/table-model.js: -------------------------------------------------------------------------------- 1 | import _ from 'lodash'; 2 | 3 | import Cell from './cell'; 4 | import Transaction from './transaction'; 5 | 6 | import helperFns from './helper-functions'; 7 | import validate from './validation'; 8 | 9 | import { buildHelperFactory } from './utils'; 10 | 11 | const TableModel = ({ rowDefs, helpers, listener, preLink, columnList }) => { 12 | // Helpers 13 | const allHelpers = _.merge({}, helperFns, helpers || {}); 14 | 15 | // Listeners 16 | const listenerList = listener || []; 17 | const listeners = _.isArray(listenerList) ? listenerList : [listenerList]; 18 | 19 | const listen = listener => listeners.push(listener); 20 | 21 | const fireUpdate = update => { 22 | listeners.forEach(listener => listener(update)); 23 | }; 24 | 25 | // Pre-Link 26 | const preLinkData = {}; 27 | 28 | // Create rows of cells 29 | const cellMap = {}; 30 | const rows = []; 31 | const rowsById = {}; 32 | 33 | let cellIdCounter = 0; 34 | 35 | const mapUpdates = updates => { 36 | const mappedUpdates = {}; 37 | _.each(updates, (value, cellId) => { 38 | const cell = cellMap[cellId]; 39 | const { data } = cell; 40 | const rowId = data.meta.id; 41 | const { cellName } = data; 42 | 43 | const rowUpdates = mappedUpdates[rowId] || {}; 44 | rowUpdates[cellName] = value; 45 | mappedUpdates[rowId] = rowUpdates; 46 | }); 47 | 48 | return mappedUpdates; 49 | }; 50 | 51 | const addColumns = columnList => { 52 | _.each(rowDefs, (rowDef, rowIndex) => { 53 | const columns = columnList || Object.keys(rowDef.cells); 54 | const { meta } = rowDef; 55 | const { id } = meta; 56 | let row = rows.find(row => row.meta.id === id); 57 | if(!row) { 58 | row = { meta }; 59 | rows.push(row); 60 | } 61 | 62 | const helperFactory = buildHelperFactory(allHelpers, { meta, rows, row, rowIndex, preLink: preLinkData }); 63 | columns.forEach(col => { 64 | if(row[col]) 65 | return; 66 | const formula = rowDef.cells[col]; 67 | const id = ++cellIdCounter; 68 | const cell = Cell({ id, formula, data: { meta, row, cellName: col }, helperFactory }); 69 | cellMap[id] = cell; 70 | row[col] = cell; 71 | }); 72 | rowsById[id] = row; 73 | }); 74 | 75 | // Pre-link stage 76 | if(preLink) { 77 | const plData = preLink(rows); 78 | Object.assign(preLinkData, plData); 79 | } 80 | 81 | // Link and Fire Initial Update 82 | const initTrx = Transaction({ init: true }); 83 | _.each(rows, row => { 84 | const columns = columnList || Object.keys(row); 85 | _.each(columns, column => { 86 | const cell = row[column]; 87 | if(column === 'meta') 88 | return; 89 | if(cell) 90 | cell.get(initTrx); 91 | }); 92 | }); 93 | const { updates } = initTrx; 94 | const mappedUpdates = mapUpdates(updates); 95 | fireUpdate(mappedUpdates); 96 | }; 97 | 98 | const willAffect = data => { 99 | const errors = validate(data, rowsById); 100 | if(errors.length) { 101 | const msg = `There were validation errors:\n${errors.map(error => error.msg).join('\n')}`; 102 | 103 | const e = new Error(msg); 104 | e.errors = errors; 105 | throw e; 106 | } 107 | 108 | const affectedCells = {}; 109 | 110 | _.each(data, (rowUpdates, rowId) => { 111 | const row = rowsById[rowId]; 112 | 113 | // Apply each update 114 | _.each(rowUpdates, (value, prop) => { 115 | const cell = row[prop]; 116 | const dependentCells = cell.willAffect(); 117 | Object.assign(affectedCells, dependentCells); 118 | }); 119 | }); 120 | 121 | const result = {}; 122 | _.each(affectedCells, (value, cellId) => { 123 | const cell = cellMap[cellId]; 124 | 125 | const rowId = cell.data.row.meta.id; 126 | const { cellName } = cell.data; 127 | 128 | const cellNames = result[rowId] || []; 129 | cellNames.push(cellName); 130 | result[rowId] = cellNames; 131 | }); 132 | 133 | return result; 134 | }; 135 | 136 | // Update 137 | const update = data => { 138 | const errors = validate(data, rowsById); 139 | if(errors.length) { 140 | const msg = `There were validation errors: \n${errors.map(error => error.msg).join('\n')}`; 141 | 142 | const e = new Error(msg); 143 | e.errors = errors; 144 | throw e; 145 | } 146 | 147 | const trxUpdates = {}; 148 | 149 | _.each(data, (updates, id) => { 150 | // Get Row by Id 151 | const row = rowsById[id]; 152 | 153 | // Apply each update 154 | _.each(updates, (value, cellName) => { 155 | const cell = row[cellName]; 156 | 157 | const trx = Transaction(); 158 | cell.set(value, trx); 159 | 160 | // Records updates 161 | Object.assign(trxUpdates, trx.updates); 162 | }); 163 | }); 164 | 165 | const mappedUpdates = mapUpdates(trxUpdates); 166 | fireUpdate(mappedUpdates); 167 | }; 168 | 169 | addColumns(columnList); 170 | 171 | return { 172 | listen, 173 | rows, 174 | update, 175 | willAffect, 176 | preLinkData, 177 | addColumns 178 | }; 179 | }; 180 | 181 | export default TableModel; 182 | -------------------------------------------------------------------------------- /src/table-model.spec.js: -------------------------------------------------------------------------------- 1 | import _ from 'lodash'; 2 | import should from 'should'; 3 | import sinon from 'sinon'; 4 | import TableModel from './table-model'; 5 | 6 | const props = {}; 7 | 8 | describe('TableModel', () => { 9 | beforeEach(() => { 10 | const rowDefs = efficentRowDefs(); 11 | 12 | props.spy = sinon.spy(); 13 | props.tableModel = TableModel({ rowDefs, listener: props.spy }); 14 | }); 15 | 16 | it('should emit a complete initial update', () => { 17 | const { spy, tableModel } = props; 18 | 19 | tableModel.should.not.be.null(); 20 | 21 | spy.callCount.should.equal(1); 22 | spy.getCall(0).args[0].should.deepEqual({ 23 | 1: { units: 100, asp: 2, sales: 200, doubleAsp: 4, prevDoubleAsp: null, rolling: 200, colorSum: 1334 }, 24 | 2: { units: 150, asp: 1.6666666666666667, sales: 250, doubleAsp: 3.3333333333333335, prevDoubleAsp: 4, rolling: 323, colorSum: 150 }, 25 | 3: { units: 1234, asp: 4.60129659643436, sales: 5678, doubleAsp: 9.20259319286872, prevDoubleAsp: 3.3333333333333335, rolling: 446, colorSum: 1334 } 26 | }); 27 | 28 | tableModel.rows[0].units.get().should.equal(100); 29 | tableModel.rows[0].asp.get().should.equal(2); 30 | tableModel.rows[0].sales.get().should.equal(200); 31 | tableModel.rows[1].asp.get().should.be.approximately(1.6, 0.1); 32 | }); 33 | 34 | it('should be able to process updates that trigger all listeners', () => { 35 | const { spy, tableModel } = props; 36 | 37 | // Test A 38 | tableModel.update({ 1: { sales: 105 } }); 39 | 40 | spy.callCount.should.equal(2); 41 | spy.getCall(1).args[0].should.deepEqual({ 42 | 1: { asp: 1.05, sales: 105, doubleAsp: 2.1, rolling: 105 }, 43 | 2: { prevDoubleAsp: 2.1, rolling: 228 }, 44 | 3: { rolling: 351 } 45 | }); 46 | 47 | // Test B 48 | tableModel.update({ 1: { units: 123 } }); 49 | 50 | spy.callCount.should.equal(3); 51 | spy.getCall(2).args[0].should.deepEqual({ 52 | 1: { asp: 0.8536585365853658, doubleAsp: 1.7073170731707317, units: 123, colorSum: 1357 }, 53 | 2: { prevDoubleAsp: 1.7073170731707317 }, 54 | 3: { colorSum: 1357 } 55 | }); 56 | }); 57 | 58 | it('should be able to process updates on cells with setters', () => { 59 | const { spy, tableModel } = props; 60 | 61 | tableModel.update({ 2: { asp: 10 } }); 62 | 63 | spy.getCall(1).args[0].should.deepEqual({ 64 | 2: { asp: 10, sales: 1500, doubleAsp: 20 }, 65 | 3: { prevDoubleAsp: 20 } 66 | }); 67 | }); 68 | 69 | it('should be able to predict affect cells of an update', () => { 70 | const { tableModel } = props; 71 | 72 | let affectedCells = tableModel.willAffect({ 2: { asp: 10 } }); 73 | affectedCells.should.deepEqual({ 74 | 2: ['asp', 'doubleAsp', 'sales'], 75 | 3: ['prevDoubleAsp'] 76 | }); 77 | 78 | affectedCells = tableModel.willAffect({ 1: { doubleAsp: 50 } }); 79 | affectedCells.should.deepEqual({ 80 | 1: ['asp', 'doubleAsp', 'rolling', 'sales'], 81 | 2: ['prevDoubleAsp', 'rolling'], 82 | 3: ['rolling'] 83 | }); 84 | }); 85 | 86 | it('should throw an error when trying to update a cell that doesn\'t exist', () => { 87 | const { tableModel } = props; 88 | 89 | let error = null; 90 | should(() => { 91 | try { 92 | tableModel.update({ 1: { notHere: 123 } }); 93 | } catch(e) { 94 | error = e; 95 | throw e; 96 | } 97 | }).throw(); 98 | 99 | error.errors.should.deepEqual([{ 100 | msg: 'Cell "notHere" @ row 1 does not exist', 101 | row: '1', 102 | cell: 'notHere' 103 | }]); 104 | }); 105 | 106 | it('should throw an error when trying to update conflicting cells', () => { 107 | const { tableModel } = props; 108 | 109 | let error = null; 110 | should(() => { 111 | try { 112 | tableModel.update({ 2: { asp: 15, sales: 500 } }); 113 | } catch(e) { 114 | error = e; 115 | throw e; 116 | } 117 | }).throw(); 118 | 119 | error.errors.should.deepEqual([{ 120 | msg: 'Can\'t update "sales" @ row 2 and "asp" @ row 2 at the same time', 121 | rowA: '2', cellA: 'sales', 122 | rowB: '2', cellB: 'asp' 123 | }]); 124 | }); 125 | 126 | it('should throw an error when trying to update read-only cells', () => { 127 | const { tableModel } = props; 128 | 129 | let error = null; 130 | should(() => { 131 | try { 132 | tableModel.update({ 3: { prevDoubleAsp: 100 } }); 133 | } catch(e) { 134 | error = e; 135 | throw e; 136 | } 137 | }).throw(); 138 | 139 | error.errors.should.deepEqual([{ 140 | msg: 'Can\'t update "prevDoubleAsp" @ row 3', 141 | row: '3', cell: 'prevDoubleAsp' 142 | }]); 143 | }); 144 | 145 | it('should work with spreading', () => { 146 | const rowDefs = [ 147 | { 148 | meta: { id: 'test' }, 149 | cells: { 150 | total: { 151 | get: d => d.row('a') + d.row('b') + d.row('c') + d.row('d'), 152 | set: (d, value, oldValue) => d.spread(value - oldValue, [ 153 | d.cells.row('a'), d.cells.row('b'), d.cells.row('c'), d.cells.row('d') 154 | ]) 155 | }, 156 | a: 100, b: 200, c: 300, d: 400, 157 | otherTotal: d => d.row('b') + d.row('c') + d.row('d') } 158 | } 159 | ]; 160 | 161 | const listener = sinon.spy(); 162 | 163 | // Initial update 164 | const table = TableModel({ rowDefs, listener }); 165 | 166 | listener.callCount.should.eql(1); 167 | listener.getCall(0).args[0].should.deepEqual({ 168 | test: { 169 | a: 100, b: 200, c: 300, d: 400, 170 | total: 1000, otherTotal: 900 171 | } 172 | }); 173 | 174 | // Update 175 | table.update({ test: { total: 2000 } }); 176 | 177 | listener.callCount.should.eql(2); 178 | listener.getCall(1).args[0].should.deepEqual({ 179 | test: { 180 | a: 200, b: 400, c: 600, d: 800, 181 | total: 2000, otherTotal: 1800 182 | } 183 | }); 184 | }); 185 | 186 | it('should work with spreading where total is initially zero', () => { 187 | const rowDefs = [ 188 | { 189 | meta: { id: 'test' }, 190 | cells: { 191 | total: { 192 | get: d => d.row('a') + d.row('b') + d.row('c') + d.row('d'), 193 | set: (d, value, oldValue) => d.spread(value - oldValue, [ 194 | d.cells.row('a'), d.cells.row('b'), d.cells.row('c'), d.cells.row('d') 195 | ]) 196 | }, 197 | a: 0, b: 0, c: 0, d: 0, 198 | otherTotal: d => d.row('b') + d.row('c') + d.row('d') } 199 | } 200 | ]; 201 | 202 | const listener = sinon.spy(); 203 | 204 | // Initial update 205 | const table = TableModel({ rowDefs, listener }); 206 | 207 | listener.callCount.should.eql(1); 208 | listener.getCall(0).args[0].should.deepEqual({ 209 | test: { 210 | a: 0, b: 0, c: 0, d: 0, 211 | total: 0, otherTotal: 0 212 | } 213 | }); 214 | 215 | // Update 216 | table.update({ test: { total: 2000 } }); 217 | 218 | listener.callCount.should.eql(2); 219 | listener.getCall(1).args[0].should.deepEqual({ 220 | test: { 221 | a: 500, b: 500, c: 500, d: 500, 222 | total: 2000, otherTotal: 1500 223 | } 224 | }); 225 | }); 226 | 227 | describe('spreading', () => { 228 | it('should be able to support spreading', () => { 229 | // Set2: (data, mtd, oldMtd) => data.set(data.rowsWhere({x: 100}, 'sales')).spread(mtd - oldMtd) 230 | const mtdUnitsFormula = { 231 | get: data => { 232 | const cells = data.rowsWhere({ month: data.meta('mtd') }, 'units'); 233 | return cells.reduce((total, cell) => total + cell, 0); 234 | }, 235 | set: (data, mtd, oldMtd) => { 236 | const cellsForMonth = data.cells.rowsWhere({ month: data.meta('mtd') }, 'units'); 237 | data.spread(mtd - oldMtd, cellsForMonth); 238 | } 239 | }; 240 | 241 | const rowDefs = [ 242 | // Month A 243 | { meta: { id: 1, month: 1 }, cells: { units: 10 } }, 244 | { meta: { id: 2, month: 1 }, cells: { units: 20 } }, 245 | { meta: { id: 3, month: 1 }, cells: { units: 30 } }, 246 | { meta: { id: 4, month: 1 }, cells: { units: 40 } }, 247 | { 248 | meta: { id: 5, mtd: 1 }, 249 | cells: { units: mtdUnitsFormula } 250 | }, 251 | 252 | // Month B 253 | { meta: { id: 6, month: 2 }, cells: { units: 100 } }, 254 | { meta: { id: 7, month: 2 }, cells: { units: 200 } }, 255 | { meta: { id: 8, month: 2 }, cells: { units: 300 } }, 256 | { meta: { id: 9, month: 2 }, cells: { units: 400 } }, 257 | { meta: { id: 10, month: 2 }, cells: { units: 500 } }, 258 | { 259 | meta: { id: 11, mtd: 2 }, 260 | cells: { units: mtdUnitsFormula } 261 | }, 262 | 263 | // Month C 264 | { meta: { id: 12, month: 3 }, cells: { units: 1234 } }, 265 | { meta: { id: 13, month: 3 }, cells: { units: 5678 } } 266 | ]; 267 | 268 | const spy = sinon.spy(); 269 | const tableModel = TableModel({ rowDefs, listener: spy }); 270 | 271 | spy.callCount.should.equal(1); 272 | let update = spy.getCall(0).args[0]; 273 | let units = _.map(update, x => x.units); 274 | units.slice(0, 5).should.deepEqual([10, 20, 30, 40, 100]); 275 | units.slice(5, 11).should.deepEqual([100, 200, 300, 400, 500, 1500]); 276 | units.slice(11, 13).should.deepEqual([1234, 5678]); 277 | 278 | tableModel.update({ 11: { units: 2250 } }); 279 | 280 | spy.callCount.should.equal(2); 281 | update = spy.getCall(1).args[0]; 282 | units = _.map(update, x => x.units); 283 | units.should.deepEqual([150, 300, 450, 600, 750, 2250]); 284 | }); 285 | }); 286 | }); 287 | 288 | describe('TableModel add calculated column', () => { 289 | beforeEach(() => { 290 | const rowDefs = efficentRowDefs(); 291 | 292 | props.spy = sinon.spy(); 293 | props.tableModel = TableModel({ rowDefs, listener: props.spy, columnList: ['units', 'sales', 'asp'] }); 294 | }); 295 | 296 | it('should columns in list and should be able to add new column', () => { 297 | const { spy, tableModel } = props; 298 | tableModel.should.not.be.null(); 299 | 300 | spy.callCount.should.equal(1); 301 | spy.getCall(0).args[0].should.deepEqual({ 302 | 1: { units: 100, asp: 2, sales: 200 }, 303 | 2: { units: 150, asp: 1.6666666666666667, sales: 250 }, 304 | 3: { units: 1234, asp: 4.60129659643436, sales: 5678 } 305 | }); 306 | 307 | tableModel.addColumns(['doubleAsp']); 308 | spy.callCount.should.equal(2); 309 | spy.getCall(1).args[0].should.deepEqual({ 310 | 1: { units: 100, asp: 2, sales: 200, doubleAsp: 4 }, 311 | 2: { units: 150, asp: 1.6666666666666667, sales: 250, doubleAsp: 3.3333333333333335 }, 312 | 3: { units: 1234, asp: 4.60129659643436, sales: 5678, doubleAsp: 9.20259319286872 } 313 | }); 314 | 315 | tableModel.rows[0].units.get().should.equal(100); 316 | tableModel.rows[0].asp.get().should.equal(2); 317 | tableModel.rows[0].sales.get().should.equal(200); 318 | tableModel.rows[1].asp.get().should.be.approximately(1.6, 0.1); 319 | }); 320 | 321 | it('should not reset already added columns', () => { 322 | const { spy, tableModel } = props; 323 | tableModel.should.not.be.null(); 324 | 325 | spy.callCount.should.equal(1); 326 | spy.getCall(0).args[0].should.deepEqual({ 327 | 1: { units: 100, asp: 2, sales: 200 }, 328 | 2: { units: 150, asp: 1.6666666666666667, sales: 250 }, 329 | 3: { units: 1234, asp: 4.60129659643436, sales: 5678 } 330 | }); 331 | 332 | tableModel.update({ 1: { units: 200 } }); 333 | tableModel.addColumns(['doubleAsp', 'units']); 334 | spy.callCount.should.equal(3); 335 | 336 | spy.getCall(2).args[0].should.deepEqual({ 337 | 1: { units: 200, asp: 1, sales: 200, doubleAsp: 2 }, 338 | 2: { units: 150, asp: 1.6666666666666667, sales: 250, doubleAsp: 3.3333333333333335 }, 339 | 3: { units: 1234, asp: 4.60129659643436, sales: 5678, doubleAsp: 9.20259319286872 } 340 | }); 341 | 342 | tableModel.rows[0].units.get().should.equal(200); 343 | tableModel.rows[0].asp.get().should.equal(1); 344 | tableModel.rows[0].doubleAsp.get().should.equal(2); 345 | tableModel.rows[0].sales.get().should.equal(200); 346 | tableModel.rows[1].asp.get().should.be.approximately(1.6, 0.1); 347 | }); 348 | }); 349 | 350 | function efficentRowDefs() { 351 | const cellsTemplate = { 352 | asp: { 353 | get: data => data.row('sales') / data.row('units'), 354 | set: (data, asp) => data.set(asp * data.row('units'), data.cells.row('sales')) 355 | }, 356 | doubleAsp: { 357 | get: data => data.row('asp') * 2, 358 | set: (data, doubleAsp) => data.set(doubleAsp / 2, data.cells.row('asp')) 359 | }, 360 | prevDoubleAsp: data => data.prevRow('doubleAsp'), 361 | rolling: data => data.prevRow('rolling') + 123, 362 | colorSum: data => { 363 | const values = data.rowsWhere({ style: data.meta('style') }, 'units'); 364 | return _.reduce(values, (total, value) => total + value); 365 | } 366 | }; 367 | 368 | const data = [ 369 | { id: 1, style: 'red', units: 100, sales: 200 }, 370 | { id: 2, style: 'green', units: 150, sales: 250 }, 371 | { id: 3, style: 'red', units: 1234, sales: 5678 } 372 | ]; 373 | 374 | const metaFields = ['id', 'style']; 375 | const rowDefs = data.map(row => { 376 | const cells = { ...cellsTemplate, ...row }; 377 | return { 378 | meta: _.pick(row, metaFields), 379 | cells: _.omit(cells, metaFields) 380 | }; 381 | }); 382 | 383 | const firstRow = rowDefs[0]; 384 | firstRow.cells.rolling = data => data.row('sales'); 385 | 386 | return rowDefs; 387 | } 388 | 389 | function manualRowDefs() { // eslint-disable-line no-unused-vars 390 | return [ 391 | { 392 | meta: { id: 1, style: 'red' }, 393 | cells: { 394 | units: 100, 395 | asp: { 396 | get: data => data.row('sales') / data.row('units'), 397 | set: (data, asp) => data.set(asp * data.row('units'), data.cells.row('sales')) 398 | }, 399 | sales: 200, 400 | doubleAsp: { 401 | get: data => data.row('asp') * 2, 402 | set: (data, doubleAsp) => data.set(doubleAsp / 2, data.cells.row('asp')) 403 | }, 404 | prevDoubleAsp: data => data.prevRow('doubleAsp'), 405 | rolling: data => data.row('sales'), 406 | colorSum: data => { 407 | const values = data.rowsWhere({ style: data.meta('style') }, 'units'); 408 | return _.reduce(values, (total, value) => total + value); 409 | } 410 | } 411 | }, 412 | { 413 | meta: { id: 2, style: 'green' }, 414 | cells: { 415 | units: 150, 416 | asp: { 417 | get: data => data.row('sales') / data.row('units'), 418 | set: (data, asp) => data.set(asp * data.row('units'), data.cells.row('sales')) 419 | }, 420 | sales: 250, 421 | doubleAsp: { 422 | get: data => data.row('asp') * 2, 423 | set: (data, doubleAsp) => data.set(doubleAsp / 2, data.cells.row('asp')) 424 | }, 425 | prevDoubleAsp: data => data.prevRow('doubleAsp'), 426 | rolling: data => data.prevRow('rolling') + 123, 427 | colorSum: data => { 428 | const values = data.rowsWhere({ style: data.meta('style') }, 'units'); 429 | return _.reduce(values, (total, value) => total + value); 430 | } 431 | } 432 | }, 433 | { 434 | meta: { id: 3, style: 'red' }, 435 | cells: { 436 | units: 1234, 437 | asp: { 438 | get: data => data.row('sales') / data.row('units'), 439 | set: (data, asp) => data.set(asp * data.row('units'), data.cells.row('sales')) 440 | }, 441 | sales: 5678, 442 | doubleAsp: { 443 | get: data => data.row('asp') * 2, 444 | set: (data, doubleAsp) => data.set(doubleAsp / 2, data.cells.row('asp')) 445 | }, 446 | prevDoubleAsp: data => data.prevRow('doubleAsp'), 447 | rolling: data => data.prevRow('rolling') + 123, 448 | colorSum: data => { 449 | const values = data.rowsWhere({ style: data.meta('style') }, 'units'); 450 | return _.reduce(values, (total, value) => total + value); 451 | } 452 | } 453 | } 454 | ]; 455 | } 456 | -------------------------------------------------------------------------------- /src/transaction.js: -------------------------------------------------------------------------------- 1 | const Transaction = (options = {}) => { 2 | const init = options.init || false; 3 | const dryRun = options.dryRun || false; 4 | 5 | return { init, cellStack: [], dryRun, stale: {}, updates: {} }; 6 | }; 7 | 8 | export default Transaction; 9 | -------------------------------------------------------------------------------- /src/utils.js: -------------------------------------------------------------------------------- 1 | import _ from 'lodash'; 2 | 3 | export const isSuperSet = (a, b) => { 4 | const picked = _.pick(a, _.keys(b)); 5 | return _.isEqual(picked, b); 6 | }; 7 | 8 | const mapCellHelperToValueHelper = (cellHelper, input) => { 9 | return (...args) => { 10 | const cells = cellHelper(...args); 11 | const { trx } = input; 12 | 13 | let result; 14 | if(_.isArray(cells)) 15 | result = cells.map(cell => cell.get(trx)); 16 | else 17 | result = cells ? cells.get(trx) : null; 18 | 19 | return result; 20 | }; 21 | }; 22 | 23 | export const buildHelperFactory = (helperFns, data) => { 24 | const { cellHelpers, otherHelpers } = helperFns; 25 | 26 | // Build input 27 | const input = { ...data }; 28 | 29 | const boundCellHelpers = _.mapValues(cellHelpers, helperBuilder => helperBuilder(input)); 30 | const boundOtherHelpers = _.mapValues(otherHelpers, helperBuilder => helperBuilder(input)); 31 | 32 | const boundValueHelpers = _.mapValues(boundCellHelpers, cellHelper => mapCellHelperToValueHelper(cellHelper, input)); 33 | 34 | const result = { ...boundValueHelpers, ...boundOtherHelpers }; 35 | result.cells = boundCellHelpers; 36 | 37 | return trx => { 38 | input.trx = trx; 39 | return result; 40 | }; 41 | }; 42 | -------------------------------------------------------------------------------- /src/validation.js: -------------------------------------------------------------------------------- 1 | import _ from 'lodash'; 2 | 3 | const validate = (data, rowsById) => { 4 | const errors = []; 5 | 6 | _.each(data, (updateRow, rowId) => { 7 | _.each(updateRow, (value, cellName) => { 8 | // Get Dependents for each update 9 | const row = rowsById[rowId]; 10 | const cell = row[cellName]; 11 | 12 | // VALIDATION: Check that cell exists for update 13 | if(cell === undefined) { 14 | const msg = `Cell "${cellName}" @ row ${rowId} does not exist`; 15 | errors.push({ msg, row: rowId, cell: cellName }); 16 | return; 17 | } 18 | 19 | // VALIDATION: Check for update conflict 20 | const { dependents } = cell; 21 | dependents.forEach(cell => { 22 | const uRowId = cell.data.row.meta.id; 23 | const uRow = data[uRowId]; 24 | 25 | const { cellName: depCellName } = cell.data; 26 | if(uRow && uRow[depCellName]) { 27 | const msg = `Can't update "${cellName}" @ row ${rowId} and ` + 28 | `"${depCellName}" @ row ${uRowId} at the same time`; 29 | errors.push({ 30 | msg, 31 | rowA: rowId, cellA: cellName, 32 | rowB: uRowId.toString(), cellB: depCellName 33 | }); 34 | } 35 | }); 36 | 37 | // VALIDATION: Check for updates on read-only cells 38 | if(!cell.hasSetter) { 39 | const msg = `Can't update "${cellName}" @ row ${rowId}`; 40 | errors.push({ msg, row: rowId, cell: cellName }); 41 | } 42 | }); 43 | }); 44 | 45 | return errors; 46 | }; 47 | 48 | export default validate; 49 | -------------------------------------------------------------------------------- /webpack.config.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | module.exports = { 4 | entry: './src/index.js', 5 | output: { 6 | filename: './dist/table-model.js', 7 | library: 'tableModel', 8 | libraryExport: 'default', 9 | libraryTarget: 'umd', 10 | }, 11 | 12 | module: { 13 | rules: [ 14 | { 15 | test: /\.js$/, 16 | exclude: /node_modules/, 17 | use: [ 18 | { 19 | loader: 'eslint-loader', 20 | }, 21 | ], 22 | enforce: 'pre', 23 | }, 24 | { 25 | test: /\.js$/, 26 | exclude: /node_modules/, 27 | use: [ 28 | { 29 | loader: 'babel-loader', 30 | }, 31 | ], 32 | }, 33 | ], 34 | }, 35 | 36 | devtool: 'source-map', 37 | }; 38 | --------------------------------------------------------------------------------