New site

Author: Vlad Balin

docs/00_Getting_Started.md

@@ -0,0 +1,40 @@
+# Introduction
+
+Type-R is the universal state management framework for both UI and domain state.
+
+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.
+
+- 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.
+- 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.
+- Type-R features declarative [validation](06_API_by_feature/03_Validation.md) with attribute-level rules. Validation is transparent and lazily evaluated.
+- 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.
+- Type-R data structures are pretty efficient. They are about 10 times faster in real-world data scenarios than BackboneJS.
+
+# Installation
+
+Is packed as UMD and ES6 module. No side dependencies.
+
+`npm install type-r --save-dev`
+
+## Requirements
+
+IE10+, Edge, Safari, Chrome, and Firefox are supported.
+
+IE9 and Opera may work but has not been tested. IE8 _won't work_.
+
+# FAQ
+## How the Type-R compares with X?
+
+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.
+
+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.
+
+Feature | Type-R | BackboneJS | EmberJS | mobx
+-|-|-|-|-
+View and Router | - | ✓ | ✓ | - |
+Models | ✓ | ✓ | ✓ | Objects as models
+Collections | ✓ | ✓ | modeled as relations | Arrays as collections
+Nested Data Strictures | as aggregation trees and relations | - | as relations | as object graph
+Relations by id | resolved agains the chain of dynamic stores | - | resolved agains the global store | - 
+JSON Serialization | ✓ | ✓ | ✓ | -
+Validation | ✓ | ✓ | ✓ | -

docs/04_Record/00_Overview.md

@@ -0,0 +1,169 @@
+Record is the serializable class with typed attributes, observable changes, and custom validation checks. It is the main building block for managing the application state; component local state, stores, and collection elements are all subclasses of the `Record`.
+
+In contrast to the "model" class in the majority of data frameworks, Record is *not the key-value hash*. It's the class with statically defined set of attributes of known types.
+
+`Record` itself is an abstract class. The subclass needs to be defined for every data structure of different shape, in a similar way as it's done in statically typed languages.
+
+```javascript
+import { define, Record } from 'type-r'
+
+// ⤹ required to make magic work  
+@define class User extends Record {
+    // ⤹ attribute's declaration
+    static attributes = {
+        firstName : '', // ⟵ String type is inferred from the default value
+        lastName  : String, // ⟵ Or you can just mention its constructor
+        email     : String.value( null ), //⟵ Or you can provide both
+        createdAt : Date, // ⟵ And it works for any constructor.
+        // And you can attach ⤹ metadata to fine-tune attribute's behavior
+        lastLogin : Date.value( null ).has.toJSON( false ) // ⟵ not serializable
+    }
+}
+
+const user = new User();
+console.log( user.createdAt ); // ⟵ this is an instance of Date created for you.
+
+const users = new User.Collection(); // ⟵ Collections are defined automatically.
+users.on( 'changes', () => updateUI( users ) ); // ⟵ listen to the changes.
+
+users.set( json, { parse : true } ); // ⟵ parse raw JSON from the server.
+users.updateEach( user => user.firstName = '' ); // ⟵ bulk update triggering 'changes' once
+```
+
+# Record definition
+
+Record definition must:
+
+- be the class extending the `Record`;
+- be preceded with the `@define` decorator;
+- have `static attributes` definition.
+
+### `decorator` @define
+
+_Must_ be placed before record class definition.
+
+```javascript
+import { define, Record } from 'type-r'
+
+@define class X extends Record {
+    ...    
+}
+```
+
+### `static` attributes = { name : `attrDef`, ... }
+
+Record's attributes definition. Lists attribute names along with their types, default values, and metadata controlling different aspects of attribute behavior.
+
+```javascript
+@define class User extends Record {
+    static attributes = {
+        name    : String.value( 'John Dow' ),
+        email   : '[email protected]', // Same as String.value( '[email protected]' )
+        address : String, // Same as String.value( '' )
+    }
+}
+```
+
+The Record guarantee that _every attribute will retain the value of the declared type_. Whenever an attribute is being assigned with the value which is not compatible with its declared type, the type is being converted with an invocation of the constructor: `new Type( value )` (primitive types are treated specially).
+
+## Attribute definitions
+
+### `attrDef` name : Type
+
+When the function is used as `attrDef`, it's treated as the constructor function. Any constructor function which behaves as _converting constructor_ (like `new Date( msecs )`) may be used as an attribute type.
+
+You can use other record's and collection's constructors as attribute types. They will be treated as an _integral part_ of the record (created, serialized, validated, and disposed together), i.e. as _aggregated members_.
+
+```javascript
+@define class Person extends Record {
+    static attributes = {
+        name : String // String attribute which is "" by default.
+        createdAt : Date // Date attribute
+        ...
+    }
+}
+```
+
+### `attrDef` name : defaultValue
+
+When value of other type than function is used as `attrDef` it's treated as attribute's default value. Attribute's type is being inferred from the value.
+
+Use the general form of attribute definition for attributes of `Function` type: `Function.value( theFunction )`.
+
+```javascript
+@define class GridColumn extends Record {
+    static attributes = {
+        name : '', // String attribute which is '' by default.
+        render : Function.value( x => x ),
+        ...
+    }
+}
+```
+
+### `attrDef` name : Type.value( defaultValue )
+
+The general form of attribute definition is `Type.value( defaultValue )`, where the `Type` is the corresponding constructor function.
+
+```javascript
+@define class Person extends Record {
+    static attributes = {
+        phone : String.value( null ) // String attribute which is null by default.
+        ...
+    }
+}
+```
+
+# Create the record
+
+Record behaves as regular ES6 class with attributes accessible as properties.
+
+### new Record()
+
+Create an instance of the record with default attribute values taken from the attributes definition.
+
+When no default value is explicitly provided for an attribute, it's initialized as `new Type()` (just `Type()` for primitives). When the default value is provided and it's not compatible with the attribute type, it's converted with `new Type( defaultValue )` call.
+
+### new Record({ attrName : value, ... }, options? )
+
+When creating an instance of a record, you can pass in the initial attribute values to override the defaults.
+
+If `{parse: true}` option is used, `attrs` is assumed to be the JSON.
+
+If the value of the particular attribute is not compatible with its type, it's converted to the declared type invoking the constructor `new Type( value )` (just `Type( value )` for primitives).
+
+```javascript
+@define class Book extends Record {
+    static attributes = {
+        title  : '',
+        author : ''
+    }
+}
+
+const book = new Book({
+  title: "One Thousand and One Nights",
+  author: "Scheherazade"
+});
+```
+
+### `abstract` record.initialize( attrs?, options? )
+
+Called at the end of the `Record` constructor when all attributes are assigned and the record's inner state is properly initialized. Takes the same arguments as
+a constructor.
+
+### record.attrName
+
+Record's attributes may be directly accessed as `record.name`.
+
+> Please note, that you *have to declare all attributes* in `static attributes` declaration.
+
+```javascript
+@define class Account extends Record {
+    static attributes = {
+        name : String,
+        balance : Number
+    }
+}
+
+const myAccount = new Account({ name : 'mine' });
+myAccount.balance += 1000000; // That works. Good, eh?
+```

docs/04_Record/03_Updates_and_transactions.md

@@ -0,0 +1,89 @@
+# Update record attributes
+
+### record.attrName = value
+
+Assign the record's attribute. If the value is not compatible with attribute's type from the declaration, it is converted:
+
+- with `Type( value )` call, for primitive types;
+- with `record.attrName.set( value )`, for existing record or collection (updated in place);
+- with `new Type( value )` in all other cases.
+
+Record triggers events on changes:
+- `change:attrName` *( record, value )*.
+- `change` *( record )*.
+
+```javascript
+@define class Book extends Record {
+    static attributes = {
+        title : String,
+        author : String
+        price : Number,
+        publishedAt : Date,
+        available : Boolean
+    }
+}
+
+const myBook = new Book({ title : "State management with Type-R" });
+myBook.author = 'Vlad'; // That works.
+myBook.price = 'Too much'; // Converted with Number( 'Too much' ), resulting in NaN.
+myBook.price = '123'; // = Number( '123' ).
+myBook.publishedAt = new Date(); // Type is compatible, no conversion.
+myBook.publishedAt = '1678-10-15 12:00'; // new Date( '1678-10-15 12:00' )
+myBook.available = some && weird || condition; // Will always be Boolean. Or null.
+```
+
+### record.set( { attrName : value, ... }, options? : `options` )
+
+Bulk assign record's attributes, possibly taking options.
+
+If the value is not compatible with attribute's type from the declaration, it is converted:
+
+- with `Type( value )` call, for primitive types.
+- with `record.attrName.set( value )`, for existing record or collection (updated in place).
+- with `new Type( value )` in all other cases.
+
+Record triggers events after all changes are applied:
+
+1. `change:attrName` *( record, val, options )* for any changed attribute.
+2. `change` *(record, options)*, if there were changed attributes.
+
+### `options` { parse : true }
+
+Assume `record.set` argument is the raw JSON and parse it. Must be used to process the response from the server.
+
+```javascript
+// Another way of doing the bestSeller.clone()
+// Amazingly, this is guaranteed to work by default.
+const book = new Book();
+book.set( bestSeller.toJSON(), { parse : true } );
+```
+
+### record.assignFrom( otherRecord )
+
+Makes an existing `record` to be the full clone of `otherRecord`, recursively assigning all attributes.
+
+```javascript
+// Another way of doing the bestSeller.clone()
+const book = new Book();
+book.assignFrom( bestSeller );
+```
+
+# Transactions
+
+All record updates occurs in the scope of transactions. Transaction is the sequence of changes which results in a single `change` event.
+
+Transaction can be opened either manually or implicitly with calling `set()` or assigning an attribute.
+Any additional changes made to the record in `change:attr` event handler will be executed in the scope of the original transaction, and won't trigger additional `change` events.
+
+### record.transaction( fun )
+
+Execute the all changes made to the record in `fun` as single transaction triggering the single `change` event.
+
+```javascript
+some.record.transaction( record => {
+    record.a = 1; // `change:a` event is triggered.
+    record.b = 2; // `change:b` event is triggered.
+}); // `change` event is triggered.
+```
+
+Manual transactions with attribute assignments are superior to `record.set()` in terms of both performance and flexibility.