epos-unit 1.13.0 → 1.15.0

package/dist/epos-unit.d.ts

@@ -1,30 +1,67 @@
 import * as mobx from 'mobx';
-import { Cls } from 'dropcap/types';
-import { Log } from 'dropcap/utils';
+import { Cls, Obj, Arr } from 'dropcap/types';
+import { createLog } from 'dropcap/utils';
 
 declare const _root_: unique symbol;
 declare const _parent_: unique symbol;
+declare const _attached_: unique symbol;
 declare const _disposers_: unique symbol;
-type Descriptors = Record<string | symbol, PropertyDescriptor>;
+declare const _ancestors_: unique symbol;
+declare const _pendingAttachFns_: unique symbol;
+type Node<T> = Unit<T> | Obj | Arr;
 declare class Unit<TRoot = unknown> {
-    static [epos.symbols.stateModelStrict]: boolean;
-    static [epos.symbols.stateModelVersioner]: unknown;
-    [epos.symbols.stateModelInit]: () => void;
-    [epos.symbols.stateModelDispose]: () => void;
+    /**
+     * Lifecycle method called when the unit is attached to the state tree.
+     */
+    [epos.state.ATTACH]: () => void;
+    /**
+     * Lifecycle method called when the unit is detached from the state tree.
+     */
+    [epos.state.DETACH]: () => void;
     '@': string;
-    log: Log;
+    log: ReturnType<typeof createLog>;
     [':version']?: number;
-    private [_root_];
-    private [_parent_];
-    private [_disposers_];
+    [_root_]?: TRoot;
+    [_parent_]?: Unit<TRoot> | null;
+    [_attached_]?: boolean;
+    [_disposers_]?: Set<() => void>;
+    [_ancestors_]?: Map<Cls, unknown>;
+    [_pendingAttachFns_]?: (() => void)[];
     constructor(parent: Unit<TRoot> | null);
-    get $(): TRoot;
+    /**
+     * Gets the root unit of the current unit's tree.
+     * The result is cached for subsequent calls.
+     */
+    get $(): TRoot | (undefined & TRoot);
+    /**
+     * Finds the closest ancestor unit of a given type.
+     * The result is cached for subsequent calls.
+     */
     closest<T extends Unit>(Ancestor: Cls<T>): T | null;
+    /**
+     * A wrapper around MobX's `autorun` that automatically disposes
+     * the reaction when the unit is detached.
+     */
     autorun(...args: Parameters<typeof epos.libs.mobx.autorun>): mobx.IReactionDisposer;
+    /**
+     * A wrapper around MobX's `reaction` that automatically disposes
+     * the reaction when the unit is detached.
+     */
     reaction(...args: Parameters<typeof epos.libs.mobx.reaction>): mobx.IReactionDisposer;
+    /**
+     * A wrapper around `setTimeout` that automatically clears the timeout
+     * when the unit is detached.
+     */
     setTimeout(...args: Parameters<typeof self.setTimeout>): number;
+    /**
+     * A wrapper around `setInterval` that automatically clears the interval
+     * when the unit is detached.
+     */
     setInterval(...args: Parameters<typeof self.setInterval>): number;
-    never(message?: string): void;
+    /**
+     * Creates an error for an unreachable code path.
+     */
+    never(message?: string): Error;
 }
 
-export { type Descriptors, Unit, _disposers_, _parent_, _root_ };
+export { type Node, Unit, _ancestors_, _attached_, _disposers_, _parent_, _pendingAttachFns_, _root_ };

package/dist/epos-unit.js

@@ -1,113 +1,178 @@
 // src/epos-unit.ts
+import { createLog, is } from "dropcap/utils";
 import "epos";
-import { createLog } from "dropcap/utils";
 var _root_ = /* @__PURE__ */ Symbol("root");
 var _parent_ = /* @__PURE__ */ Symbol("parent");
+var _attached_ = /* @__PURE__ */ Symbol("attached");
 var _disposers_ = /* @__PURE__ */ Symbol("disposers");
+var _ancestors_ = /* @__PURE__ */ Symbol("ancestors");
+var _pendingAttachFns_ = /* @__PURE__ */ Symbol("pendingAttachFns");
 var Unit = class {
-  static get [epos.symbols.stateModelStrict]() {
-    return true;
-  }
   constructor(parent) {
-    Reflect.defineProperty(this, _parent_, { get: () => parent });
+    this[_parent_] = parent;
+    const versions = getVersions(this);
+    if (versions.length > 0) this[":version"] = versions.at(-1);
   }
-  // ---------------------------------------------------------------------------
-  // INIT
-  // ---------------------------------------------------------------------------
-  [epos.symbols.stateModelInit]() {
-    const _this = this;
-    const Unit2 = this.constructor;
-    const descriptors = Object.getOwnPropertyDescriptors(Unit2.prototype);
-    const keys = Reflect.ownKeys(descriptors);
-    const disposers = /* @__PURE__ */ new Set();
-    Reflect.defineProperty(this, _disposers_, { get: () => disposers });
-    for (const key of keys) {
-      if (key === "constructor") continue;
-      const descriptor = descriptors[key];
-      if (!descriptor) continue;
-      if (descriptor.get || descriptor.set) continue;
-      if (typeof descriptor.value !== "function") continue;
-      _this[key] = descriptor.value.bind(this);
+  /**
+   * Lifecycle method called when the unit is attached to the state tree.
+   */
+  [epos.state.ATTACH]() {
+    setProperty(this, "log", createLog(this["@"]));
+    epos.state.transaction(() => {
+      const versioner = getVersioner(this);
+      const versions = getVersions(this);
+      for (const version of versions) {
+        if (is.number(this[":version"]) && this[":version"] >= version) continue;
+        const versionFn = versioner[version];
+        if (!is.function(versionFn)) continue;
+        versionFn.call(this, this);
+        this[":version"] = version;
+      }
+    });
+    for (const prototype of getPrototypes(this)) {
+      const descriptors = Object.getOwnPropertyDescriptors(prototype);
+      for (const [key, descriptor] of Object.entries(descriptors)) {
+        if (key === "constructor") continue;
+        if (this.hasOwnProperty(key)) continue;
+        if (descriptor.get || descriptor.set) continue;
+        if (!is.function(descriptor.value)) continue;
+        const fn = descriptor.value.bind(this);
+        if (key.endsWith("View")) {
+          let Component = epos.component(fn);
+          Component.displayName = `${this.constructor.name}.${key}`;
+          setProperty(this, key, Component);
+        } else {
+          setProperty(this, key, fn);
+        }
+      }
     }
-    for (const key of keys) {
-      if (typeof key === "symbol") continue;
-      if (!key.endsWith("View")) continue;
-      const descriptor = descriptors[key];
-      if (!descriptor) continue;
-      if (descriptor.get || descriptor.set) continue;
-      if (typeof _this[key] !== "function") continue;
-      _this[key] = epos.component(_this[key]);
-      _this[key].displayName = `${this["@"]}.${key}`;
+    const stateDescriptor = Reflect.getOwnPropertyDescriptor(this.constructor.prototype, "state");
+    if (stateDescriptor && stateDescriptor.get) {
+      const state = stateDescriptor.get.call(this);
+      setProperty(this, "state", epos.libs.mobx.observable.object(state, {}, { deep: false }));
     }
-    const log = createLog(this["@"]);
-    Reflect.defineProperty(this, "log", { get: () => log });
-    if (typeof _this.init === "function") _this.init();
-  }
-  // ---------------------------------------------------------------------------
-  // DISPOSE
-  // ---------------------------------------------------------------------------
-  [epos.symbols.stateModelDispose]() {
-    const _this = this;
-    this[_disposers_].forEach((disposer) => disposer());
-    this[_disposers_].clear();
-    if (typeof _this.dispose === "function") _this.dispose();
+    const attach = Reflect.get(this, "attach");
+    if (is.function(attach)) {
+      const unattachedRoot = findUnattachedRoot(this);
+      if (!unattachedRoot) throw this.never();
+      ensureProperty(unattachedRoot, _pendingAttachFns_, () => []);
+      unattachedRoot[_pendingAttachFns_].push(() => attach());
+      if (this[_pendingAttachFns_]) {
+        this[_pendingAttachFns_].forEach((attach2) => attach2());
+        delete this[_pendingAttachFns_];
+      }
+    }
+    setProperty(this, _attached_, true);
   }
-  // ---------------------------------------------------------------------------
-  // VERSIONER
-  // ---------------------------------------------------------------------------
-  static get [epos.symbols.stateModelVersioner]() {
-    if (!("versioner" in this)) return null;
-    return this.versioner;
+  /**
+   * Lifecycle method called when the unit is detached from the state tree.
+   */
+  [epos.state.DETACH]() {
+    if (this[_disposers_]) {
+      this[_disposers_].forEach((disposer) => disposer());
+      this[_disposers_].clear();
+    }
+    const detach = Reflect.get(this, "detach");
+    if (is.function(detach)) detach();
+    delete this[_root_];
+    delete this[_attached_];
+    delete this[_ancestors_];
+    delete this[_disposers_];
   }
-  // ---------------------------------------------------------------------------
-  // ROOT
-  // ---------------------------------------------------------------------------
+  /**
+   * Gets the root unit of the current unit's tree.
+   * The result is cached for subsequent calls.
+   */
   get $() {
-    this[_root_] ??= findRoot(this);
+    ensureProperty(this, _root_, () => findRoot(this));
     return this[_root_];
   }
-  // ---------------------------------------------------------------------------
-  // METHODS
-  // ---------------------------------------------------------------------------
+  /**
+   * Finds the closest ancestor unit of a given type.
+   * The result is cached for subsequent calls.
+   */
   closest(Ancestor) {
-    let cursor = getParent(this);
+    ensureProperty(this, _ancestors_, () => /* @__PURE__ */ new Map());
+    if (this[_ancestors_].has(Ancestor)) return this[_ancestors_].get(Ancestor);
+    let cursor = this;
     while (cursor) {
-      if (cursor instanceof Ancestor) return cursor;
+      if (cursor instanceof Ancestor) {
+        this[_ancestors_].set(Ancestor, cursor);
+        return cursor;
+      }
       cursor = getParent(cursor);
     }
     return null;
   }
+  /**
+   * A wrapper around MobX's `autorun` that automatically disposes
+   * the reaction when the unit is detached.
+   */
   autorun(...args) {
     const disposer = epos.libs.mobx.autorun(...args);
+    ensureProperty(this, _disposers_, () => /* @__PURE__ */ new Set());
     this[_disposers_].add(disposer);
     return disposer;
   }
+  /**
+   * A wrapper around MobX's `reaction` that automatically disposes
+   * the reaction when the unit is detached.
+   */
   reaction(...args) {
     const disposer = epos.libs.mobx.reaction(...args);
+    ensureProperty(this, _disposers_, () => /* @__PURE__ */ new Set());
     this[_disposers_].add(disposer);
     return disposer;
   }
+  /**
+   * A wrapper around `setTimeout` that automatically clears the timeout
+   * when the unit is detached.
+   */
   setTimeout(...args) {
     const id = self.setTimeout(...args);
+    ensureProperty(this, _disposers_, () => /* @__PURE__ */ new Set());
     this[_disposers_].add(() => self.clearTimeout(id));
     return id;
   }
+  /**
+   * A wrapper around `setInterval` that automatically clears the interval
+   * when the unit is detached.
+   */
   setInterval(...args) {
     const id = self.setInterval(...args);
+    ensureProperty(this, _disposers_, () => /* @__PURE__ */ new Set());
     this[_disposers_].add(() => self.clearInterval(id));
     return id;
   }
+  /**
+   * Creates an error for an unreachable code path.
+   */
   never(message = "This should never happen") {
-    const error = new Error(`[${this["@"]}] ${message}`);
+    const details = message ? `: ${message}` : "";
+    const error = new Error(`[${this.constructor.name}] This should never happen${details}`);
     Error.captureStackTrace(error, this.never);
-    throw error;
+    return error;
   }
 };
-function getParent(child) {
-  return child[_parent_] ?? child[epos.symbols.stateParent];
+function setProperty(object, key, value) {
+  Reflect.defineProperty(object, key, {
+    configurable: true,
+    get: () => value,
+    set: (v) => value = v
+  });
+}
+function ensureProperty(object, key, getInitialValue) {
+  if (key in object) return;
+  const value = getInitialValue();
+  Reflect.defineProperty(object, key, { configurable: true, get: () => value });
+}
+function getPrototypes(object) {
+  const prototype = Reflect.getPrototypeOf(object);
+  if (!prototype || prototype === Object.prototype) return [];
+  return [prototype, ...getPrototypes(prototype)];
 }
 function findRoot(unit) {
-  let root = unit;
+  let root = null;
   let cursor = unit;
   while (cursor) {
     if (cursor instanceof Unit) root = cursor;
@@ -115,9 +180,36 @@ function findRoot(unit) {
   }
   return root;
 }
+function findUnattachedRoot(unit) {
+  let unattachedRoot = null;
+  let cursor = unit;
+  while (cursor) {
+    if (cursor instanceof Unit && !cursor[_attached_]) unattachedRoot = cursor;
+    cursor = getParent(cursor);
+  }
+  return unattachedRoot;
+}
+function getParent(node) {
+  const parent = Reflect.get(node, _parent_) ?? Reflect.get(node, epos.state.PARENT) ?? null;
+  return parent;
+}
+function getVersioner(unit) {
+  const versioner = Reflect.get(unit.constructor, "versioner");
+  if (!is.object(versioner)) return {};
+  return versioner;
+}
+function getVersions(unit) {
+  const versioner = getVersioner(unit);
+  const numericKeys = Object.keys(versioner).filter((key) => is.numeric(key));
+  return numericKeys.map(Number).sort((v1, v2) => v1 - v2);
+}
 export {
   Unit,
+  _ancestors_,
+  _attached_,
   _disposers_,
   _parent_,
+  _pendingAttachFns_,
   _root_
 };
+//# sourceMappingURL=epos-unit.js.map

package/dist/epos-unit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/epos-unit.ts"],"sourcesContent":["import type { Arr, Cls, Obj } from 'dropcap/types'\nimport { createLog, is } from 'dropcap/utils'\nimport 'epos'\n\nexport const _root_ = Symbol('root')\nexport const _parent_ = Symbol('parent')\nexport const _attached_ = Symbol('attached')\nexport const _disposers_ = Symbol('disposers')\nexport const _ancestors_ = Symbol('ancestors')\nexport const _pendingAttachFns_ = Symbol('pendingAttachFns')\n\nexport type Node<T> = Unit<T> | Obj | Arr\n\nexport class Unit<TRoot = unknown> {\n  declare '@': string\n  declare log: ReturnType<typeof createLog>;\n  declare [':version']?: number;\n  declare [_root_]?: TRoot;\n  declare [_parent_]?: Unit<TRoot> | null; // Parent reference for a not-yet-attached units\n  declare [_attached_]?: boolean;\n  declare [_disposers_]?: Set<() => void>;\n  declare [_ancestors_]?: Map<Cls, unknown>;\n  declare [_pendingAttachFns_]?: (() => void)[]\n\n  constructor(parent: Unit<TRoot> | null) {\n    this[_parent_] = parent\n    const versions = getVersions(this)\n    if (versions.length > 0) this[':version'] = versions.at(-1)!\n  }\n\n  /**\n   * Lifecycle method called when the unit is attached to the state tree.\n   */\n  [epos.state.ATTACH]() {\n    // Setup logger\n    setProperty(this, 'log', createLog(this['@']))\n\n    // Apply versioner\n    epos.state.transaction(() => {\n      const versioner = getVersioner(this)\n      const versions = getVersions(this)\n      for (const version of versions) {\n        if (is.number(this[':version']) && this[':version'] >= version) continue\n        const versionFn = versioner[version]\n        if (!is.function(versionFn)) continue\n        versionFn.call(this, this)\n        this[':version'] = version\n      }\n    })\n\n    // Prepare methods:\n    // - Create components for methods ending with `View`\n    // - Bind all other methods to the unit instance\n    for (const prototype of getPrototypes(this)) {\n      const descriptors = Object.getOwnPropertyDescriptors(prototype)\n\n      for (const [key, descriptor] of Object.entries(descriptors)) {\n        if (key === 'constructor') continue\n        if (this.hasOwnProperty(key)) continue\n\n        if (descriptor.get || descriptor.set) continue\n        if (!is.function(descriptor.value)) continue\n        const fn = descriptor.value.bind(this)\n\n        if (key.endsWith('View')) {\n          let Component = epos.component(fn)\n          Component.displayName = `${this.constructor.name}.${key}`\n          setProperty(this, key, Component)\n        } else {\n          setProperty(this, key, fn)\n        }\n      }\n    }\n\n    // Setup state\n    const stateDescriptor = Reflect.getOwnPropertyDescriptor(this.constructor.prototype, 'state')\n    if (stateDescriptor && stateDescriptor.get) {\n      const state = stateDescriptor.get.call(this)\n      setProperty(this, 'state', epos.libs.mobx.observable.object(state, {}, { deep: false }))\n    }\n\n    // Process attach queue.\n    // We do not execute `attach` methods immediately, but rather queue them\n    // on the highest unattached ancestor. This way we ensure that `attach`\n    // methods are called after all versioners have been applied in the entire subtree.\n    const attach = Reflect.get(this, 'attach')\n    if (is.function(attach)) {\n      const unattachedRoot = findUnattachedRoot(this)\n      if (!unattachedRoot) throw this.never()\n\n      ensureProperty(unattachedRoot, _pendingAttachFns_, () => [])\n      unattachedRoot[_pendingAttachFns_].push(() => attach())\n\n      if (this[_pendingAttachFns_]) {\n        this[_pendingAttachFns_].forEach(attach => attach())\n        delete this[_pendingAttachFns_]\n      }\n    }\n\n    // Mark as attached\n    setProperty(this, _attached_, true)\n  }\n\n  /**\n   * Lifecycle method called when the unit is detached from the state tree.\n   */\n  [epos.state.DETACH]() {\n    // 1. Run disposers\n    if (this[_disposers_]) {\n      this[_disposers_].forEach(disposer => disposer())\n      this[_disposers_].clear()\n    }\n\n    // 2. Call detach method\n    const detach = Reflect.get(this, 'detach')\n    if (is.function(detach)) detach()\n\n    // 3. Clean up internal properties\n    delete this[_root_]\n    delete this[_attached_]\n    delete this[_ancestors_]\n    delete this[_disposers_]\n  }\n\n  /**\n   * Gets the root unit of the current unit's tree.\n   * The result is cached for subsequent calls.\n   */\n  get $() {\n    ensureProperty(this, _root_, () => findRoot(this))\n    return this[_root_]\n  }\n\n  /**\n   * Finds the closest ancestor unit of a given type.\n   * The result is cached for subsequent calls.\n   */\n  closest<T extends Unit>(Ancestor: Cls<T>) {\n    // Has cached value? -> Return it\n    ensureProperty(this, _ancestors_, () => new Map())\n    if (this[_ancestors_].has(Ancestor)) return this[_ancestors_].get(Ancestor) as T\n\n    // Find the closest ancestor and cache it\n    let cursor: Node<TRoot> | null = this\n    while (cursor) {\n      if (cursor instanceof Ancestor) {\n        this[_ancestors_].set(Ancestor, cursor)\n        return cursor\n      }\n      cursor = getParent(cursor)\n    }\n\n    return null\n  }\n\n  /**\n   * A wrapper around MobX's `autorun` that automatically disposes\n   * the reaction when the unit is detached.\n   */\n  autorun(...args: Parameters<typeof epos.libs.mobx.autorun>) {\n    const disposer = epos.libs.mobx.autorun(...args)\n    ensureProperty(this, _disposers_, () => new Set())\n    this[_disposers_].add(disposer)\n    return disposer\n  }\n\n  /**\n   * A wrapper around MobX's `reaction` that automatically disposes\n   * the reaction when the unit is detached.\n   */\n  reaction(...args: Parameters<typeof epos.libs.mobx.reaction>) {\n    const disposer = epos.libs.mobx.reaction(...args)\n    ensureProperty(this, _disposers_, () => new Set())\n    this[_disposers_].add(disposer)\n    return disposer\n  }\n\n  /**\n   * A wrapper around `setTimeout` that automatically clears the timeout\n   * when the unit is detached.\n   */\n  setTimeout(...args: Parameters<typeof self.setTimeout>) {\n    const id = self.setTimeout(...args)\n    ensureProperty(this, _disposers_, () => new Set())\n    this[_disposers_].add(() => self.clearTimeout(id))\n    return id\n  }\n\n  /**\n   * A wrapper around `setInterval` that automatically clears the interval\n   * when the unit is detached.\n   */\n  setInterval(...args: Parameters<typeof self.setInterval>) {\n    const id = self.setInterval(...args)\n    ensureProperty(this, _disposers_, () => new Set())\n    this[_disposers_].add(() => self.clearInterval(id))\n    return id\n  }\n\n  /**\n   * Creates an error for an unreachable code path.\n   */\n  never(message = 'This should never happen') {\n    const details = message ? `: ${message}` : ''\n    const error = new Error(`[${this.constructor.name}] This should never happen${details}`)\n    Error.captureStackTrace(error, this.never)\n    return error\n  }\n}\n\n// ---------------------------------------------------------------------------\n// HELPERS\n// ---------------------------------------------------------------------------\n\n/**\n * Defines a configurable property on an object.\n */\nfunction setProperty(object: object, key: PropertyKey, value: unknown) {\n  Reflect.defineProperty(object, key, {\n    configurable: true,\n    get: () => value,\n    set: v => (value = v),\n  })\n}\n\n/**\n * Ensures a property exists on an object, initializing it if it doesn't.\n */\nfunction ensureProperty<T extends object, K extends PropertyKey, V>(\n  object: T,\n  key: K,\n  getInitialValue: () => V,\n): asserts object is T & { [key in K]: V } {\n  if (key in object) return\n  const value = getInitialValue()\n  Reflect.defineProperty(object, key, { configurable: true, get: () => value })\n}\n\n/**\n * Gets all prototypes of an object up to `Object.prototype`.\n */\nfunction getPrototypes(object: object): object[] {\n  const prototype = Reflect.getPrototypeOf(object)\n  if (!prototype || prototype === Object.prototype) return []\n  return [prototype, ...getPrototypes(prototype)]\n}\n\n/**\n * Finds the root `Unit` in the hierarchy for a given unit.\n */\nfunction findRoot<T>(unit: Unit<T>) {\n  let root: Unit<T> | null = null\n  let cursor: Node<T> | null = unit\n\n  while (cursor) {\n    if (cursor instanceof Unit) root = cursor\n    cursor = getParent(cursor)\n  }\n\n  return root as T\n}\n\n/**\n * Finds the highest unattached `Unit` in the hierarchy for a given unit.\n */\nfunction findUnattachedRoot<T>(unit: Unit<T>) {\n  let unattachedRoot: Unit<T> | null = null\n  let cursor: Node<T> | null = unit\n\n  while (cursor) {\n    if (cursor instanceof Unit && !cursor[_attached_]) unattachedRoot = cursor\n    cursor = getParent(cursor)\n  }\n\n  return unattachedRoot\n}\n\n/**\n * Gets the parent of a node, which can be a `Unit`, an object, or an array.\n */\nfunction getParent<T>(node: Node<T>) {\n  const parent: Node<T> | null = Reflect.get(node, _parent_) ?? Reflect.get(node, epos.state.PARENT) ?? null\n  return parent\n}\n\n/**\n * Gets the versioner object from a unit's constructor.\n */\nfunction getVersioner<T>(unit: Unit<T>) {\n  const versioner: unknown = Reflect.get(unit.constructor, 'versioner')\n  if (!is.object(versioner)) return {}\n  return versioner\n}\n\n/**\n * Gets a sorted list of numeric version keys from a unit's versioner.\n */\nfunction getVersions<T>(unit: Unit<T>) {\n  const versioner = getVersioner(unit)\n  const numericKeys = Object.keys(versioner).filter(key => is.numeric(key))\n  return numericKeys.map(Number).sort((v1, v2) => v1 - v2)\n}\n"],"mappings":"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","names":["attach"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "epos-unit",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "type": "module",
   "license": "MIT",
   "author": "imkost",
@@ -20,7 +20,7 @@
     "src"
   ],
   "dependencies": {
-    "dropcap": "^1.0.0",
-    "epos": "^1.30.0"
+    "dropcap": "^1.4.0",
+    "epos": "^1.32.0"
   }
 }

package/src/epos-unit.ts

@@ -1,148 +1,210 @@
+import type { Arr, Cls, Obj } from 'dropcap/types'
+import { createLog, is } from 'dropcap/utils'
 import 'epos'
-import type { Cls } from 'dropcap/types'
-import { createLog, Log } from 'dropcap/utils'
-import type { FC } from 'react'
 
 export const _root_ = Symbol('root')
 export const _parent_ = Symbol('parent')
+export const _attached_ = Symbol('attached')
 export const _disposers_ = Symbol('disposers')
-export type Descriptors = Record<string | symbol, PropertyDescriptor>
+export const _ancestors_ = Symbol('ancestors')
+export const _pendingAttachFns_ = Symbol('pendingAttachFns')
+
+export type Node<T> = Unit<T> | Obj | Arr
 
 export class Unit<TRoot = unknown> {
   declare '@': string
-  declare log: Log;
-  declare [':version']?: number
-  declare private [_root_]: TRoot
-  declare private [_parent_]: Unit<TRoot> | null // Parent reference for not-yet-attached units
-  declare private [_disposers_]: Set<() => void>
-
-  static get [epos.symbols.stateModelStrict]() {
-    return true
-  }
+  declare log: ReturnType<typeof createLog>;
+  declare [':version']?: number;
+  declare [_root_]?: TRoot;
+  declare [_parent_]?: Unit<TRoot> | null; // Parent reference for a not-yet-attached units
+  declare [_attached_]?: boolean;
+  declare [_disposers_]?: Set<() => void>;
+  declare [_ancestors_]?: Map<Cls, unknown>;
+  declare [_pendingAttachFns_]?: (() => void)[]
 
   constructor(parent: Unit<TRoot> | null) {
-    // Define parent for not-yet-attached units
-    Reflect.defineProperty(this, _parent_, { get: () => parent })
+    this[_parent_] = parent
+    const versions = getVersions(this)
+    if (versions.length > 0) this[':version'] = versions.at(-1)!
   }
 
-  // ---------------------------------------------------------------------------
-  // INIT
-  // ---------------------------------------------------------------------------
-
-  [epos.symbols.stateModelInit]() {
-    const _this = this as any
-    const Unit = this.constructor
-    const descriptors: Descriptors = Object.getOwnPropertyDescriptors(Unit.prototype)
-    const keys = Reflect.ownKeys(descriptors)
-
-    // Setup disposers container
-    const disposers = new Set<() => void>()
-    Reflect.defineProperty(this, _disposers_, { get: () => disposers })
-
-    // Bind all methods
-    for (const key of keys) {
-      if (key === 'constructor') continue
-      const descriptor = descriptors[key]
-      if (!descriptor) continue
-      if (descriptor.get || descriptor.set) continue
-      if (typeof descriptor.value !== 'function') continue
-      _this[key] = descriptor.value.bind(this)
-    }
+  /**
+   * Lifecycle method called when the unit is attached to the state tree.
+   */
+  [epos.state.ATTACH]() {
+    // Setup logger
+    setProperty(this, 'log', createLog(this['@']))
 
-    // Create components out of `View` methods
-    for (const key of keys) {
-      if (typeof key === 'symbol') continue
-      if (!key.endsWith('View')) continue
-      const descriptor = descriptors[key]
-      if (!descriptor) continue
-      if (descriptor.get || descriptor.set) continue
-      if (typeof _this[key] !== 'function') continue
-      _this[key] = epos.component(_this[key] as FC)
-      _this[key].displayName = `${this['@']}.${key}`
-    }
+    // Apply versioner
+    epos.state.transaction(() => {
+      const versioner = getVersioner(this)
+      const versions = getVersions(this)
+      for (const version of versions) {
+        if (is.number(this[':version']) && this[':version'] >= version) continue
+        const versionFn = versioner[version]
+        if (!is.function(versionFn)) continue
+        versionFn.call(this, this)
+        this[':version'] = version
+      }
+    })
 
-    // Define log method
-    const log = createLog(this['@'])
-    Reflect.defineProperty(this, 'log', { get: () => log })
+    // Prepare methods:
+    // - Create components for methods ending with `View`
+    // - Bind all other methods to the unit instance
+    for (const prototype of getPrototypes(this)) {
+      const descriptors = Object.getOwnPropertyDescriptors(prototype)
 
-    // Call init method
-    if (typeof _this.init === 'function') _this.init()
-  }
+      for (const [key, descriptor] of Object.entries(descriptors)) {
+        if (key === 'constructor') continue
+        if (this.hasOwnProperty(key)) continue
 
-  // ---------------------------------------------------------------------------
-  // DISPOSE
-  // ---------------------------------------------------------------------------
+        if (descriptor.get || descriptor.set) continue
+        if (!is.function(descriptor.value)) continue
+        const fn = descriptor.value.bind(this)
 
-  [epos.symbols.stateModelDispose]() {
-    const _this = this as any
+        if (key.endsWith('View')) {
+          let Component = epos.component(fn)
+          Component.displayName = `${this.constructor.name}.${key}`
+          setProperty(this, key, Component)
+        } else {
+          setProperty(this, key, fn)
+        }
+      }
+    }
 
-    // Call disposers
-    this[_disposers_].forEach(disposer => disposer())
-    this[_disposers_].clear()
+    // Setup state
+    const stateDescriptor = Reflect.getOwnPropertyDescriptor(this.constructor.prototype, 'state')
+    if (stateDescriptor && stateDescriptor.get) {
+      const state = stateDescriptor.get.call(this)
+      setProperty(this, 'state', epos.libs.mobx.observable.object(state, {}, { deep: false }))
+    }
 
-    // Call dispose method
-    if (typeof _this.dispose === 'function') _this.dispose()
-  }
+    // Process attach queue.
+    // We do not execute `attach` methods immediately, but rather queue them
+    // on the highest unattached ancestor. This way we ensure that `attach`
+    // methods are called after all versioners have been applied in the entire subtree.
+    const attach = Reflect.get(this, 'attach')
+    if (is.function(attach)) {
+      const unattachedRoot = findUnattachedRoot(this)
+      if (!unattachedRoot) throw this.never()
 
-  // ---------------------------------------------------------------------------
-  // VERSIONER
-  // ---------------------------------------------------------------------------
+      ensureProperty(unattachedRoot, _pendingAttachFns_, () => [])
+      unattachedRoot[_pendingAttachFns_].push(() => attach())
 
-  static get [epos.symbols.stateModelVersioner]() {
-    if (!('versioner' in this)) return null
-    return this.versioner
+      if (this[_pendingAttachFns_]) {
+        this[_pendingAttachFns_].forEach(attach => attach())
+        delete this[_pendingAttachFns_]
+      }
+    }
+
+    // Mark as attached
+    setProperty(this, _attached_, true)
   }
 
-  // ---------------------------------------------------------------------------
-  // ROOT
-  // ---------------------------------------------------------------------------
+  /**
+   * Lifecycle method called when the unit is detached from the state tree.
+   */
+  [epos.state.DETACH]() {
+    // 1. Run disposers
+    if (this[_disposers_]) {
+      this[_disposers_].forEach(disposer => disposer())
+      this[_disposers_].clear()
+    }
+
+    // 2. Call detach method
+    const detach = Reflect.get(this, 'detach')
+    if (is.function(detach)) detach()
 
+    // 3. Clean up internal properties
+    delete this[_root_]
+    delete this[_attached_]
+    delete this[_ancestors_]
+    delete this[_disposers_]
+  }
+
+  /**
+   * Gets the root unit of the current unit's tree.
+   * The result is cached for subsequent calls.
+   */
   get $() {
-    this[_root_] ??= findRoot(this) as TRoot
+    ensureProperty(this, _root_, () => findRoot(this))
     return this[_root_]
   }
 
-  // ---------------------------------------------------------------------------
-  // METHODS
-  // ---------------------------------------------------------------------------
+  /**
+   * Finds the closest ancestor unit of a given type.
+   * The result is cached for subsequent calls.
+   */
+  closest<T extends Unit>(Ancestor: Cls<T>) {
+    // Has cached value? -> Return it
+    ensureProperty(this, _ancestors_, () => new Map())
+    if (this[_ancestors_].has(Ancestor)) return this[_ancestors_].get(Ancestor) as T
 
-  closest<T extends Unit>(Ancestor: Cls<T>): T | null {
-    let cursor: unknown = getParent(this)
+    // Find the closest ancestor and cache it
+    let cursor: Node<TRoot> | null = this
     while (cursor) {
-      if (cursor instanceof Ancestor) return cursor
+      if (cursor instanceof Ancestor) {
+        this[_ancestors_].set(Ancestor, cursor)
+        return cursor
+      }
       cursor = getParent(cursor)
     }
+
     return null
   }
 
+  /**
+   * A wrapper around MobX's `autorun` that automatically disposes
+   * the reaction when the unit is detached.
+   */
   autorun(...args: Parameters<typeof epos.libs.mobx.autorun>) {
     const disposer = epos.libs.mobx.autorun(...args)
+    ensureProperty(this, _disposers_, () => new Set())
     this[_disposers_].add(disposer)
     return disposer
   }
 
+  /**
+   * A wrapper around MobX's `reaction` that automatically disposes
+   * the reaction when the unit is detached.
+   */
   reaction(...args: Parameters<typeof epos.libs.mobx.reaction>) {
     const disposer = epos.libs.mobx.reaction(...args)
+    ensureProperty(this, _disposers_, () => new Set())
     this[_disposers_].add(disposer)
     return disposer
   }
 
+  /**
+   * A wrapper around `setTimeout` that automatically clears the timeout
+   * when the unit is detached.
+   */
   setTimeout(...args: Parameters<typeof self.setTimeout>) {
     const id = self.setTimeout(...args)
+    ensureProperty(this, _disposers_, () => new Set())
     this[_disposers_].add(() => self.clearTimeout(id))
     return id
   }
 
+  /**
+   * A wrapper around `setInterval` that automatically clears the interval
+   * when the unit is detached.
+   */
   setInterval(...args: Parameters<typeof self.setInterval>) {
     const id = self.setInterval(...args)
+    ensureProperty(this, _disposers_, () => new Set())
     this[_disposers_].add(() => self.clearInterval(id))
     return id
   }
 
+  /**
+   * Creates an error for an unreachable code path.
+   */
   never(message = 'This should never happen') {
-    const error = new Error(`[${this['@']}] ${message}`)
+    const details = message ? `: ${message}` : ''
+    const error = new Error(`[${this.constructor.name}] This should never happen${details}`)
     Error.captureStackTrace(error, this.never)
-    throw error
+    return error
   }
 }
 
@@ -150,18 +212,91 @@ export class Unit<TRoot = unknown> {
 // HELPERS
 // ---------------------------------------------------------------------------
 
-function getParent(child: any) {
-  return child[_parent_] ?? child[epos.symbols.stateParent]
+/**
+ * Defines a configurable property on an object.
+ */
+function setProperty(object: object, key: PropertyKey, value: unknown) {
+  Reflect.defineProperty(object, key, {
+    configurable: true,
+    get: () => value,
+    set: v => (value = v),
+  })
+}
+
+/**
+ * Ensures a property exists on an object, initializing it if it doesn't.
+ */
+function ensureProperty<T extends object, K extends PropertyKey, V>(
+  object: T,
+  key: K,
+  getInitialValue: () => V,
+): asserts object is T & { [key in K]: V } {
+  if (key in object) return
+  const value = getInitialValue()
+  Reflect.defineProperty(object, key, { configurable: true, get: () => value })
+}
+
+/**
+ * Gets all prototypes of an object up to `Object.prototype`.
+ */
+function getPrototypes(object: object): object[] {
+  const prototype = Reflect.getPrototypeOf(object)
+  if (!prototype || prototype === Object.prototype) return []
+  return [prototype, ...getPrototypes(prototype)]
 }
 
-function findRoot(unit: Unit) {
-  let root = unit
-  let cursor: any = unit
+/**
+ * Finds the root `Unit` in the hierarchy for a given unit.
+ */
+function findRoot<T>(unit: Unit<T>) {
+  let root: Unit<T> | null = null
+  let cursor: Node<T> | null = unit
 
   while (cursor) {
     if (cursor instanceof Unit) root = cursor
     cursor = getParent(cursor)
   }
 
-  return root
+  return root as T
+}
+
+/**
+ * Finds the highest unattached `Unit` in the hierarchy for a given unit.
+ */
+function findUnattachedRoot<T>(unit: Unit<T>) {
+  let unattachedRoot: Unit<T> | null = null
+  let cursor: Node<T> | null = unit
+
+  while (cursor) {
+    if (cursor instanceof Unit && !cursor[_attached_]) unattachedRoot = cursor
+    cursor = getParent(cursor)
+  }
+
+  return unattachedRoot
+}
+
+/**
+ * Gets the parent of a node, which can be a `Unit`, an object, or an array.
+ */
+function getParent<T>(node: Node<T>) {
+  const parent: Node<T> | null = Reflect.get(node, _parent_) ?? Reflect.get(node, epos.state.PARENT) ?? null
+  return parent
+}
+
+/**
+ * Gets the versioner object from a unit's constructor.
+ */
+function getVersioner<T>(unit: Unit<T>) {
+  const versioner: unknown = Reflect.get(unit.constructor, 'versioner')
+  if (!is.object(versioner)) return {}
+  return versioner
+}
+
+/**
+ * Gets a sorted list of numeric version keys from a unit's versioner.
+ */
+function getVersions<T>(unit: Unit<T>) {
+  const versioner = getVersioner(unit)
+  const numericKeys = Object.keys(versioner).filter(key => is.numeric(key))
+  return numericKeys.map(Number).sort((v1, v2) => v1 - v2)
 }