vasille 4.3.1 → 5.0.1

package/README.md

@@ -1,19 +1,32 @@
-# Vasille
+# Steel Frame
 
-![Vasille.js logo](https://raw.githubusercontent.com/vasille-js/vasille-js/refs/heads/v4/doc/img/logo.png)
+![Vasille.js logo](https://raw.githubusercontent.com/vasille-js/vasille-js/refs/heads/v5/doc/img/logo.png)
 
-`Vasille Web` is a front-end framework, which is developed to provide bulletproof frontends.
+`SteelFrameKit` is a front-end development kit, which is developed to provide fault tolerant web applications.
 
-[![npm](https://img.shields.io/npm/v/vasille?style=flat-square)](https://www.npmjs.com/package/vasille)
+[![npm](https://img.shields.io/npm/v/steel-frame?style=flat-square)](https://www.npmjs.com/package/steel-frame)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/vasille-js/steel-frame)
+[![Coverage Status](https://coveralls.io/repos/github/vasille-js/steel-frame/badge.svg?branch=v5)](https://coveralls.io/github/vasille-js/steel-frame?branch=v5)
 
 ## Table of content
 
-* [Installation](#installation)
-* [How to use Vasille](#how-to-use-vasille)
-* [How SAFE is Vasille](#how-safe-is-vasille)
-* [How INTUITIVE is Vasille](#how-intuitive-is-vasille)
-* [How POWERFUL is Vasille](#how-powerful-is-vasille)
-* [Road Map](#road-map)
+- [Steel Frame](#steel-frame)
+  - [Table of content](#table-of-content)
+  - [Installation](#installation)
+  - [How to use SteelFramekit](#how-to-use-steelframekit)
+    - [Full documentation:](#full-documentation)
+    - [Examples](#examples)
+  - [How SAFE is SteelFrameKit](#how-safe-is-steelframekit)
+  - [How INTUITIVE is SteelFrameKit](#how-intuitive-is-steelframekit)
+  - [How POWERFUL is SteelFrameKit](#how-powerful-is-steelframekit)
+  - [Road map](#road-map)
+  - [Change log](#change-log)
+    - [5.0](#50)
+    - [4.0 - 4.3](#40---43)
+    - [3.0 - 3.2](#30---32)
+    - [2.0 - 2.3](#20---23)
+    - [1.0 - 1.2](#10---12)
+  - [Questions](#questions)
 
 
 <hr>
@@ -21,21 +34,22 @@
 ## Installation
 
 ```
-npm install vasille-web --save
+npm install steel-frame --save
 ```
 
-## How to use Vasille
+## How to use SteelFramekit
 
 Create an app from a template
 
 ```bash
-$ npm create vasille
+$ npm create steel-frame
 ```
 
 ### Full documentation:
-* [Learn `Vasille` in 5 minutes](https://github.com/vasille-js/vasille-js/blob/v4/doc/V4-API.md)
-* [Vasille Router Documentation](https://github.com/vasille-js/vasille-js/blob/v4/doc/Router-API.md)
-* [Vasille Compostion function](https://github.com/vasille-js/vasille-js/blob/v4/doc/Compositions.md)
+* [Learn `SteelFrameKit` in 5 minutes](https://github.com/vasille-js/vasille-js/blob/v5/doc/V4-API.md)
+* [Router Documentation](https://github.com/vasille-js/vasille-js/blob/v5/doc/Router-API.md)
+* [Compostion functions](https://github.com/vasille-js/vasille-js/blob/v5/doc/Compositions.md)
+* [Dependency injection](https://github.com/vasille-js/vasille-js/blob/v5/doc/Context.md)
 
 ### Examples
 * [TypeScript Example](https://github.com/vasille-js/example-typescript)
@@ -43,14 +57,14 @@ $ npm create vasille
 
 <hr>
 
-## How SAFE is Vasille
+## How SAFE is SteelFrameKit
 
 The safe of your application is ensured by
 * `100%` coverage of code by unit tests.
   Each function, each branch is working as designed.
 * OOP, DRY, KISS and SOLID principles are applied.
 * `strong typing` makes your javascript/typescript code safe as C++ code.
-All entities of `vasille` core library are strongly typed, including:
+All entities of `SteelFrameKit` core library are strongly typed, including:
   * data fields & properties.
   * computed properties (function parameters and result).
   * methods.
@@ -60,11 +74,11 @@ All entities of `vasille` core library are strongly typed, including:
   * references to children.
 * No asynchronous code, when the line of code is executed, the DOM and reactive things are already synced.
 
-## How INTUITIVE is Vasille
+## How INTUITIVE is SteelFrameKit
 
 There is the "Hello World":
 ```typescript jsx
-import { compose, mount } from "vasille-dx";
+import { compose, mount } from "steel-frame";
 
 const App = compose(() => {
   <p>Hello world</p>;
@@ -73,56 +87,76 @@ const App = compose(() => {
 mount(document.body, App, {});
 ```
 
-## How POWERFUL is Vasille
+## How POWERFUL is SteelFrameKit
 
 All of these are supported:
 * Components.
 * Reactive values (observables).
 * Inline computed values.
 * Multiline computed values.
-* HTML & SVG tags.
+* HTML tags.
 * Component custom slots.
 * 2-way data binding in components.
 * Logic block (if, else).
 * Loops (array, map, set).
+* Dependency injection.
 
 <hr>
 
 ## Road map
 
-* [x] Update the `Vasille Core` library to version 3.0.
 * [x] `100%` Test Coverage for core Library v3.
-* [x] Develop the `Vasille JSX` library.
+* [x] Develop the `JSX` library.
 * [x] `100%` Test Coverage for the JSX library.
-* [x] Develop the `Vasille Babel Plugin`.
+* [x] Develop the `Babel Plugin`.
 * [x] `100%` Test Coverage fot babel plugin.
 * [x] Add CSS support (define styles in components).
 * [x] Add router.
 * [x] Add SSG (static site generation).
+* [ ] Develop tools extension for debugging (WIP).
 * [ ] Add SSR (server side rendering).
-* [ ] Develop tools extension for debugging.
 
 ## Change log
 
-### 4.2.0
+We respect semantic versioning:
+- Major version is increased when we make incompatible API changes.
+- Minor version is increased when we add functionality.
+- Patch version is increased when we fix bugs.
 
-Add support for inlined conditions in JSX, binary `&&` and ternary `?:` operator.
+### 5.0
 
-### 4.1.0
+- Add support for context and dependencies injection.
+- New developement direction: `fault tolerant`.
+- Renamed to `steel-frame`. **[API change]**
+- Removed `forward` and `backward` functions. **[API change]**
+- Removed `Debug` component. **[API change]**
 
-Added SSG (static site generation) as build option `vasille-web build static`.
+### 4.0 - 4.3
 
-### 4.0.0
+- Initial version of the framework with file based routing and building scripts (`web dev` and `web build spa`).
+- Reactive values naming switched to `$` prefix. **[API change]**
+- `4.1` Added SSG (static site generation) as build option `web build static`.
+- `4.2` Add support for inlined conditions in JSX, binary `&&` and ternary `?:` operator.
+- `4.3` Add new function `safe` which make functions safe, errors are reported automatically.
 
-Initial version of the framework with file based routing and building scripts (`vasille-web dev` and `vasille-web build spa`).
+### 3.0 - 3.2
+
+- Switch to a babel plugin to compile components code. **[API change]**
+- 100% of code has been covered with unit tests.
+- New developement direction: `keep it simple`.
+
+### 2.0 - 2.3
+
+- Introduces components compilation via a typescript plugin. **[API change]**
+- New developement direction: `write less, do more`.
+
+### 1.0 - 1.2
+
+- Initial version of core library.
+- Developemnt direction: `performance-first`.
 
 ## Questions
 
 If you have questions, feel free to contact the maintainer of the project:
 
 * [Author's Email](mailto:vas.lixcode@gmail.com)
-* [Author's Telegram](https://t.me/lixcode)
-
-<hr>
-
-**Made in Moldova** 🇲🇩

package/lib/dev/components.js

@@ -0,0 +1,82 @@
+import { App, Portal } from "../node/app.js";
+import { SwitchedNode } from "../node/node.js";
+import { Watch } from "../node/watch.js";
+import { provideId, toDevIdOrValue, toDevObject, toDevValue, } from "./inspectable.js";
+import { DevFragment } from "./node.js";
+export class DevWatch extends Watch {
+    constructor(input, runner, usage) {
+        super(input, runner);
+        const id = provideId();
+        runner.inspector.createComponent({
+            id: id,
+            usage: usage,
+            name: "Watch",
+            props: toDevObject(input),
+            time: Date.now(),
+        });
+        this.runOnDestroy(() => {
+            runner.inspector.destroy({ id, time: Date.now() });
+        });
+    }
+}
+export class DevApp extends App {
+    constructor(node, runner) {
+        super(node, runner);
+        const id = provideId();
+        runner.inspector.createComponent({
+            id: id,
+            name: "App",
+            props: {},
+            time: Date.now(),
+        });
+        this.runOnDestroy(() => {
+            runner.inspector.destroy({ id, time: Date.now() });
+        });
+    }
+}
+export class DevPortal extends Portal {
+    id;
+    constructor(input, runner, declaration, usage, name) {
+        super(input, runner);
+        const id = (this.id = provideId());
+        runner.inspector.createComponent({
+            id: id,
+            name: name ?? "Portal",
+            props: {},
+            declaration: declaration,
+            usage: usage,
+            time: Date.now(),
+        });
+        this.runOnDestroy(() => {
+            runner.inspector.destroy({ id, time: Date.now() });
+        });
+    }
+}
+export class DevSwitchedNode extends SwitchedNode {
+    id;
+    constructor(usage, runner, cases, _default) {
+        super(runner, cases, _default);
+        const id = provideId();
+        const conditions = {};
+        cases.forEach((_case, index) => {
+            conditions[index] = _case.slot === _default ? toDevValue(true) : toDevIdOrValue(_case.$case);
+        });
+        this.id = id;
+        runner.inspector.createComponent({
+            id: id,
+            name: "Switch",
+            props: conditions,
+            usage: usage,
+            time: Date.now(),
+        });
+    }
+    destroy() {
+        this.runner.inspector.destroy({ id: this.id, time: Date.now() });
+        super.destroy();
+    }
+    newChild(index) {
+        const frag = new DevFragment(this.runner, null, null, "Case", { index });
+        this.runner.inspector.setElementParent({ parent: this.id, child: frag.id });
+        return frag;
+    }
+}

package/lib/dev/core.js

@@ -0,0 +1,15 @@
+import { Reactive } from "../core/core.js";
+import { provideId } from "./inspectable.js";
+export class DevReactive extends Reactive {
+    id;
+    runner;
+    constructor(runner) {
+        super();
+        this.id = provideId();
+        this.runner = runner;
+    }
+    destroy() {
+        this.runner.inspector.destroy({ id: this.id, time: Date.now() });
+        super.destroy();
+    }
+}

package/lib/dev/index.js

@@ -0,0 +1,8 @@
+export { DevReactive } from "./core.js";
+export { DevApp, DevPortal, DevSwitchedNode, DevWatch } from "./components.js";
+export { executionPosition, provideId, runFn, wrapFn, registerReference, toDevId, toDevIdOrValue, toDevObject, toDevValue, } from "./inspectable.js";
+export { DevArrayModel, DevMapModel, DevSetModel } from "./models.js";
+export { DevFragment, ModelId, shareStateById } from "./node.js";
+export { DevRunner, PositionedText, positionedText, remapObject, DevTextNode, DevTag, } from "./runner.js";
+export { BaseDevReference, DevExpression, DevIValue, DevReference, ExpressionDevReference, } from "./state.js";
+export { DevArrayView, DevMapView, DevSetView } from "./views.js";

package/lib/dev/inspectable.js

@@ -0,0 +1,113 @@
+import { DevExpression, DevReference } from "./state.js";
+let positionId = 1;
+function getErrorStack(error) {
+    return (error.stack
+        ?.split("\n")
+        .slice(1)
+        .map(line => line.trim()) ?? []);
+}
+export function executionPosition(inspector, pathLineAndChar, error) {
+    const id = positionId++;
+    inspector.registerExecutionPosition({
+        id: id,
+        position: pathLineAndChar,
+        stack: getErrorStack(error),
+    });
+    return id;
+}
+let id = 0;
+export function provideId() {
+    return id++;
+}
+const primitiveTypes = ["number", "string", "boolean"];
+export function registerReference(value, declaration, inspector) {
+    inspector.newReference({
+        id: value.id,
+        value: toDevValue(value.V),
+        declaration: declaration,
+        time: Date.now(),
+    });
+    return value;
+}
+let executionId = 0;
+export function wrapFn(fn, declaration, inspector) {
+    return (...args) => {
+        return runFn(fn, args, declaration, inspector);
+    };
+}
+export function runFn(fn, args, declaration, inspector) {
+    const id = ++executionId;
+    inspector.functionCall({
+        id: id,
+        position: declaration,
+        args: args.map(toDevValue),
+        time: Date.now(),
+    });
+    try {
+        let result = fn(...args);
+        if (result instanceof Promise) {
+            return new Promise((resolve, reject) => {
+                result.then(result => {
+                    inspector.functionReturn({
+                        id: id,
+                        result: toDevValue(result),
+                        async: true,
+                        time: Date.now(),
+                    });
+                    resolve(result);
+                });
+                result.catch(e => {
+                    inspector.functionThrows({
+                        targetId: id,
+                        error: e instanceof Error ? (e.stack ?? e.message) : `${e}`,
+                        async: false,
+                        time: Date.now(),
+                    });
+                    reject(e);
+                });
+            });
+        }
+        else {
+            inspector.functionReturn({
+                id: id,
+                result: toDevValue(result),
+                async: false,
+                time: Date.now(),
+            });
+            return result;
+        }
+    }
+    catch (e) {
+        inspector.functionThrows({
+            targetId: id,
+            error: e instanceof Error ? (e.stack ?? e.message) : `${e}`,
+            async: false,
+            time: Date.now(),
+        });
+        throw e;
+    }
+}
+export function toDevValue(value) {
+    const type = typeof value;
+    return {
+        type: type,
+        value: primitiveTypes.includes(type) || value === null ? JSON.stringify(value) : undefined,
+    };
+}
+export function toDevId(value) {
+    if (value instanceof DevReference || value instanceof DevExpression) {
+        return value.id;
+    }
+    return undefined;
+}
+export function toDevIdOrValue(value) {
+    return toDevId(value) ?? toDevValue(value);
+}
+export function toDevObject(value) {
+    return Object.entries(value).reduce((obj, [prop, value]) => {
+        return {
+            ...obj,
+            [prop]: toDevIdOrValue(value),
+        };
+    }, {});
+}

package/lib/dev/models.js

@@ -0,0 +1,147 @@
+import { ArrayModel } from "../models/array-model.js";
+import { MapModel } from "../models/map-model.js";
+import { SetModel } from "../models/set-model.js";
+import { provideId, toDevValue } from "./inspectable.js";
+export class DevArrayModel extends ArrayModel {
+    id;
+    inspector;
+    constructor(inspector, usage, data, ctx) {
+        super(data, ctx);
+        this.id = provideId();
+        this.inspector = inspector;
+        if (inspector) {
+            const values = [];
+            for (let i = 0; i < this.length; i++) {
+                values.push([toDevValue(i), toDevValue(this[i])]);
+            }
+            inspector.createModel({
+                id: this.id,
+                type: "array",
+                values: values,
+                usage: usage,
+                time: Date.now(),
+            });
+        }
+    }
+    destroy() {
+        this.inspector?.destroy({ id: this.id, time: Date.now() });
+        super.destroy();
+    }
+    fill(value, start, end) {
+        this.shareChange("fill", [value, start, end], undefined);
+        return super.fill(value, start, end);
+    }
+    pop() {
+        const result = super.pop();
+        this.shareChange("pop", [], result);
+        return result;
+    }
+    push(...items) {
+        const result = super.push(...items);
+        this.shareChange("push", items, result);
+        return result;
+    }
+    shift() {
+        const result = super.shift();
+        this.shareChange("shift", [], result);
+        return result;
+    }
+    splice(start, deleteCount, ...items) {
+        this.shareChange("splice", [start, deleteCount, ...items], undefined);
+        return super.splice(start, deleteCount, ...items);
+    }
+    unshift(...items) {
+        const result = super.unshift(...items);
+        this.shareChange("unshift", items, result);
+        return result;
+    }
+    shareChange(method, args, result) {
+        this.inspector?.updateModel({
+            id: this.id,
+            method: method,
+            args: args.map(toDevValue),
+            return: toDevValue(result),
+        });
+    }
+}
+export class DevSetModel extends SetModel {
+    id;
+    inspector;
+    constructor(inspector, usage, set, ctx) {
+        super(set, ctx);
+        this.id = provideId();
+        this.inspector = inspector;
+        inspector?.createModel({
+            id: this.id,
+            type: "set",
+            values: [...this].map(item => [toDevValue(0), toDevValue(item)]),
+            usage: usage,
+            time: Date.now(),
+        });
+    }
+    destroy() {
+        this.inspector?.destroy({ id: this.id, time: Date.now() });
+        super.destroy();
+    }
+    add(value) {
+        this.shareChange("add", [value], undefined);
+        return super.add(value);
+    }
+    clear() {
+        this.shareChange("clear", [], undefined);
+        return super.clear();
+    }
+    delete(value) {
+        const result = super.delete(value);
+        this.shareChange("delete", [value], result);
+        return result;
+    }
+    shareChange(method, args, result) {
+        this.inspector?.updateModel({
+            id: this.id,
+            method: method,
+            args: args.map(toDevValue),
+            return: toDevValue(result),
+        });
+    }
+}
+export class DevMapModel extends MapModel {
+    id;
+    inspector;
+    constructor(inspector, usage, map, ctx) {
+        super(map, ctx);
+        this.id = provideId();
+        this.inspector = inspector;
+        inspector?.createModel({
+            id: this.id,
+            type: "map",
+            values: [...this.entries()].map(([key, value]) => [toDevValue(key), toDevValue(value)]),
+            usage: usage,
+            time: Date.now(),
+        });
+    }
+    destroy() {
+        this.inspector?.destroy({ id: this.id, time: Date.now() });
+    }
+    clear() {
+        this.shareChange("clear", [], undefined);
+        super.clear();
+    }
+    delete(key) {
+        const result = super.delete(key);
+        this.shareChange("delete", [key], result);
+        return result;
+    }
+    set(key, value) {
+        this.shareChange("set", [key, value], undefined);
+        return super.set(key, value);
+    }
+    shareChange(method, args, result) {
+        this.inspector?.updateModel({
+            id: this.id,
+            method: method,
+            args: args.map(toDevValue),
+            return: toDevValue(result),
+        });
+    }
+}

package/lib/dev/node.js

@@ -0,0 +1,59 @@
+import { Fragment } from "../node/node.js";
+import { provideId, toDevObject, } from "./inspectable.js";
+import { DevArrayModel, DevMapModel, DevSetModel } from "./models.js";
+import { DevExpression, DevReference } from "./state.js";
+export const ModelId = Symbol("model-id");
+export function shareStateById(id, runner, name, value) {
+    const inspector = runner.inspector;
+    if (value instanceof DevReference ||
+        value instanceof DevExpression ||
+        value instanceof DevArrayModel ||
+        value instanceof DevSetModel ||
+        value instanceof DevMapModel) {
+        inspector.addContextState({
+            id: id ?? 0,
+            name: name,
+            stateId: value.id,
+        });
+    }
+    else if (value && typeof value == "object" && ModelId in value) {
+        inspector.addContextState({
+            id: id ?? 0,
+            name: name,
+            stateId: value[ModelId],
+        });
+    }
+    return value;
+}
+export class DevFragment extends Fragment {
+    id;
+    declaration;
+    inspector;
+    constructor(runner, declaration, usage, name, props) {
+        super(runner);
+        this.id = provideId();
+        this.declaration = declaration;
+        this.inspector = runner.inspector;
+        runner.inspector.createComponent({
+            id: this.id,
+            declaration: declaration,
+            usage: usage,
+            name: name,
+            props: toDevObject(props),
+            time: Date.now(),
+        });
+    }
+    destroy() {
+        this.inspector.destroy({ id: this.id, time: Date.now() });
+        super.destroy();
+    }
+    pushNode(node) {
+        if ("id" in node && typeof node.id == "number") {
+            this.inspector.setElementParent({
+                parent: this.id,
+                child: node.id,
+            });
+        }
+        super.pushNode(node);
+    }
+}