You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/index.html
+21-11Lines changed: 21 additions & 11 deletions
Original file line number
Diff line number
Diff line change
@@ -73,22 +73,32 @@
73
73
<divclass="page-wrapper">
74
74
<divclass="content">
75
75
<h1id="getting-started">Getting started</h1>
76
-
<p>Type-R is the universal state management framework for both UI and domain state.</p>
77
-
<p>Application state is described with the superposition of two main container types - <ahref="04_Record/00_Overview.md">Record</a> and <ahref="./05_Collection/00_Overview.md">Collection</a> of records. The state has observable changes and is serializable by default.</p>
76
+
<p>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:</p>
78
77
<ul>
79
-
<li>Records are classes with typed attributes. They are protected from attributes assignment of incompatible types with run-time type assertions and conversions. Which means that the client-server protocol is protected from both ends.</li>
80
-
<li>Records distinguish <ahref="06_API_by_feature/01_Aggregation_tree.md">aggregated attributes</a> and those which are <ahref="06_API_by_feature/04_Shared_objects.md">references to shared objects</a>. Aggregated attributes are serialized as nested JSON, while references might be <ahref="06_API_by_feature/05_id-references_and_Stores.md">serialized as ids</a>. Operations like <code>clone()</code>, <code>dispose()</code>, and <code>toJSON()</code> are performed recursively on elements of aggregation tree.</li>
78
+
<li><em>Record</em> classes with typed attributes.</li>
79
+
<li>Ordered <em>collections</em> of records.</li>
80
+
<li><em>Stores</em> to hold collections used to resolve id-references in JSON.</li>
81
+
</ul>
82
+
<p>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 communication protocol.</p>
83
+
<p>Type-R is your perfect M and VM in MVVM and MVC architecture imposing no restrictions on V and C parts.</p>
84
+
<h2id="installation-and-requirements">Installation and Requirements</h2>
85
+
<p>Is packed as UMD and ES6 module. No peer dependencies are required.</p>
86
+
<p><code>npm install type-r --save-dev</code></p>
87
+
<asideclass="success">IE10+, Edge, Safari, Chrome, and Firefox are supported</aside>
88
+
89
+
<asideclass="warning">IE9 and Opera may work but has not been tested. IE8 won't work.</aside>
90
+
91
+
<h2id="how-the-type-r-compares-with-x-">How the Type-R compares with X?</h2>
92
+
<p>The closest things to the Type-R are <ahref="https://guides.emberjs.com/v2.2.0/models/">Ember Data</a>, <ahref="http://backbonejs.org/#Model">BackboneJS models and collections</a>, and <ahref="https://github.com/mobxjs/mobx">mobx</a>. It has an API resembling the one in BackboneJS, it supports transactional observable changes in the way close to mobx, and it has powerful serialization and validation capabilities as Ember Data.</p>
93
+
<ul>
94
+
<li><p>Records attributes are typed at run-time. They are protected from assignment of incompatible types with run-time type assertions and conversions. Which means that the client-server protocol is protected agains errors from both ends. There are no </p>
95
+
</li>
96
+
<li><p>Records distinguish <ahref="06_API_by_feature/01_Aggregation_tree.md">aggregated attributes</a> and those which are <ahref="06_API_by_feature/04_Shared_objects.md">references to shared objects</a>. Aggregated attributes are serialized as nested JSON, while references might be <ahref="06_API_by_feature/05_id-references_and_Stores.md">serialized as ids</a>. Operations like <code>clone()</code>, <code>dispose()</code>, and <code>toJSON()</code> are performed recursively on elements of aggregation tree.</p>
97
+
</li>
81
98
<li>Type-R features declarative <ahref="06_API_by_feature/03_Validation.md">validation</a> with attribute-level rules. Validation is transparent and lazily evaluated.</li>
82
99
<li>Architecture does not depend on stores and singletons. <ahref="05_API_by_feature/05_id-references_and_Stores.md">Stores</a> are optional and used for shared data only. There might be as many stores as you need, and they can be created and disposed dynamically.</li>
83
100
<li>Type-R data structures are pretty efficient. They are about 10 times faster in real-world data scenarios than BackboneJS.</li>
84
101
</ul>
85
-
<h2id="installation">Installation</h2>
86
-
<p>Is packed as UMD and ES6 module. No side dependencies.</p>
87
-
<p><code>npm install type-r --save-dev</code></p>
88
-
<h2id="requirements">Requirements</h2>
89
-
<p>IE10+, Edge, Safari, Chrome, and Firefox are supported.</p>
90
-
<p>IE9 and Opera may work but has not been tested. IE8 <em>won't work</em>.</p>
91
-
<h2id="how-the-type-r-compares-with-x-">How the Type-R compares with X?</h2>
92
102
<p>Type-R is designed to be the substitution for BackboneJS, which was used extensively 3 years ago in Volicon/Verizon Observer products. While it largely backward compatible by its API with BackboneJS (for Events and Collections), it's entirely different internally.</p>
93
103
<p>In its core, it's an engine for managing the <em>aggregation trees</em> composed of nested Records and Collections. It contains no View, Router, REST, and jQuery/Underscore dependencies.</p>
Copy file name to clipboardExpand all lines: docs/index.md
+35-23Lines changed: 35 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,40 +18,52 @@ search: true
18
18
19
19
# Getting started
20
20
21
-
Type-R is the universal state management framework for both UI and domain state.
21
+
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:
22
22
23
-
Application state is described with the superposition of two main container types - [Record](04_Record/00_Overview.md) and [Collection](./05_Collection/00_Overview.md) of records. The state has observable changes and is serializable by default.
23
+
-*Record* classes with typed attributes.
24
+
- Ordered *collections* of records.
25
+
-*Stores* to hold collections used to resolve id-references in JSON.
24
26
25
-
- Records are classes with typed attributes. They are protected from attributes assignment of incompatible types with run-time type assertions and conversions. Which means that the client-server protocol is protected from both ends.
26
-
- Records distinguish [aggregated attributes](06_API_by_feature/01_Aggregation_tree.md) and those which are [references to shared objects](06_API_by_feature/04_Shared_objects.md). Aggregated attributes are serialized as nested JSON, while references might be [serialized as ids](06_API_by_feature/05_id-references_and_Stores.md). Operations like `clone()`, `dispose()`, and `toJSON()` are performed recursively on elements of aggregation tree.
27
-
- Type-R features declarative [validation](06_API_by_feature/03_Validation.md) with attribute-level rules. Validation is transparent and lazily evaluated.
28
-
- Architecture does not depend on stores and singletons. [Stores](05_API_by_feature/05_id-references_and_Stores.md) are optional and used for shared data only. There might be as many stores as you need, and they can be created and disposed dynamically.
29
-
- Type-R data structures are pretty efficient. They are about 10 times faster in real-world data scenarios than BackboneJS.
27
+
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.
30
28
31
-
## Installation
29
+
Type-R is your perfect M and VM in MVVM and MVC architecture imposing no restrictions on V and C parts.
32
30
33
-
Is packed as UMD and ES6 module. No side dependencies.
31
+
## How the Type-R compares with X?
34
32
35
-
`npm install type-r --save-dev`
33
+
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.
36
34
37
-
## Requirements
35
+
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).
38
36
39
-
IE10+, Edge, Safari, Chrome, and Firefox are supported.
37
+
There are a lot of similarities:
40
38
41
-
IE9 and Opera may work but has not been tested. IE8 _won't work_.
39
+
- All that things can be used to manage an application's state.
40
+
- 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).
41
+
- 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.
42
+
- 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).
42
43
43
-
## How the Type-R compares with X?
44
+
Speaking of the distinguishing differences,
44
45
45
-
Type-R is designed to be the substitution for BackboneJS, which was used extensively 3 years ago in Volicon/Verizon Observer products. While it largely backward compatible by its API with BackboneJS (for Events and Collections), it's entirely different internally.
46
+
- 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.
47
+
- 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.
48
+
- 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.
49
+
- 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.
50
+
- 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.
46
51
47
-
In its core, it's an engine for managing the _aggregation trees_ composed of nested Records and Collections. It contains no View, Router, REST, and jQuery/Underscore dependencies.
48
-
49
-
Feature | Type-R | BackboneJS | EmberJS | mobx
52
+
Feature | Type-R | Backbone Models | Ember Data | mobx
50
53
-|-|-|-|-
51
-
View and Router | - | ✓ | ✓ | -
52
-
Models | ✓ | ✓ | ✓ | Objects as models
53
-
Collections | ✓ | ✓ | modeled as relations | Arrays as collections
54
-
Nested Data Strictures | as aggregation trees and relations | - | as relations | as object graph
55
-
Relations by id | resolved agains the chain of dynamic stores | - | resolved agains the global store | -
0 commit comments