arrmatura 6.3.1 → 6.3.2

package/src/core/{Entitron.ts → Arrmatron.ts}

@@ -1,45 +1,44 @@
-import { areEqual, capitalize, identity } from "ultimus";
-import { stringify } from "../utils/stringify";
-import type { Delta, Fn, Hash, Proc, Uid } from "ultimus/types";
-import type { IEntitron, IManifestNode, IComponent, IPlatform } from "arrmatura/types";
+import { capitalize, identity } from "ultimus";
+import type { Delta, Fn, Hash, LogEntry, Proc, Uid } from "ultimus/types";
 
-type EProcedure = (c: IEntitron) => void;
+import type { IArrmatron, IManifestNode, IComponent, IPlatform } from "../../types";
+import { objectFingerprint } from "../utils/FingerprintMashine";
+import { applyStateChangedToImpl } from "../utils/applyStateChangedToImpl";
+import { stringify } from "../utils/stringify";
 
 /**
- * The Entitron is the essential the framework concept.
- * 
- * It creates a own component instance,
- * manages its state and behavior, 
- * and ties it up with others.
+ * The Arrmatron is the essential concept of the framework.
+ * It creates a component instance, manages its state and keeps in touch with others.
  */
-export class Entitron<T extends IManifestNode = IManifestNode> implements IEntitron {
-  readonly component: IComponent;
-  $children?: Map<Uid, IEntitron>;
-  readonly root: IEntitron;
-  readonly scope: IEntitron;
-  isDone = false;
+export class Arrmatron<T extends IManifestNode = IManifestNode> implements IArrmatron {
+  readonly $component: IComponent;
+  readonly root: IArrmatron;
+  readonly scope: Arrmatron;
 
+  $children?: Map<Uid, Arrmatron>;
+  isDone = false;
   #isInited = false;
-  #state: Hash = {};
+  #fprints: Hash = {};
   #initialState: Hash = {};
-  #listeners?: Set<(c: Entitron) => void>;
-  #defered?: EProcedure[] = [];
+  #listeners?: Set<(c: Arrmatron) => void>;
+  #defered?: Array<(c: IArrmatron) => void> = [];
   #weak?: Map<string, number>;
-  #refs?: Hash<IEntitron>;
+  #refs?: Hash<IArrmatron>;
   #propFnMap?: Map<string, Proc>;
 
-  constructor(readonly platform: IPlatform, protected readonly manifest: T, private _parent?: IEntitron, scope?: IEntitron) {
+  constructor(readonly platform: IPlatform, protected readonly manifest: T, private _parent?: Arrmatron, scope?: Arrmatron) {
     this.scope = scope ?? this;
     this.root = scope?.root ?? this;
     this.#initialState = this.manifest.resolveInitialProps(this);
-    this.component = this.createComponent(this.#initialState);
+    this.$component = this.createComponent(this.#initialState);
 
     if (this.refId) {
+      // this.log('addReference', this.refId)
       this.scope.addReference(this.refId, this);
     }
   }
 
-  get parent(): IEntitron | undefined {
+  get parent(): IArrmatron | undefined {
     return this._parent;
   }
 
@@ -59,64 +58,67 @@ export class Entitron<T extends IManifestNode = IManifestNode> implements IEntit
   // --- State
 
   // updates component state
-  up(Δ?: Delta | Promise<any> | null | void | unknown, force = false): void {
-    if (!Δ || this.isDone) {
+  up(delta?: Delta | Promise<any> | null | void | unknown, force = false): void {
+    if (!delta || this.isDone) {
       return;
     }
 
-    if (Δ instanceof Promise) {
-      this.upAsync(Δ, "*");
+    if (delta instanceof Promise) {
+      const racer = this.raceCondition(`set`);
+      delta.then((val) => racer(() => this.up(val)));
       return;
     }
 
     const changes = new Map<string, unknown>();
-    Object.entries(Δ).forEach(([k, v]) => {
+    Object.entries(delta).forEach(([k, v]) => {
       if (v instanceof Promise) {
-        this.upAsync(v, k);
-      } else if (k && typeof v !== "undefined" && !areEqual(v, this.#state[k])) {
-        this.#state[k] = v;
-        changes.set(k, v);
+        const isSpreading = !k || k.startsWith("...");
+        const racer = this.raceCondition(`set:${k}`);
+        void v.then((val) => racer(() => this.up(isSpreading ? val : { [k]: val })));
+
+      } else if (k && typeof v !== "undefined") {
+        if (k[0] === "$") {
+          if (this.$component[k] !== v) {
+            changes.set(k.slice(1), v);
+          }
+        } else {
+
+          const fprint = objectFingerprint(v);
+          if (!(k in this.#fprints) || fprint !== this.#fprints[k]) {
+            this.#fprints[k] = fprint;
+            changes.set(k, v);
+            // } else {
+            //   if (v && typeof v === "object" && v !== this.get(k)) {
+
+            //     this.log('same skip', k, '\n  ', v, '==', this.get(k), '\n  ', this.#fprints[k], '==', fprint)
+            //   }
+          }
+        }
       }
     });
 
     if (changes.size || force) {
-      this.stateChanged(changes);
+      applyStateChangedToImpl(changes, this.$component);
+      this.touch();
     }
   }
 
-  private upAsync(promise: Promise<any>, key: string): void {
-    const racer = this.raceCondition(`set:${key}`);
-    if (key[0] !== "*") {
-      const akey = key.replace("Promise", "");
-      void promise.then((val) => racer(() => this.up({ [akey]: val })));
-    } else {
-      void promise.then((r: Delta) => racer(() => this.up(r)));
-    }
-  }
-
-  private stateChanged(changes: Map<string, unknown>) {
-    if (this.component.stateChanged) {
-      this.component.stateChanged(changes);
-    } else {
-      changes.forEach((v, k) => {
-        const setter = this.component[`set${capitalize(k)}`];
-        if (typeof setter === "function") {
-          setter.call(this.component, v);
-        } else {
-          this.component[k] = v;
-        }
-      });
-    }
-    this.touch();
-  }
-
   // do recontent and notify all
   touch() {
     this.recontent();
     this.notify();
   }
 
-  // gets component property by key
+  /**
+   * Retrieves the component value associated with the given property ID.
+   * Dot-sepated pathes to properties are supported.
+   * Supported getters like `get<Name>()`.
+   * use '@' prefix to access platform resources.
+   * Functional values are bounded and cached.
+   *
+   * @param {string} propId - The ID of the property. 
+   * @return {unknown} The value associated with the property ID.
+   */
   get(propId: string): unknown {
     const map = this.#propFnMap ?? (this.#propFnMap = new Map());
     if (map.has(propId)) {
@@ -124,15 +126,17 @@ export class Entitron<T extends IManifestNode = IManifestNode> implements IEntit
     }
 
     let fn: Fn | null = null;
-    const impl = this.component;
+    const impl = this.$component;
     const instant = impl[propId];
+
     if (instant && typeof instant === "function") {
       const bound = instant.bind(impl);
       fn = () => bound;
+    } else if (impl.__getProperty) {
+      fn = () => (impl.__getProperty as (p: string) => unknown)(propId);
     } else {
       const [pk, ...path] = propId.split(".");
-      if (pk[0] === "@") {
-        path.unshift(pk.slice(1));
+      if (pk === "R") {
         const val = this.platform.getResource(path) ?? null;
         fn = () => val;
       } else {
@@ -159,7 +163,7 @@ export class Entitron<T extends IManifestNode = IManifestNode> implements IEntit
   }
 
   // add listener to componet state changes
-  subscribe(handler: (src: Entitron) => any): Proc {
+  subscribe(handler: (src: Arrmatron) => any): Proc {
     const listeners = this.#listeners ?? (this.#listeners = new Set());
     listeners.add(handler);
     return () => {
@@ -171,62 +175,60 @@ export class Entitron<T extends IManifestNode = IManifestNode> implements IEntit
 
   // emits action event to this component
   emit(key: string, data: Delta): void {
+    if (this.isDone) return;
+
     try {
-      // when key.endsWith("...") it will produce empty target, so don't need to hande it peculiarly 
-      let [refId, target] = key.split(".");
-      if (!target) {
-        target = refId;
-        refId = 'this'
-      }
+      if (key.endsWith(")")) {
+        const [refId, target] = key.split("(")[0].split(".");
+        const ref = this.getByRef(refId);
+        if (!ref) {
+          throw new Error(`No such reference: ${refId}`);
+        }
 
-      const ref = this.getByRef(refId);
-      if (!ref) {
-        throw new Error(`No such reference: ${refId}`);
-      }
+        const impl = ref.$component;
 
-      if (!target) { // spread '...'
-        ref.up(data);
-        return;
-      }
+        const method = impl[target];
+        if (!(typeof method === "function")) {
+          throw new Error(`Not a method: ${refId}.${target}()`);
+        }
 
-      if (target[0] === "@") {
-        ref.up({ [target.slice(1)]: data });
-        return;
-      }
+        const result = method.call(impl, data);
 
-      const impl = ref.component;
-      const method = impl[target] ?? impl[`on${capitalize(target)}`];
+        // this.log(`-> ${refId}.${target}(data)`, result, data, impl);
 
-      // deprecated. Use @-prefix instead.
-      if (!method) {
-        const propKey = target[0] === "@" ? target.slice(1) : target;
-        ref.up({ [propKey]: data });
-        return;
-      }
+        ref.up(result);
+      } else {
+        let [refId, target] = key.split(".");
+        if (!target) {
+          target = refId;
+          refId = "this";
+        }
 
-      if (!(typeof method === "function")) {
-        throw new Error(`Not a method: ${refId}.${target}`);
-      }
+        const ref = this.getByRef(refId);
+        if (!ref) {
+          throw new Error(`No such reference: ${refId}`);
+        }
 
-      const result = method.call(impl, data, impl, ref);
+        ref.up(target === "*" ? data : { [target]: data });
 
-      this.log(`-> ${refId}.${target}`, result, data, impl);
+        // this.log(`-> ${refId}.${target} = `, data);
+      }
 
-      ref.up(result);
     } catch (ex) {
       this.logError(`emit ${key}:`, ex);
     }
     return;
   }
+  // --- life-cycle.
 
-  // Done life-cycle hook.
+  // Done  hook.
   done() {
     if (this.isDone) {
       return;
     }
     this.isDone = true;
 
-    this.component.done?.(this);
+    this.$component.done?.(this);
 
     this.children?.forEach((c) => c.done());
 
@@ -237,22 +239,14 @@ export class Entitron<T extends IManifestNode = IManifestNode> implements IEntit
     this._parent = undefined;
   }
 
-  // map of children contexts
-  get children(): Map<Uid, IEntitron> | undefined {
-    return this.$children;
-  }
-
-  // map of chidren of its node
-  get contentManifests() {
-    return this.manifest.getSubNodes(this.platform);
-  }
-
-  // actual scope for re-content
-  get recontentScope() {
-    return this.scope;
+  // register callback to be called on done
+  defer(fn: (c: IArrmatron) => void) {
+    if (fn && typeof fn === "function") {
+      (this.#defered ?? (this.#defered = [])).push(fn);
+    }
   }
 
-  settleAsChild() {
+  private settleAsChild() {
     if (!this.#isInited) {
       this.#isInited = true;
 
@@ -260,12 +254,29 @@ export class Entitron<T extends IManifestNode = IManifestNode> implements IEntit
 
       this.up(this.#initialState, true);
 
-      this.up(this.component.init?.(this));
+      this.up(this.$component.init?.(this));
     } else {
       void this.up(this.manifest.resolveProps(this), true);
     }
   }
 
+  // --- Content.
+
+  // map of children contexts
+  get children(): Map<Uid, IArrmatron> | undefined {
+    return this.$children;
+  }
+
+  // map of chidren of its node
+  get contentManifests() {
+    return this.manifest.getSubNodes(this.platform);
+  }
+
+  // actual scope for re-content
+  get recontentScope() {
+    return this.scope;
+  }
+
   // perform children instantiation and updates
   private recontent() {
     const nodes = this.contentManifests;
@@ -278,10 +289,10 @@ export class Entitron<T extends IManifestNode = IManifestNode> implements IEntit
       }
     });
 
-    const children = new Map<Uid, IEntitron>();
+    const children = new Map<Uid, Arrmatron>();
 
     nodes?.forEach((node: IManifestNode, uid: Uid) => {
-      const e = this.children?.get(uid) ?? node.createEntitron(this.platform, this, this.recontentScope);
+      const e = this.$children?.get(uid) ?? node.createArrmatron(this.platform, this, this.recontentScope);
       children.set(e.uid, e);
     });
 
@@ -299,7 +310,7 @@ export class Entitron<T extends IManifestNode = IManifestNode> implements IEntit
   }
 
   // gets any context instance in current or upper scope by key
-  getByRef(refId: string): IEntitron | undefined {
+  getByRef(refId: string): IArrmatron | undefined {
     if (!refId) return undefined;
 
     if (refId === "this") {
@@ -309,15 +320,14 @@ export class Entitron<T extends IManifestNode = IManifestNode> implements IEntit
     if (local) {
       return local;
     }
-    const ref = this === this.scope ? null : this.scope.getByRef(refId);
-    return ref as Entitron;
+    return this.parent?.getByRef(refId);
   }
 
-  addReference(refId: string, c: IEntitron) {
+  private addReference(refId: string, c: IArrmatron) {
     (this.#refs ?? (this.#refs = {}))[refId] = c;
   }
 
-  // --- Routines -------------------------
+  // --- Connectors -------------------------
 
   private initConnectors() {
     if (this.manifest.connectors) {
@@ -325,7 +335,7 @@ export class Entitron<T extends IManifestNode = IManifestNode> implements IEntit
         const [srcIds, targetPropName] = key.split("|");
         const [refId, sourcePropName] = srcIds.split(".");
 
-        const ref = this.scope.getByRef(refId) as Entitron;
+        const ref = this.parent?.getByRef(refId) as Arrmatron;
         if (!ref) {
           this.logError(`Connect: No such ref: ${refId}`);
           continue;
@@ -336,26 +346,35 @@ export class Entitron<T extends IManifestNode = IManifestNode> implements IEntit
           continue;
         }
 
-        const propName = sourcePropName[0] === '@' ? sourcePropName.slice(1) : sourcePropName;
         const applicator = targetPropName ? (rr: any) => ({ [targetPropName]: rr }) : identity;
 
-        this.defer(
-          ref.subscribe((source: Entitron) => {
+        this.defer((() => {
+          let popre;
+          return ref.subscribe(async (source: Arrmatron) => {
             try {
-              const r = applicator(pipes(this, source.get(propName)));
+              const val = await source.get(sourcePropName);
+              const fingerprint = objectFingerprint(val);
+
+              if (popre !== undefined && popre === fingerprint) return;
+
+              popre = fingerprint;
+              const r = applicator(pipes(this, val));
               this.up(r as Delta);
             } catch (ex) {
               source.logError("Notify ", ex);
             }
           })
+        })()
         );
 
         // hot subscription
-        Object.assign(this.#initialState, applicator(pipes(ref, ref.get(propName))));
+        Object.assign(this.#initialState, applicator(pipes(ref, ref.get(sourcePropName))));
       }
     }
   }
 
+  // --- Routines -------------------------
+
   raceCondition(key: string) {
     const COUNTERS = this.#weak ?? (this.#weak = new Map<string, number>());
     let counter = 1 + (COUNTERS.get(key) ?? 0);
@@ -368,13 +387,6 @@ export class Entitron<T extends IManifestNode = IManifestNode> implements IEntit
     };
   }
 
-  // register callback to be called on done
-  defer(fn: EProcedure) {
-    if (fn && typeof fn === "function") {
-      (this.#defered ?? (this.#defered = [])).push(fn);
-    }
-  }
-
   log(val: any, ...args: unknown[]) {
     this.platform.log({
       level: "log",
@@ -395,9 +407,8 @@ export class Entitron<T extends IManifestNode = IManifestNode> implements IEntit
     });
   }
 
-  // access to resource by key
-  res(key: string | string[]) {
-    return this.platform.getResource(key);
+  toast = (t: LogEntry) => {
+    this.platform.toast(t, this);
   }
 
   toString(): string {

package/src/core/Component.ts

@@ -1,5 +1,6 @@
-import type { Data, Delta, Hash, LogEntry } from "ultimus/types";
-import type { IComponent, IEntitron } from "../../types";
+import type { Delta, Hash, LogEntry } from "ultimus/types";
+
+import type { IComponent, IArrmatron } from "../../types";
 
 /**
  * Base Ancestor for custom components.
@@ -7,61 +8,83 @@ import type { IComponent, IEntitron } from "../../types";
 export abstract class Component implements IComponent {
   [key: string]: unknown;
 
-  constructor(_: Hash, readonly ctx: IEntitron) {
+  constructor(_: Hash, private readonly $ctx: IArrmatron) {
     //no-op
   }
 
   get platform() {
-    return this.ctx.platform;
+    return this.$ctx.platform;
   }
 
   get isDone() {
-    return this.ctx.isDone;
+    return this.$ctx.isDone;
   }
 
   // hook on done
-  done(_: IEntitron): void {
+  done(_: IArrmatron): void {
     //no-op
   }
 
   // hook on init
   // returned value will be used to update state
-  init(_: IEntitron): Delta | null | undefined | unknown {
+  init(_: IArrmatron): Delta | null | undefined | unknown {
     return undefined;
   }
 
-  // update its state
+  // get from ctx state
+  get(key: string) {
+    return this.$ctx.get(key);
+  }
+
+  // update ctx state
   up(d: Delta) {
-    return this.ctx.up(d);
+    return this.$ctx.up(d);
   }
+
   touch() {
-    return this.ctx.touch();
+    return this.$ctx.touch();
   }
+
   // emit action event to another component by key
   emit(key: string, data: Delta) {
-    return this.ctx.emit(key, data);
+    return this.$ctx.emit(key, data);
   }
 
-  // access to resource entity by key
-  res(key: string): Data | Data[] {
-    return this.ctx.res(key);
+  // register callback to be called on done
+  defer(fn: () => void) {
+    this.$ctx.defer(fn);
   }
 
   // register callback to be called on done
-  defer(fn: () => void) {
-    this.ctx.defer(fn);
+  defineCalculatedProperty(key, fn: (...args: any[]) => any, deps?: string[]) {
+    let depKey = "";
+    let depValue = undefined;
+    Object.defineProperty(this, key, {
+      get() {
+        const args: any[] = deps?.length ? deps.map((k) => this.$ctx.get(k)) : [];
+        const newKey = args.join(':');
+        if (depKey !== newKey) {
+          depKey = newKey;
+          depValue = fn.apply(this, args);
+        }
+        return depValue;
+      },
+    });
+  }
+
+  toast(entry: LogEntry) {
+    this.$ctx.toast(entry);
   }
 
   log(val: unknown, ...args: unknown[]) {
-    this.ctx.log(val, ...args);
+    this.$ctx.log(val, ...args);
   }
 
   logError(val: unknown, ...args: unknown[]) {
-    this.ctx.logError(val, ...args);
+    this.$ctx.logError(val, ...args);
   }
 
-  toast(message: string | Partial<LogEntry> = "ok") {
-    // may  overriden from props
-    void this.emit("toasters.send", typeof message === "string" ? { message } : message);
+  toString() {
+    return this.$ctx.toString();
   }
 }