arrmatura 6.2.1 → 6.3.2

package/src/core/Arrmatron.ts

@@ -0,0 +1,417 @@
+import { capitalize, identity } from "ultimus";
+import type { Delta, Fn, Hash, LogEntry, Proc, Uid } from "ultimus/types";
+
+import type { IArrmatron, IManifestNode, IComponent, IPlatform } from "../../types";
+import { objectFingerprint } from "../utils/FingerprintMashine";
+import { applyStateChangedToImpl } from "../utils/applyStateChangedToImpl";
+import { stringify } from "../utils/stringify";
+
+/**
+ * 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 Arrmatron<T extends IManifestNode = IManifestNode> implements IArrmatron {
+  readonly $component: IComponent;
+  readonly root: IArrmatron;
+  readonly scope: Arrmatron;
+
+  $children?: Map<Uid, Arrmatron>;
+  isDone = false;
+  #isInited = false;
+  #fprints: Hash = {};
+  #initialState: Hash = {};
+  #listeners?: Set<(c: Arrmatron) => void>;
+  #defered?: Array<(c: IArrmatron) => void> = [];
+  #weak?: Map<string, number>;
+  #refs?: Hash<IArrmatron>;
+  #propFnMap?: Map<string, Proc>;
+
+  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);
+
+    if (this.refId) {
+      // this.log('addReference', this.refId)
+      this.scope.addReference(this.refId, this);
+    }
+  }
+
+  get parent(): IArrmatron | undefined {
+    return this._parent;
+  }
+
+  get uid(): string {
+    return this.manifest.uid;
+  }
+
+  get displayName(): string {
+    return "🔹";
+  }
+
+  createComponent(initials: Hash): IComponent {
+    // by default, a component is just a plain object.
+    return { ...initials };
+  }
+
+  // --- State
+
+  // updates component state
+  up(delta?: Delta | Promise<any> | null | void | unknown, force = false): void {
+    if (!delta || this.isDone) {
+      return;
+    }
+
+    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(delta).forEach(([k, v]) => {
+      if (v instanceof Promise) {
+        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) {
+      applyStateChangedToImpl(changes, this.$component);
+      this.touch();
+    }
+  }
+
+  // do recontent and notify all
+  touch() {
+    this.recontent();
+    this.notify();
+  }
+
+  /**
+   * 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)) {
+      return map.get(propId)();
+    }
+
+    let fn: Fn | null = null;
+    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 === "R") {
+        const val = this.platform.getResource(path) ?? null;
+        fn = () => val;
+      } else {
+        const gettr = impl[`get${capitalize(pk)}`];
+        const fn0 = typeof gettr === "function" ? () => gettr.call(impl) ?? null : () => impl[pk] ?? null;
+
+        fn = !path.length ? fn0 : () => path.reduce((r, p) => r?.[p] ?? null, fn0());
+      }
+    }
+
+    map.set(propId, fn);
+
+    return fn();
+  }
+
+  getFromScope(propId: string): unknown {
+    return this.scope.get(propId);
+  }
+
+  // --- Left Arrow.
+
+  notify() {
+    this.#listeners?.forEach((fn) => fn(this));
+  }
+
+  // add listener to componet state changes
+  subscribe(handler: (src: Arrmatron) => any): Proc {
+    const listeners = this.#listeners ?? (this.#listeners = new Set());
+    listeners.add(handler);
+    return () => {
+      listeners.delete(handler);
+    };
+  }
+
+  // --- Right Arrow.
+
+  // emits action event to this component
+  emit(key: string, data: Delta): void {
+    if (this.isDone) return;
+
+    try {
+      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 impl = ref.$component;
+
+        const method = impl[target];
+        if (!(typeof method === "function")) {
+          throw new Error(`Not a method: ${refId}.${target}()`);
+        }
+
+        const result = method.call(impl, data);
+
+        // this.log(`-> ${refId}.${target}(data)`, result, data, impl);
+
+        ref.up(result);
+      } else {
+        let [refId, target] = key.split(".");
+        if (!target) {
+          target = refId;
+          refId = "this";
+        }
+
+        const ref = this.getByRef(refId);
+        if (!ref) {
+          throw new Error(`No such reference: ${refId}`);
+        }
+
+        ref.up(target === "*" ? data : { [target]: data });
+
+        // this.log(`-> ${refId}.${target} = `, data);
+      }
+
+    } catch (ex) {
+      this.logError(`emit ${key}:`, ex);
+    }
+    return;
+  }
+  // --- life-cycle.
+
+  // Done  hook.
+  done() {
+    if (this.isDone) {
+      return;
+    }
+    this.isDone = true;
+
+    this.$component.done?.(this);
+
+    this.children?.forEach((c) => c.done());
+
+    this.#defered?.forEach((f) => f(this));
+    this.#defered = undefined;
+
+    this._parent?.children?.delete(this.uid);
+    this._parent = undefined;
+  }
+
+  // register callback to be called on done
+  defer(fn: (c: IArrmatron) => void) {
+    if (fn && typeof fn === "function") {
+      (this.#defered ?? (this.#defered = [])).push(fn);
+    }
+  }
+
+  private settleAsChild() {
+    if (!this.#isInited) {
+      this.#isInited = true;
+
+      this.initConnectors();
+
+      this.up(this.#initialState, true);
+
+      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;
+
+    this.platform.redraw(this, this.root);
+
+    this.children?.forEach((e, uid) => {
+      if (!nodes?.get(uid)) {
+        e.done();
+      }
+    });
+
+    const children = new Map<Uid, Arrmatron>();
+
+    nodes?.forEach((node: IManifestNode, uid: Uid) => {
+      const e = this.$children?.get(uid) ?? node.createArrmatron(this.platform, this, this.recontentScope);
+      children.set(e.uid, e);
+    });
+
+    this.$children = children;
+
+    for (const ch of children.values()) {
+      ch.settleAsChild();
+    }
+  }
+
+  // --- Referencing.
+
+  get refId() {
+    return this.manifest.refId;
+  }
+
+  // gets any context instance in current or upper scope by key
+  getByRef(refId: string): IArrmatron | undefined {
+    if (!refId) return undefined;
+
+    if (refId === "this") {
+      return this;
+    }
+    const local = this.#refs?.[refId];
+    if (local) {
+      return local;
+    }
+    return this.parent?.getByRef(refId);
+  }
+
+  private addReference(refId: string, c: IArrmatron) {
+    (this.#refs ?? (this.#refs = {}))[refId] = c;
+  }
+
+  // --- Connectors -------------------------
+
+  private initConnectors() {
+    if (this.manifest.connectors) {
+      for (const [key, pipes] of this.manifest.connectors.entries()) {
+        const [srcIds, targetPropName] = key.split("|");
+        const [refId, sourcePropName] = srcIds.split(".");
+
+        const ref = this.parent?.getByRef(refId) as Arrmatron;
+        if (!ref) {
+          this.logError(`Connect: No such ref: ${refId}`);
+          continue;
+        }
+
+        if (!sourcePropName) {
+          this.logError(`Connect: No prop specified: ${key}`);
+          continue;
+        }
+
+        const applicator = targetPropName ? (rr: any) => ({ [targetPropName]: rr }) : identity;
+
+        this.defer((() => {
+          let popre;
+          return ref.subscribe(async (source: Arrmatron) => {
+            try {
+              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(sourcePropName))));
+      }
+    }
+  }
+
+  // --- Routines -------------------------
+
+  raceCondition(key: string) {
+    const COUNTERS = this.#weak ?? (this.#weak = new Map<string, number>());
+    let counter = 1 + (COUNTERS.get(key) ?? 0);
+    COUNTERS.set(key, counter);
+    return (fn: () => unknown) => {
+      if (counter === COUNTERS.get(key)) {
+        counter = 0;
+        return fn();
+      }
+    };
+  }
+
+  log(val: any, ...args: unknown[]) {
+    this.platform.log({
+      level: "log",
+      source: `${this.displayName}:${this.uid}`,
+      message: val,
+      params: args,
+    });
+    return val;
+  }
+
+  logError(error: any, ...args: unknown[]) {
+    this.platform.log({
+      level: "error",
+      source: `${this.displayName}:${this.uid}`,
+      error,
+      message: `${String(error.message || error)}\n${this.toString().slice(0, 120)}`,
+      params: args,
+    });
+  }
+
+  toast = (t: LogEntry) => {
+    this.platform.toast(t, this);
+  }
+
+  toString(): string {
+    return stringify(this);
+  }
+}

package/src/core/Component.ts

@@ -0,0 +1,90 @@
+import type { Delta, Hash, LogEntry } from "ultimus/types";
+
+import type { IComponent, IArrmatron } from "../../types";
+
+/**
+ * Base Ancestor for custom components.
+ */
+export abstract class Component implements IComponent {
+  [key: string]: unknown;
+
+  constructor(_: Hash, private readonly $ctx: IArrmatron) {
+    //no-op
+  }
+
+  get platform() {
+    return this.$ctx.platform;
+  }
+
+  get isDone() {
+    return this.$ctx.isDone;
+  }
+
+  // hook on done
+  done(_: IArrmatron): void {
+    //no-op
+  }
+
+  // hook on init
+  // returned value will be used to update state
+  init(_: IArrmatron): Delta | null | undefined | unknown {
+    return undefined;
+  }
+
+  // get from ctx state
+  get(key: string) {
+    return this.$ctx.get(key);
+  }
+
+  // update ctx state
+  up(d: Delta) {
+    return this.$ctx.up(d);
+  }
+
+  touch() {
+    return this.$ctx.touch();
+  }
+
+  // emit action event to another component by key
+  emit(key: string, data: Delta) {
+    return this.$ctx.emit(key, data);
+  }
+
+  // register callback to be called on done
+  defer(fn: () => void) {
+    this.$ctx.defer(fn);
+  }
+
+  // register callback to be called on done
+  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);
+  }
+
+  logError(val: unknown, ...args: unknown[]) {
+    this.$ctx.logError(val, ...args);
+  }
+
+  toString() {
+    return this.$ctx.toString();
+  }
+}

package/src/core/ManifestNode.ts

@@ -0,0 +1,150 @@
+import type { IPlatform, IArrmatron, IManifestNode } from "arrmatura/types";
+import { nextId } from "ultimus";
+import type { Delta, ExpressionText, Hash, Uid } from "ultimus/types";
+
+import { compilePipeExpression } from "../utils/compileExpression";
+
+import { Arrmatron } from "./Arrmatron";
+import { resolveExpression } from "./resolveExpression";
+
+
+type PropertyResolver = (c: IArrmatron, acc: Delta) => Delta;
+
+type PropertyGetter = (c: IArrmatron) => unknown;
+
+/**
+ * ManifestNode is a abstract factory for Arrmatron.
+ * 
+ * Each specific kind of Arrmatron has its own descending implementation of ManifestNode.
+ */
+export abstract class ManifestNode implements IManifestNode {
+  protected $content?: Map<Uid, IManifestNode> | undefined;
+  uid: Uid;
+  refId?: string;
+  private readonly propertyResolvers: PropertyResolver[] = [];
+  private initialState: Hash<(c: IArrmatron) => any> = {};
+  connectors?: Map<string, (c: IArrmatron, x: unknown) => unknown>;
+  tag: any;
+
+  constructor(xid: Uid) {
+    this.uid = `${nextId("N")}:${xid}`;
+  }
+
+  abstract get EntitronConstructor(): new (platform: IPlatform, node: typeof this, parent?: Arrmatron, scope?: Arrmatron) => Arrmatron;
+
+  /**
+   * Create a context object.
+   *
+   * @param {IPlatform} platform - The platform object.
+   * @param {IArrmatron} parent - The parent context object (optional).
+   * @param {IArrmatron} scope - The scope context object (optional).
+   * @return {IArrmatron} The created context object.
+   */
+  createArrmatron(platform: IPlatform, parent?: Arrmatron, scope?: Arrmatron): Arrmatron {
+    return new this.EntitronConstructor(platform, this, parent, scope);
+  }
+
+  getSubNodes(_platform: IPlatform): Map<Uid, IManifestNode> | undefined {
+    return this.$content;
+  }
+
+  addPropertyResolver(getter: PropertyGetter, propKey: string) {
+    this.propertyResolvers.push((c: IArrmatron, delta: Delta) => {
+      delta[propKey] = getter(c);
+      return delta;
+    });
+    return this;
+  }
+
+  private addDataPropertyResolver(getter: PropertyGetter, propKey: string) {
+    this.propertyResolvers.push((c: IArrmatron, delta: Delta) => {
+      const val = getter(c);
+      delta.data = Object.assign((delta.data as object) || {}, {
+        [propKey]: val,
+      });
+      return delta;
+    });
+    return this;
+  }
+
+  private addPropertiesResolver(getter: PropertyGetter) {
+    this.propertyResolvers.push((c: IArrmatron, delta: Delta) => {
+      const value = getter(c);
+      if (value && typeof value === "object") {
+        Object.entries(value).forEach(([key, val]) => {
+          delta[key] = val;
+        });
+      }
+      return delta;
+    });
+    return this;
+  }
+
+  addConnector(expr: ExpressionText, propName: string) {
+    const { key, pipec } = compilePipeExpression(expr);
+    (this.connectors ?? (this.connectors = new Map())).set(`${key}|${propName}`, pipec);
+  }
+
+  private addEmitter(expr: ExpressionText, k: string) {
+    const { key, pipec } = compilePipeExpression(expr);
+    const rkey = key + (expr.endsWith(")") ? "()" : '');
+    this.initialState[k] = (c) => (data: unknown) => c.scope?.emit(rkey, pipec(c, data) as Delta);
+  }
+
+  resolveInitialProps(c: IArrmatron) {
+    return this.propertyResolvers.reduce(
+      (delta, resolver) => resolver(c, delta),
+      Object.entries(this.initialState).reduce((acc, [key, fn]) => {
+        acc[key] = fn(c);
+        return acc;
+      }, {} as Hash)
+    );
+  }
+
+  resolveProps(c: IArrmatron) {
+    return this.propertyResolvers.reduce((delta, resolver) => resolver(c, delta), {});
+  }
+
+  compileAttribute(k: string, v: unknown) {
+    if (k.startsWith("data-")) {
+      this.addDataPropertyResolver(resolveExpression(v), k.slice(5));
+    } else if (k === "Ref") {
+      this.refId = String(v);
+    } else if (k === '(...)') {
+      const sv = String(v);
+      if (sv[0] === "<" && sv[1] === "-") {
+        this.addConnector(sv.slice(2), "");
+      } else {
+        this.addPropertiesResolver(resolveExpression(sv));
+      }
+    } else {
+      if (typeof v !== "string") {
+        this.initialState[k] = () => v;
+      } else {
+        if (v[0] === "<" && v[1] === "-") {
+          this.addConnector(v.slice(2), k);
+        } else if (v[0] === "-" && v[1] === ">") {
+          this.addEmitter(v.slice(2), k);
+        } else if (v[0] === "d" && v.startsWith("data->")) {
+          this.addEmitter(v.slice(6), k);
+        } else {
+          if (!v.includes("{")) {
+            this.initialState[k] = () => v;
+          } else {
+            if (v[0] === "R" && v[1] === "." && v.match(/^@@[a-z0-9\-_.]+$/i) != null) {
+              this.initialState[k] = (c) => c.platform.getResource(v.slice(2));
+            } else {
+              this.addPropertyResolver(resolveExpression(v), k);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  compileAttributes(attrs?: Hash) {
+    if (attrs) {
+      Object.entries(attrs).forEach((keyValue) => this.compileAttribute(...keyValue));
+    }
+  }
+}

package/src/core/resolveExpression.ts

@@ -0,0 +1,25 @@
+import { createStringInterpolator } from "ultimus/src/parsing/createStringInterpolator";
+
+import { compileConstant, compileJsExpression, compilePlaceholder } from "../utils/compileExpression";
+// \{\{([\w\.]+)\}\}
+
+const CACHE = new Map();
+
+function compileExpression(v: unknown) {
+  if (typeof v !== "string") return () => v;
+
+  if (v.startsWith("js:")) return compileJsExpression(v.slice(3));
+
+  if (v.includes("{")) {
+    const vCutOne = v.slice(1, -1);
+    if (v[0] === "{" && v[v.length - 1] === "}" && !vCutOne.includes("{")) {
+      return compilePlaceholder(vCutOne)
+    }
+    return createStringInterpolator(v.replace(/\s+/g, " "), compilePlaceholder);
+  }
+  return compileConstant(v);
+}
+
+export const resolveExpression = (x: unknown) => {
+  return CACHE.has(x) ? CACHE.get(x) : CACHE.set(x, compileExpression(x)).get(x);
+}