vasille 1.2.7 → 2.0.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Vasile Lelițac
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,132 +1,166 @@
-# Vasille.js
+# Vasille
 
-|Intro|
-|:---:|
-|![Vasille.js logo](https://gitlab.com/vasille-js/vasille-js/-/raw/master/img/logo.png)|
-|Vasille.js is **very fast** javascript frontend framework, it is not using virtual DOM, it updates DOM directly using an own reactive mechanism.|
+![Vasille.js logo](https://gitlab.com/vasille-js/vasille-js/-/raw/v2/img/logo.png)
 
-This framework is in active development, if you want to contribute contact
-the maintainer: Lelițac Vasile (lixcode@vivaldi.net).
+`Vasille` core library is frontend solution for `safe`, `fast` & `powerful` applications.
 
-### Table of content
+## Table of content
 [[_TOC_]]
 
 
-## Project roadmap
+<hr>
 
-| Feature                                     | Deadline     | Status     |
-|---------------------------------------------|--------------|------------|
-| Initial Version                             | 01.07.2021   | Ready      |
-| Patch to 1.1                                | 02.12.2021   | Ready      |
-| Describe API                                | 02.14.2021   | Ready      |
-| Describe JS API                             | 02.15.2021   | Ready      |
-| Describe VCC architecture                   | 02.22.2021   | Waiting    |
-| Code and debug VCC                          | 03.xx.2021   |            |
-| First enterprise ready version              | xx.xx.2021   |            |
-| Boost by HTML templates                     | xx.xx.2021   |            |
+## Installation
 
-## API documentation
+```
+npm install vasille --save
+```
+
+### Getting ready be example
+* JavaScript Example
+* TypeScript Example
+* Flow.js Example
+
+### Flow.js typedef
+Add the next line to `[libs]` section in your `.flowconfig` file
+```
+node_modules/vasille/flow-typed
+```
+
+<hr>
+
+## How SAFE is Vasille
+
+The safe of your application is ensured by 
+* `100%` coverage of `vasille` code by unit tests.
+  Each function, each branch are working as designed.
+* `strong typing` makes your javascript/typescript code safe as C++ code.
+All entities of `vasille` core library are strong typed, including:
+  * data fields & properties.
+  * computed properties (function parameters & result).
+  * methods.
+  * events (defined handlers & event emit).
+  * DOM events & DOM operation (attributing, styling, etc.).
+  * slots of component.
+  * references to children.
+* What you write is what you get - there is no hidden operations, you can control everything.
+* No asynchronous code, when the line of code is executed, the DOM and reactive things are already synced.
+
+## How FAST is Vasille
+
+The test project was coded using the next frameworks:
+* Angular /
+  [Try Initial](https://vasille-js.gitlab.io/project-x32/angular/) /
+  [Try Optimized](https://vasille-js.gitlab.io/project-x32-if/angular/).
+* React /
+  [Try Initial](https://vasille-js.gitlab.io/project-x32/react/) /
+  [Try Optimized](https://vasille-js.gitlab.io/project-x32-if/react/).
+* Vue 2 /
+  [Try Initial](https://vasille-js.gitlab.io/project-x32/vue-2/) /
+  [Try Optimized](https://vasille-js.gitlab.io/project-x32-if/vue-2/).
+* Vue 3 /
+  [Try Initial](https://vasille-js.gitlab.io/project-x32/vue-3/) /
+  [Try Optimized](https://vasille-js.gitlab.io/project-x32-if/vue-3/).
+* Svelte /
+  [Try Initial](https://vasille-js.gitlab.io/project-x32/svelte/) /
+  [Try Optimized](https://vasille-js.gitlab.io/project-x32-if/svelte/).
+* Vasille /
+  [Try Initial](https://vasille-js.gitlab.io/project-x32/vasille-js/) /
+  [Try Optimized](https://vasille-js.gitlab.io/project-x32-if/vasille-js/).
+
+The result of test are demonstrated in figures 1 & 2. 
+The test result are measured in FPS (frames per second), which is calculated as `1000 / ft`,
+where `ft` is an average frame time in ms of 20 frames. All values are absolute. Higher is better.
+
+The initial version is updating all the page content in each frame. 
+The page reactivity connections are very complex, and we get poor results in Angular, React, Vue & Svelte.
+
+The optimized version disables the offscreen & non-actual content, which simplifies the
+reactivity complexity in time. Angular & Svelte give result similar to Vasille.
+React & Vue continue to be slow in the beginning of test.
+
+**Conclusion:** The reactivity system of Vasille is very fast
+and its complexity is not slowing down the application.
+
+<hr>
 
+&nbsp;
+
+Figure 1: Initial version
+
+![results 1](https://gitlab.com/vasille-js/vasille-js/-/raw/v2/img/scores-wo.png)
+
+<hr>
+
+&nbsp;
+
+Figure 2: Optimized version
+
+![results 2](https://gitlab.com/vasille-js/vasille-js/-/raw/v2/img/scores-o.png)
+
+<hr>
+
+## How POWERFUL is Vasille
+
+The secret of `Vasille` is a good task decomposition. The core library is composed of
+an effective reactive module and a DOM generation engine based on it.
+
+<hr>
+
+### Reactivity Module
+
+Reactivity module is used to create a model of data. It can contain self-updating values,
+forward-only shared data. Reactivity of objects/fields can be disabled/enabled manually.
+
+![Reactivity Module](https://gitlab.com/vasille-js/vasille-js/-/raw/v2/img/reactive.png)
+
+* `Destroyable` is an entity which has a custom destructor.
+* `IValue<T>` is a common interface for any value container, with next members:
+  * `get $` gets the encapsulated value.
+  * `set $` manually update the encapsulated value, if enabled triggers updating of all linked data.
+  * `disable` disables the reactivity.
+  * `enable` enables the reactivity and triggers updating of all linked data.
+* `Reference<T>` contains a value of type `T`.
+* `Mirror<T>` syncs self value with another `IValue` container, can be used to share a value forward-only.
+* `Pointer<T>` same as `Mirror`, but it can switch between `IValue` target anytime.
+* `Expression<ReturnType, Args...>` is a self-updating value.
+* `Reactive` is a reactive object which can have multiple reactive fields, emit/receive events/signals.
+
+<hr>
+
+### DOM Generation Engine
+
+DOM Generation Engine is used to describe a virtual DOM of reactive fragments, 
+which will be reflected into a browser DOM and keep up to date it.
+
+![DOM Generation Engine](https://gitlab.com/vasille-js/vasille-js/-/raw/v2/img/nodes.png)
+
+* `Fragment` describes a virtual DOM node, which has siblings, children, parent & slots.
+* `TextNode` reflects a `Text` node.
+* `INode` reflects a `Element` node.
+* `Tag` reflect a self created `Element` node.
+* `Extension` reflects an existing `Element` node.
+* `Component` reflects a `Element` node created by a `Tag` child.
+* `AppNode` is root of a `Vasille` application, can be used to create applications in application.
+* `App` is root of a definitive `Vasille` application.
+* `DebugNode` reflects a `Comment` node, useful for debug.
+* `Watch` recompose children nodes on model value change.
+* `RepeatNode` creates multiples children nodes using the same code multiple time.
+* `Repeater` repeat slot content `n` times.
+* `BaseView` represent a view in context of MVC (Model-View-Controller).
+* `ObjectView` repeats slot content for each value of `ObjectModel`.
+* `MapView` repeats slot content for each `MapModel` value.
+* `SetView` repeats slot content for each `SetModel` value.
+* `ArrayView` repeats slot content for each `ArrayModel` value respecting its order.
+* `InterceptorNode` is used to send an event/signal from one child to other 
+without manually creating of interceptors.
+
+## API documentation
 
-Currently, the [API](pages/API.md) is in development, 
-but the [JavaScript API](pages/JavaScriptAPI.md)
-is available.
-
-* [API Documentation](https://gitlab.com/vasille-js/vasille-js/-/blob/master/pages/API.md)
-* [JS API Documentation](https://gitlab.com/vasille-js/vasille-js/-/blob/master/pages/JavaScriptAPI.md)
-
-## Tools in development
-
-* **Vasille.js** is a component based framework without any dependencies
-* **Reactive Reference** is a build in reactivity library of Vasille.js
-* **Vasille Language** is a user-friendy language to describe Vasille.js 
-  components
-* **VCC** (*Vasille Component Compiler*) translate code from Vasille 
-  language to high-effective Vasille.js components performing a 
-  lot of performance improvements.
-  
-## How it works
-
-To test the speed of frameworks (inclusive Vasille JS) I had created a map, 
-which can be zoomed up to 32x, this project was called "Project x32".
-
-On the next image is demonstrated the difference between 1x zoom (on the 
-left side) and x32 zoom (on the right side):
-![x1-x32](https://gitlab.com/vasille-js/vasille-js/-/raw/master/img/x1-x32.png)
-
-There are 100 random squares over each brick, on small zoom the squares 
-are hidden to optimize browser performance, because the page is composed 
-of over than 23 000 nodes. The random squares added one by one to not 
-freeze zoom animation. The zoom animation duration is 300ms, and it 
-must consist of 20 frames on 60Hz screen.
-
-The project x32 was coded using the next frameworks:
-* Angular.
-* React.
-* Vue 2.
-* Vue 3.
-* Svelte.
-* Vasille JS.
-
-### Measuring zoom performance
-
-After zooming in each production build and measuring performance 
-I had got the next results:
-![results 1](https://gitlab.com/vasille-js/vasille-js/-/raw/master/img/scores-wo.png)
-
-The Vue & React builds are the slowest: the average frame time of:
-* React build is 1263.48ms.
-* Vue 3 build is 971.80ms.
-* Vue 2 build is 823.56ms.
-
-There is the same graphic in logarithmic scale:
-![results 1](https://gitlab.com/vasille-js/vasille-js/-/raw/master/img/scores-wo-log.png)
-
-Let's analyze the Angular, Svelte & Vasille JS results:
-* Angular & Svelte has a similar result, the average time of frame 
-  is 53.94ms for Angular & 53.98 for Svelte.
-* The Vasille JS is the unique framework which support the zoom 
-  animation at 60fps without any additional optimization.  
-  Average time of frame is 3.22ms.
-
-#### Try it:
-* [Project x32 powered by Angular](https://vasille-js.gitlab.io/project-x32/angular/)
-* [Project x32 powered by React](https://vasille-js.gitlab.io/project-x32/react/)
-* [Project x32 powered by Vue 2](https://vasille-js.gitlab.io/project-x32/vue-2/)
-* [Project x32 powered by Vue 3](https://vasille-js.gitlab.io/project-x32/vue-3/)
-* [Project x32 powered by Svelte](https://vasille-js.gitlab.io/project-x32/svelte/)
-* [Project x32 powered by Vasille JS](https://vasille-js.gitlab.io/project-x32/vasille-js/)
-
-### Let's optimize Project x32
-
-To optimize the Project x32 realizations, the optimization consist 
-of removing the off-screen components, that change will decrease 
-the number of components. So let's zoom each optimized build 
-from x1 to x32.
-
-Tests results:
-![results 2](https://gitlab.com/vasille-js/vasille-js/-/raw/master/img/scores-o.png)
-
-After X8 the number of onscreen components is very small, the optimization has a good result.
-The Reactive frameworks are the slowest before and after optimization.
-
-There is the same graphic in logarithmic scale:
-![results 2](https://gitlab.com/vasille-js/vasille-js/-/raw/master/img/scores-o-log.png)
-
-After optimization Angular, Svelte & Vasille JS has very good 
-results close to Vasille JS before optimization.
-
-#### Try it:
-* [Optimized Project x32 powered by Angular](https://vasille-js.gitlab.io/project-x32-if/angular/)
-* [Optimized Project x32 powered by React](https://vasille-js.gitlab.io/project-x32-if/react/)
-* [Optimized Project x32 powered by Vue 2](https://vasille-js.gitlab.io/project-x32-if/vue-2/)
-* [Optimized Project x32 powered by Vue 3](https://vasille-js.gitlab.io/project-x32-if/vue-3/)
-* [Optimized Project x32 powered by Svelte](https://vasille-js.gitlab.io/project-x32-if/svelte/)
-* [Optimized Project x32 powered by Vasille JS](https://vasille-js.gitlab.io/project-x32-if/vasille-js/)
-
-## Conclusions
-The main goal of Vasille JS is not to be the fastest JavaScript framework, 
-but to ensure excellent performance without any optimizations.
+There are several API, and most of it are WIP (Work In Progress):
+* [OOP API - Ready](https://gitlab.com/vasille-js/vasille-js/-/blob/v2/pages/OOP-API.md)
+* [Procedural API - WIP](https://gitlab.com/vasille-js/vasille-js/-/blob/v2/pages/Procedural-API.md)
+* [Final API - WIP](https://gitlab.com/vasille-js/vasille-js/-/blob/v2/pages/API.md)
 
 ## Questions