ivue 2.1.0 → 2.2.0

package/dist/Static.d.ts

@@ -6,6 +6,18 @@
  * retain as callbacks (routers, watchers, command handlers) while the
  * selected `Class` slot remains replaceable by a kernel/plugin.
  *
+ * Get-only static accessors whose name starts with `$` become
+ * compute-once-per-receiver caches: the getter body runs on first read
+ * through a given class, its (shallowly frozen) result is stored under a
+ * symbol OWN property of that receiver, and later reads return the stored
+ * value. The `Object.hasOwn` guard never walks the prototype chain, so a
+ * parent's cache can never shadow a subclass — each class in a hierarchy
+ * derives through its own overrides on its own first read, in ANY read
+ * order. The `$` prefix IS the API: a static getter that must stay live
+ * (a knob for subclasses to pinch, a fresh-per-read value) must not use
+ * it. Cached values are frozen shallowly — cache-and-freeze or
+ * return-fresh, never cache-mutable.
+ *
  * This is the namespace pattern's backend adapter: canonical namespace +
  * mutable `Class` slot + late reads, for STATELESS capability classes (a
  * function bag). Never wrap stateful/reactive instance classes with it — use

package/dist/extras.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"}),exports.Static=function(o){const r=class extends o{},c=new Set;for(let e=o;e!==Function.prototype;e=Object.getPrototypeOf(e))for(const t of Reflect.ownKeys(e)){if(c.has(t))continue;c.add(t);const n=Object.getOwnPropertyDescriptor(e,t);if(typeof n.value!="function")continue;const u=n.value;Object.defineProperty(r,t,{configurable:!0,enumerable:n.enumerable,get(){const i=u.bind(this);return Object.defineProperty(this,t,{...n,value:i}),i}})}return r};
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"}),exports.Static=function(i){const o=class extends i{},s=new Set;for(let n=i;n!==Function.prototype;n=Object.getPrototypeOf(n))for(const e of Reflect.ownKeys(n)){if(s.has(e))continue;s.add(e);const t=Object.getOwnPropertyDescriptor(n,e);if(typeof t.value=="function"){const c=t.value;Object.defineProperty(o,e,{configurable:!0,enumerable:t.enumerable,get(){const r=c.bind(this);return Object.defineProperty(this,e,{...t,value:r}),r}})}else if(t.get&&!t.set&&typeof e=="string"&&e.startsWith("$")){const c=t.get,r=Symbol.for(`ivue.staticCache.${e}`);Object.defineProperty(o,e,{configurable:!0,enumerable:t.enumerable,get(){return Object.hasOwn(this,r)||Object.defineProperty(this,r,{configurable:!0,value:Object.freeze(c.call(this))}),this[r]}})}}return o};

package/dist/extras.es.js

@@ -1,22 +1,27 @@
-function f(o) {
-  const r = class extends o {
-  }, c = /* @__PURE__ */ new Set();
-  for (let e = o; e !== Function.prototype; e = Object.getPrototypeOf(e))
-    for (const t of Reflect.ownKeys(e)) {
-      if (c.has(t))
+function a(i) {
+  const o = class extends i {
+  }, s = /* @__PURE__ */ new Set();
+  for (let r = i; r !== Function.prototype; r = Object.getPrototypeOf(r))
+    for (const e of Reflect.ownKeys(r)) {
+      if (s.has(e))
         continue;
-      c.add(t);
-      const n = Object.getOwnPropertyDescriptor(e, t);
-      if (typeof n.value != "function")
-        continue;
-      const s = n.value;
-      Object.defineProperty(r, t, { configurable: !0, enumerable: n.enumerable, get() {
-        const i = s.bind(this);
-        return Object.defineProperty(this, t, { ...n, value: i }), i;
-      } });
+      s.add(e);
+      const t = Object.getOwnPropertyDescriptor(r, e);
+      if (typeof t.value == "function") {
+        const c = t.value;
+        Object.defineProperty(o, e, { configurable: !0, enumerable: t.enumerable, get() {
+          const n = c.bind(this);
+          return Object.defineProperty(this, e, { ...t, value: n }), n;
+        } });
+      } else if (t.get && !t.set && typeof e == "string" && e.startsWith("$")) {
+        const c = t.get, n = Symbol.for(`ivue.staticCache.${e}`);
+        Object.defineProperty(o, e, { configurable: !0, enumerable: t.enumerable, get() {
+          return Object.hasOwn(this, n) || Object.defineProperty(this, n, { configurable: !0, value: Object.freeze(c.call(this)) }), this[n];
+        } });
+      }
     }
-  return r;
+  return o;
 }
 export {
-  f as Static
+  a as Static
 };

package/lib/Static.ts

@@ -6,6 +6,18 @@
  * retain as callbacks (routers, watchers, command handlers) while the
  * selected `Class` slot remains replaceable by a kernel/plugin.
  *
+ * Get-only static accessors whose name starts with `$` become
+ * compute-once-per-receiver caches: the getter body runs on first read
+ * through a given class, its (shallowly frozen) result is stored under a
+ * symbol OWN property of that receiver, and later reads return the stored
+ * value. The `Object.hasOwn` guard never walks the prototype chain, so a
+ * parent's cache can never shadow a subclass — each class in a hierarchy
+ * derives through its own overrides on its own first read, in ANY read
+ * order. The `$` prefix IS the API: a static getter that must stay live
+ * (a knob for subclasses to pinch, a fresh-per-read value) must not use
+ * it. Cached values are frozen shallowly — cache-and-freeze or
+ * return-fresh, never cache-mutable.
+ *
  * This is the namespace pattern's backend adapter: canonical namespace +
  * mutable `Class` slot + late reads, for STATELESS capability classes (a
  * function bag). Never wrap stateful/reactive instance classes with it — use
@@ -31,18 +43,42 @@ export function Static<Class extends ClassConstructor>(targetClass: Class): Clas
       visitedKeys.add(key);
 
       const descriptor = Object.getOwnPropertyDescriptor(currentClass, key)!;
-      if (typeof descriptor.value !== 'function') continue;
-      const method = descriptor.value;
 
-      Object.defineProperty(SelectedClass, key, {
-        configurable: true,
-        enumerable: descriptor.enumerable,
-        get(this: ClassConstructor) {
-          const boundMethod = method.bind(this);
-          Object.defineProperty(this, key, { ...descriptor, value: boundMethod });
-          return boundMethod;
-        },
-      });
+      if (typeof descriptor.value === 'function') {
+        const method = descriptor.value;
+
+        Object.defineProperty(SelectedClass, key, {
+          configurable: true,
+          enumerable: descriptor.enumerable,
+          get(this: ClassConstructor) {
+            const boundMethod = method.bind(this);
+            Object.defineProperty(this, key, { ...descriptor, value: boundMethod });
+            return boundMethod;
+          },
+        });
+      } else if (
+        descriptor.get &&
+        !descriptor.set &&
+        typeof key === 'string' &&
+        key.startsWith('$')
+      ) {
+        const getter = descriptor.get;
+        const cacheKey = Symbol.for(`ivue.staticCache.${key}`);
+
+        Object.defineProperty(SelectedClass, key, {
+          configurable: true,
+          enumerable: descriptor.enumerable,
+          get(this: any) {
+            if (!Object.hasOwn(this, cacheKey)) {
+              Object.defineProperty(this, cacheKey, {
+                configurable: true,
+                value: Object.freeze(getter.call(this)),
+              });
+            }
+            return this[cacheKey];
+          },
+        });
+      }
     }
   }
 

package/lib/__tests__/Static.vitest.spec.ts

@@ -97,3 +97,184 @@ describe('Static', () => {
     expect(render()).toBe('HEADER|body');
   });
 });
+
+describe('Static $-cached getters', () => {
+  it('computes a $-getter exactly once per receiver', () => {
+    let computeRuns = 0;
+
+    class $Palette {
+      static get $tokens() {
+        computeRuns++;
+        return { accent: 'cyan' };
+      }
+    }
+
+    const Palette = Static($Palette);
+    const firstRead = Palette.$tokens;
+
+    expect(Palette.$tokens).toBe(firstRead); // same object, cached
+    expect(Palette.$tokens.accent).toBe('cyan');
+    expect(computeRuns).toBe(1);
+  });
+
+  it('is order-correct: parent read first, child override still wins', () => {
+    class $Momentum {
+      static get friction() {
+        return 2; // a live knob — subclasses pinch it
+      }
+      static get $atRest() {
+        return { velocity: 0, threshold: this.friction * 10 };
+      }
+    }
+
+    const Momentum = Static($Momentum);
+    class TunedMomentum extends Momentum {
+      static override get friction() {
+        return 7;
+      }
+    }
+
+    // PARENT reads first — the hand-rolled self-replacement idiom
+    // caches on the parent here and silently shadows the child forever
+    expect(Momentum.$atRest.threshold).toBe(20);
+    expect(TunedMomentum.$atRest.threshold).toBe(70); // child derives itself
+    expect(TunedMomentum.$atRest).not.toBe(Momentum.$atRest);
+  });
+
+  it('is order-correct: child read first, parent unaffected', () => {
+    let computeRuns = 0;
+
+    class $Momentum {
+      static get friction() {
+        return 2;
+      }
+      static get $atRest() {
+        computeRuns++;
+        return { threshold: this.friction * 10 };
+      }
+    }
+
+    const Momentum = Static($Momentum);
+    class TunedMomentum extends Momentum {
+      static override get friction() {
+        return 7;
+      }
+    }
+
+    expect(TunedMomentum.$atRest.threshold).toBe(70); // CHILD reads first
+    expect(Momentum.$atRest.threshold).toBe(20);
+    expect(computeRuns).toBe(2); // once per receiver, never shared
+  });
+
+  it('freezes cached values — mutation throws instead of corrupting', () => {
+    class $Config {
+      static get $defaults() {
+        return { width: 80 };
+      }
+    }
+
+    const Config = Static($Config);
+    const defaults = Config.$defaults;
+
+    expect(Object.isFrozen(defaults)).toBe(true);
+    expect(() => {
+      (defaults as any).width = 120;
+    }).toThrow(TypeError);
+    expect(Config.$defaults.width).toBe(80);
+  });
+
+  it('caches primitive results too', () => {
+    let computeRuns = 0;
+
+    class $Layout {
+      static get $gutterWidth() {
+        computeRuns++;
+        return 4;
+      }
+    }
+
+    const Layout = Static($Layout);
+
+    expect(Layout.$gutterWidth).toBe(4);
+    expect(Layout.$gutterWidth).toBe(4);
+    expect(computeRuns).toBe(1);
+  });
+
+  it('leaves non-$ getters live — knobs re-read every time', () => {
+    let reads = 0;
+
+    class $Driver {
+      static get retainedLimit() {
+        reads++;
+        return 96;
+      }
+    }
+
+    const Driver = Static($Driver);
+    Driver.retainedLimit;
+    Driver.retainedLimit;
+
+    expect(reads).toBe(2); // no caching without the $ prefix
+  });
+
+  it('leaves accessor pairs with a setter untouched', () => {
+    class $Tunable {
+      static backing = 1;
+      static get $level() {
+        return this.backing;
+      }
+      static set $level(value: number) {
+        this.backing = value;
+      }
+    }
+
+    const Tunable = Static($Tunable);
+    Tunable.$level = 5;
+
+    expect(Tunable.$level).toBe(5); // still the live pair, not a cache
+    Tunable.$level = 9;
+    expect(Tunable.$level).toBe(9);
+  });
+
+  it('a subclass overriding the $-getter itself wins', () => {
+    class $Theme {
+      static get $accent() {
+        return 'blue';
+      }
+    }
+
+    const Theme = Static($Theme);
+    expect(Theme.$accent).toBe('blue');
+
+    class DarkTheme extends Theme {
+      static override get $accent() {
+        return 'violet';
+      }
+    }
+
+    // the subclass's own getter descriptor shadows the caching wrapper
+    expect(DarkTheme.$accent).toBe('violet');
+    expect(Theme.$accent).toBe('blue');
+  });
+
+  it('walks the raw inheritance chain — ancestor $-getters cache per receiver', () => {
+    class $Base {
+      static get scale() {
+        return 1;
+      }
+      static get $metrics() {
+        return { unit: this.scale * 8 };
+      }
+    }
+    class $Wide extends $Base {
+      static override get scale() {
+        return 3;
+      }
+    }
+
+    const Wide = Static($Wide);
+
+    expect(Wide.$metrics.unit).toBe(24); // derived through the override
+    expect(Wide.$metrics).toBe(Wide.$metrics); // and cached
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ivue",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Infinite Vue – Class Based Architecture for Vue 3",
   "type": "module",
   "exports": {
@@ -40,6 +40,7 @@
     "build:docs": "npm run sync:examples && npm --prefix docs_v2 run build",
     "render:og": "node docs_v2/scripts/brand-image-generator.mjs og",
     "render:form-header": "node docs_v2/scripts/brand-image-generator.mjs form-header",
+    "render:banner": "node docs_v2/scripts/brand-image-generator.mjs blog",
     "preview:demo": "npm run build:demo && vite preview demo --host",
     "preview:docs": "npm --prefix docs_v2 run preview",
     "release": "npm run build && npm publish",