|
4 | 4 |
|
5 | 5 | # Getting started |
6 | 6 |
|
7 | | -Type-R helps to declaratively define complex domain and UI application state in modern JS applications as a superposition of three kinds of building blocks: |
| 7 | +Type-R is the modern JS data framework allowing declaratively definitions of complex domain and UI application state. The state is defined as the superposition of JS classes extending `Record` and `Collection`, and has following features: |
| 8 | + |
| 9 | +- _It's mapped to JSON by default_. The mapping can handle sophisticated scenarios with nested JSON and relations by id, and can be easily customized for every particular attribute or class. |
| 10 | +- _All changes are observable_, happens in the scope of transactions, and there's the fine-grained change events system. |
| 11 | +- _Validation_ is performed on the first access to the validation error and never happens twice for unchanged data. |
| 12 | +- _Everything is typed at run-time_ and is protected from improper updates. The shape of generated JSON and data classes is guaranteed to match the definitions. |
| 13 | +- It still looks like regular JS classes and is freaking fast. Type-R data structures are about 10 times faster than Backbone models and collections. |
| 14 | + |
| 15 | + |
| 16 | + |
| 17 | +Data layer is defined as a superposition of three kinds of building blocks: |
8 | 18 |
|
9 | 19 | - *Record* classes with typed attributes. |
10 | 20 | - Ordered *collections* of records. |
11 | | -- *Stores* to hold collections used to resolve id-references in JSON. |
| 21 | +- *Stores* are records with a set of collections in its attributes used to resolve id-references in JSON. |
12 | 22 |
|
13 | | -The state defined with Type-R classes is deeply observable and serializable by default. While being an advanced JSON serialization engine handling sophisticated scenarios (like cross-collections many-to-many relationships), Type-R is completely unopinionated on the client-server transport protocol. |
| 23 | +Type-R is completely unopinionated on the client-server transport protocol and the view layer technology. It's your perfect M and VM in modern MVVM or MVC architecture. |
14 | 24 |
|
15 | | -Type-R is your perfect M and VM in MVVM and MVC architecture imposing no restrictions on V and C parts. |
| 25 | +```javascript |
| 26 | +import { define, Record } from 'type-r' |
16 | 27 |
|
17 | | -API docs site: https://volicon.github.io/Type-R/ |
| 28 | +// Define email attribute type with encapsulated validation check. |
| 29 | +const Email = String.has.check( x => x! || x.indexOf( '@' ) >= 0, 'Invalid email' ); |
18 | 30 |
|
19 | | -## Installation and requirements |
| 31 | +@define class User extends Record { |
| 32 | + static attributes = { |
| 33 | + name : String.isRequired, // should not be empty for the record to be valid. |
| 34 | + email : Email.isRequired |
| 35 | + } |
| 36 | +} |
20 | 37 |
|
21 | | -Is packed as UMD and ES6 module. No peer dependencies are required. |
| 38 | +@define class Message extends Record { |
| 39 | + static attributes = { |
| 40 | + created : Date // = new Date() |
| 41 | + author : User, // aggregated User record. |
| 42 | + to : User.Collection, // aggregating collection of users |
| 43 | + subject : '', |
| 44 | + body : '' |
| 45 | + } |
| 46 | +} |
22 | 47 |
|
23 | | -`npm install type-r --save-dev` |
| 48 | +const msg = new Message(); |
| 49 | +assert( !msg.isValid() ); // Is not valid because msg.author has empty attributes |
24 | 50 |
|
25 | | -<aside class="success">IE10+, Edge, Safari, Chrome, and Firefox are supported</aside> |
| 51 | +// Listen for the changes in aggregation tree... |
| 52 | +msg.on( 'change', () => console.log( 'change!!!' ) ); |
26 | 53 |
|
27 | | -<aside class="warning">IE9 and Opera may work but has not been tested. IE8 won't work.</aside> |
| 54 | +msg.transaction( () => { // Prepare to make the sequence of changes on msg |
| 55 | + msg.author.name = 'John Dee'; // No 'change' event yet as we're in the transaction. |
| 56 | + msg. author. email = '[email protected]'; |
28 | 57 |
|
29 | | -## How the Type-R compares with X? |
| 58 | + assert( msg.isValid() ); // Now msg is valid as all of its attributes are valid. |
| 59 | +}); // Got single 'change!!!' message in the console. |
| 60 | +``` |
30 | 61 |
|
31 | | -Type-R started to develop in 2014 as the modern substitution for BackboneJS, which would retain the spirit of the BackboneJS simplicity but would be superior to Ember Data in its capabilities and an order of magnitude faster than Backbone. |
32 | 62 |
|
33 | | -The closest things to the Type-R are [Ember Data](https://guides.emberjs.com/v2.2.0/models/), [BackboneJS models and collections](http://backbonejs.org/#Model), and [mobx](https://github.com/mobxjs/mobx). |
| 63 | +## [Documentation](https://volicon.github.io/Type-R/) |
34 | 64 |
|
35 | | -There are a lot of similarities: |
| 65 | +## Installation and requirements |
36 | 66 |
|
37 | | -- All that things can be used to manage an application's state. |
38 | | -- Type-R handles observable transactional changes in the way more or less similar to mobx (however, it's heavily optimized for the case of large aggregated object trees). |
39 | | -- Type-R id-relationships and validation capabilities are comparable to ones in [Ember Data](https://guides.emberjs.com/v2.2.0/models/relationships/), which was used a source of inspiration. |
40 | | -- Type-R has a lot of common in some API parts with BackboneJS models and collections. For instance, it uses the close API for the [collection updates](#update) and the [similar event model](#built-in-events) for the changes (however, it's generalized for the case of transactions on the nested records and collections). |
| 67 | +Is packed as UMD and ES6 module. No peer dependencies are required. |
41 | 68 |
|
42 | | -Speaking of the distinguishing differences, |
| 69 | +`npm install type-r --save-dev` |
43 | 70 |
|
44 | | -- Type-R's records are not key-value pairs but _classes_ with typed attributes. They are protected from improper assignment with run-time type assertions and conversions. Which means that the client-server protocol is protected again errors from both ends. |
45 | | -- Type-R distinguishes aggregation and the plain association operating with _aggregation trees_ formed by nested records and collections. Aggregation tree is serialized as nested JSON. Operations like `clone()`, `dispose()`, `isValid()` and `toJSON()` are performed recursively on elements of aggregation tree gracefully handling the references to shared objects. |
46 | | -- Type-R relies on _layered application state_ instead of the global singleton store. In Type-R, the stores are the special kind of records which can participate in dynamically configured lookup chains. There might be as many dynamically created and disposed stores as you need, starting with no stores at all. |
47 | | -- Type-R features automatic lazily evaluated [validation](#validation) with declarative attribute-level rules. Validation checks are the part of the attribute type; they are evaluated in the moment they needed and never performed twice on the unchanged data. |
48 | | -- Type-R is really fast. It's capable of handling collections of 10K elements with real-time response and is about 10 times faster than BackboneJS. |
| 71 | +<aside class="success">IE10+, Edge, Safari, Chrome, and Firefox are supported</aside> |
49 | 72 |
|
50 | | -Feature | Type-R | Backbone Models | Ember Data | mobx |
51 | | --|-|-|-|- |
52 | | -Observable changes in object graph | ✓ | - | - | ✓ |
53 | | -JSON Serialization | ✓ | ✓ | ✓ | - |
54 | | -Validation | ✓ | ✓ | ✓ | - |
55 | | -Dynamic Type Safety | ✓ | - | For serialization only | - |
56 | | -Aggregation | ✓ | - | - | - |
57 | | -Relations by id | ✓ | - | ✓ | - |
| 73 | +<aside class="warning">IE9 and Opera may work but has not been tested. IE8 won't work.</aside> |
58 | 74 |
|
59 | 75 | ## Roadmap |
60 | 76 |
|
|
0 commit comments