arrmatura 5.2.0 → 6.2.1

package/src/ctx/Ctx.ts

@@ -0,0 +1,424 @@
+import { areEqual, capitalize, identity } from "ultimus";
+import { stringify } from "../utils/stringify";
+import type { Delta, Fn, Hash, Proc, Uid } from "ultimus/types";
+import type {
+  EProcedure,
+  ICtx,
+  ICtxNode,
+  IComponent,
+  IPlatform,
+} from "arrmatura-api/types";
+
+/**
+ * The Component Context class.
+ * It creates, refers and manages a component instance.
+ *
+ * A component instance gets reference to its context in 2nd constructor parameter.
+ */
+export class Ctx<T extends ICtxNode = ICtxNode> implements ICtx {
+  readonly component: IComponent;
+  $children?: Map<Uid, ICtx>;
+  readonly root: ICtx;
+  readonly scope: ICtx;
+  isDone = false;
+
+  #isInited = false;
+  #state: Hash = {};
+  #initialState: Hash = {};
+  #listeners?: Set<(c: Ctx) => void>;
+  #defered?: EProcedure[] = [];
+  #weak?: Map<string, number>;
+  #refs?: Hash<ICtx>;
+  #propFnMap?: Map<string, Proc>;
+
+  constructor(
+    readonly platform: IPlatform,
+    protected readonly node: T,
+    private _parent?: ICtx,
+    scope?: ICtx
+  ) {
+    this.scope = scope ?? this;
+    this.root = scope?.root ?? this;
+    this.#initialState = this.node.resolveInitialProps(this);
+    this.component = this.createComponent(this.#initialState);
+
+    if (this.refId) {
+      this.scope.addEntityReference(this.refId, this);
+    }
+  }
+
+  get parent(): ICtx | undefined {
+    return this._parent;
+  }
+
+  get uid(): string {
+    return this.node.uid;
+  }
+
+  get displayName(): string {
+    return "🔹";
+  }
+
+  createComponent(initials: Hash): IComponent {
+    return { ...initials };
+  }
+
+  // --- State
+
+  // updates component state
+  up(Δ?: Delta | Promise<any> | null | void | unknown, force = false): void {
+    if (!Δ || this.isDone) {
+      return;
+    }
+
+    if (Δ instanceof Promise) {
+      this.upAsync(Δ, "*");
+      return;
+    }
+
+    const changes = new Map<string, unknown>();
+    Object.entries(Δ).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);
+      }
+    });
+
+    if (changes.size || force) {
+      this.stateChanged(changes);
+    }
+  }
+
+  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
+  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 {
+      const [pk, ...path] = propId.split(".");
+      if (pk[0] === "@") {
+        path.unshift(pk.slice(1));
+        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: Ctx) => 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 (!key || !key.includes(".")) {
+      this.up(key ? { [key]: data } : data);
+      return;
+    }
+
+    const [refId, target] = key.split(".");
+    try {
+      const ref = this.getByRef(refId);
+      if (!ref) {
+        throw new Error(`No such reference: ${refId}`);
+      }
+      if (!target) {
+        ref.up(data);
+        return;
+      }
+
+      const propId = `on${capitalize(target)}`;
+      const impl = ref.component;
+      const method = impl[propId];
+
+      if (!method) {
+        ref.up({ [target]: data });
+        return;
+      }
+
+      if (!method || !(typeof method === "function")) {
+        throw new Error(`No such method ${refId}.${propId}`);
+      }
+
+      const result = method.call(impl, data, impl, ref);
+
+      this.log(`-> ${refId}.${propId}`, result, data, impl);
+
+      ref.up(result);
+    } catch (ex) {
+      this.logError(`emit ${key}:`, ex);
+    }
+    return;
+  }
+
+  // Done life-cycle 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;
+  }
+
+  // map of children contexts
+  get children(): Map<Uid, ICtx> | undefined {
+    return this.$children;
+  }
+
+  // map of chidren of its node
+  get content() {
+    return this.node.getContent(this.platform);
+  }
+
+  // actual scope for re-content
+  get recontentScope() {
+    return this.scope;
+  }
+
+  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.node.resolveProps(this), true);
+    }
+  }
+
+  // perform children instantiation and updates
+  private recontent() {
+    const nodes = this.content;
+
+    this.platform.redraw(this, this.root);
+
+    this.children?.forEach((e, uid) => {
+      if (!nodes?.get(uid)) {
+        e.done();
+      }
+    });
+
+    const children = new Map<Uid, ICtx>();
+
+    nodes?.forEach((node: ICtxNode, uid: Uid) => {
+      const e =
+        this.children?.get(uid) ??
+        node.createContext(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.node.refId;
+  }
+
+  // gets any context instance in current or upper scope by key
+  getByRef(refId: string): ICtx | undefined {
+    if (!refId) return undefined;
+
+    if (refId === "this") {
+      return this;
+    }
+    const local = this.#refs?.[refId];
+    if (local) {
+      return local;
+    }
+    const ref = this === this.scope ? null : this.scope.getByRef(refId);
+    return ref as Ctx;
+  }
+
+  addEntityReference(refId: string, c: ICtx) {
+    (this.#refs ?? (this.#refs = {}))[refId] = c;
+  }
+
+  // --- Routines -------------------------
+
+  private initConnectors() {
+    if (this.node.connectors) {
+      for (const [key, pipes] of this.node.connectors.entries()) {
+        const [srcIds, targetPropName] = key.split("|");
+        const [refId, ...propIds] = srcIds.split(".");
+
+        const ref = this.scope.getByRef(refId) as Ctx;
+        if (!ref) {
+          this.logError(`Connect: No such ref: ${refId}`);
+          continue;
+        }
+
+        if (!propIds.length) {
+          this.logError(`Connect: No prop specified: ${key}`);
+          continue;
+        }
+
+        const propId = propIds.join(".");
+        const applicator = targetPropName
+          ? (rr: any) => ({ [targetPropName]: rr })
+          : identity;
+
+        this.defer(
+          ref.subscribe((source: Ctx) => {
+            try {
+              const r = applicator(pipes(this, source.get(propId)));
+              this.up(r as Delta);
+            } catch (ex) {
+              source.logError("Notify ", ex);
+            }
+          })
+        );
+
+        // hot subscription
+        Object.assign(
+          this.#initialState,
+          applicator(pipes(ref, ref.get(propId)))
+        );
+      }
+    }
+  }
+
+  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();
+      }
+    };
+  }
+
+  // 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",
+      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,
+    });
+  }
+
+  // access to resource by key
+  res(key: string | string[]) {
+    return this.platform.getResource(key);
+  }
+
+  toString(): string {
+    return stringify(this);
+  }
+}

package/src/ctx/CtxNode.ts

@@ -0,0 +1,159 @@
+import { nextId } from "ultimus";
+import {
+  compileExpression,
+  compilePipeExpression,
+} from "../utils/compileExpression";
+import type { Delta, Expression, Hash, Uid } from "ultimus/types";
+import type {
+  IPlatform,
+  ICtx,
+  ICtxNode,
+  PropertyGetter,
+  PropertyResolver,
+} from "arrmatura-api/types";
+
+/**
+ * ContextNode is a factory for all ICtx instances.
+ */
+export abstract class CtxNode implements ICtxNode {
+  protected $content?: Map<Uid, ICtxNode> | undefined;
+  uid: Uid = nextId("N");
+  refId?: string;
+  private readonly propertyResolvers: PropertyResolver[] = [];
+  private initialState: Hash<(c: ICtx) => any> = {};
+  connectors?: Map<string, (c: ICtx, x: unknown) => unknown>;
+  tag: any;
+
+  abstract get EntityConstructor(): new (
+    platform: IPlatform,
+    node: typeof this,
+    parent?: ICtx,
+    scope?: ICtx
+  ) => ICtx;
+
+  /**
+   * Create a context object.
+   *
+   * @param {IPlatform} platform - The platform object.
+   * @param {ICtx} parent - The parent context object (optional).
+   * @param {ICtx} scope - The scope context object (optional).
+   * @return {ICtx} The created context object.
+   */
+  createContext(platform: IPlatform, parent?: ICtx, scope?: ICtx): ICtx {
+    return new this.EntityConstructor(platform, this, parent, scope);
+  }
+
+  getContent(_platform: IPlatform): Map<Uid, ICtxNode> | undefined {
+    return this.$content;
+  }
+
+  addPropertyResolver(getter: PropertyGetter, propKey: string) {
+    this.propertyResolvers.push((c: ICtx, delta: Delta) => {
+      delta[propKey] = getter(c);
+      return delta;
+    });
+    return this;
+  }
+
+  private addDataPropertyResolver(getter: PropertyGetter, propKey: string) {
+    this.propertyResolvers.push((c: ICtx, 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: ICtx, 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: Expression, propName: string) {
+    const { key, pipec } = compilePipeExpression(expr);
+    (this.connectors ?? (this.connectors = new Map())).set(
+      `${key}|${propName}`,
+      pipec
+    );
+  }
+
+  private addEmitter(expr: Expression, k: string) {
+    const { key, pipec } = compilePipeExpression(expr);
+    this.initialState[k] = (c) => (data: unknown) =>
+      c.scope?.emit(key, pipec(c, data) as Delta);
+  }
+
+  resolveInitialProps(c: ICtx) {
+    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: ICtx) {
+    return this.propertyResolvers.reduce(
+      (delta, resolver) => resolver(c, delta),
+      {}
+    );
+  }
+
+  compileAttribute(k: string, v: unknown) {
+    if (k.startsWith("data-")) {
+      this.addDataPropertyResolver(compileExpression(v), k.slice(5));
+    } else if (k === "ref") {
+      this.refId = String(v);
+    } else if (k === "props") {
+      const sv = String(v);
+      if (sv[0] === "<" && sv[1] === "-") {
+        this.addConnector(sv.slice(2), "");
+      } else {
+        this.addPropertiesResolver(compileExpression(v));
+      }
+    } 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.includes("{") && v[0] !== "@") {
+            this.initialState[k] = () => v;
+          } else {
+            if (
+              v[0] === "@" &&
+              v[1] === "@" &&
+              v.match(/^@@[a-z0-9\-_.]+$/i) != null
+            ) {
+              this.initialState[k] = (c) => c.platform.getResource(v.slice(2));
+            } else {
+              this.addPropertyResolver(compileExpression(v), k);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  compileAttributes(attrs?: Hash) {
+    if (attrs) {
+      Object.entries(attrs).forEach((keyValue) =>
+        this.compileAttribute(...keyValue)
+      );
+    }
+  }
+}

package/src/utils/compileExpression.ts

@@ -0,0 +1,126 @@
+import { scalarParse } from "ultimus";
+import type { Expression, Fn, StringHash } from "ultimus/types";
+import type { ICtx } from "arrmatura-api/types";
+import { createStringInterpolator } from "ultimus/src/parsing/createStringInterpolator";
+
+type PipeFn = (c: ICtx, argValue: unknown) => unknown;
+
+const OP_SHORTCUTS: StringHash = {
+  "&&": "|and:",
+  "==": "|equals:",
+  "!=": "|notEquals:",
+  "||": "|or:",
+  "<": "|less:",
+  "[": "|dot:",
+  "]": "",
+  ">": "|greater:",
+  "??": "|coalesce:",
+  "?": "|then:",
+};
+
+const withNoPipes = (_: unknown, v: unknown) => v;
+
+function compileConstant(a: string) {
+  const vv = scalarParse(a[0] === "'" ? a.slice(1, a.length - 1) : a);
+  return () => vv;
+}
+
+const compilePropGet = (key: string) => {
+  return (c: ICtx) => c.getFromScope(key);
+};
+
+const compileArgument = (a: string) => {
+  if (a[0] !== "@") return compileConstant(a);
+
+  if (a.endsWith("#not")) {
+    const getter = compilePropGet(a.slice(1, a.length - 4));
+    return (c: ICtx) => !getter(c);
+  }
+
+  return compilePropGet(a.slice(1));
+};
+
+const splitExpression = (v: Expression) =>
+  v
+    .replace(/(&&|!=|==|>|<|\[|\]|\|\||\?\??)/g, (_, s) => `${OP_SHORTCUTS[s]}`)
+    .split("|")
+    .map((s) => s.trim());
+
+function withPipes(pipes: string[]) {
+  if (!pipes.length) return withNoPipes;
+
+  const compiledPipes = pipes.map((key) => {
+    const [pipeId, ...args] = key.split(":").map((s) => s.trim());
+    return {
+      pipeId,
+      args: args.map((a) => compileArgument(a)),
+    };
+  });
+
+  return (c: ICtx, initialValue: unknown) =>
+    compiledPipes.reduce((value, { pipeId, args }) => {
+      try {
+        const fn = c.platform.getFunction(pipeId);
+        if (typeof fn !== "function") {
+          throw new Error(`${fn != null ? "must be a function" : "not found"}`);
+        }
+        const args0 = [value, ...args.map((fn) => fn(c))];
+        return fn.apply(c, args0);
+      } catch (ex) {
+        c.logError(`ERROR: Function ${pipeId || "<empty>"}`, ex);
+        return value;
+      }
+    }, initialValue);
+}
+
+function withHardValue(hardValue: Expression, pipec: PipeFn): PipeFn {
+  if (hardValue === undefined) return pipec;
+  const iniFn =
+    hardValue[0] === "@"
+      ? compilePlaceholder(hardValue)
+      : compileConstant(hardValue);
+  return (c: ICtx) => pipec(c, iniFn(c));
+}
+
+export function compilePipeExpression(v: Expression) {
+  const [_key, ...pipes] = splitExpression(v);
+  const [key, hardValue] = _key.split("=").map((s) => s.trim());
+  return { key, pipec: withHardValue(hardValue, withPipes(pipes)) };
+}
+
+export function compilePlaceholder(expr: string): Fn {
+
+  const [key, ...pipesExpressions] = splitExpression(expr);
+  const pipec = withPipes(pipesExpressions);
+
+  let fn: any = null;
+
+  if (key[0] === "'") {
+    fn = compileConstant(key);
+  } else {
+    if (key[0] !== "@") {
+      console.warn(`Invalid placeholder "${expr}"`);
+    }
+    fn = compileArgument(key[0] === "@" ? key : `@${key}`);
+  }
+
+  return (c) => pipec(c as ICtx, fn(c));
+}
+
+const JS = {}
+export function compileJsExpression(x: string) {
+  return JS[x] ?? (JS[x] = new Function('c', x.replaceAll(/[^'a-z]([a-z][a-z0-9-\.]+)/ig, 'c.prop("$1")')))
+}
+
+export function compileExpression(v: unknown) {
+  if (typeof v !== "string") return () => v;
+
+  if (v[0] === "@") return compilePlaceholder(v);
+
+  if (v.startsWith("js:")) return compileJsExpression(v.slice(3));
+
+  if (v.includes("{"))
+    return createStringInterpolator(v.replace(/\s+/g, " "), compilePlaceholder);
+
+  return compileConstant(v);
+}