ivue 2.0.0 → 2.2.0

package/dist/Static.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `Static()` — the static-side sibling of `Reactive()`.
+ *
+ * Lazily binds every visible static method of a capability class without
+ * touching the raw class, so methods stay referentially stable and safe to
+ * 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
+ * `Reactive()` for those; `Static()` operates on the single class object and
+ * has no instance dimension.
+ *
+ * Ships from `ivue/extras` (not the reactive core) so the primary `ivue`
+ * entry stays minimal.
+ */
+export declare type ClassConstructor = new (...arguments_: any[]) => any;
+export declare function Static<Class extends ClassConstructor>(targetClass: Class): Class;

package/dist/extras.cjs

@@ -0,0 +1 @@
+"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.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `ivue/extras` — the ivue toolkit beyond the reactive core.
+ *
+ * Kept out of the primary `ivue` entry so that entry stays minimal (the
+ * 1.1kb reactive engine). Import these explicitly:
+ *
+ *   import { Static } from 'ivue/extras';
+ */
+export { Static, type ClassConstructor } from './Static';

package/dist/extras.es.js

@@ -0,0 +1,27 @@
+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;
+      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 o;
+}
+export {
+  a as Static
+};

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("vue"),g=Object.hasOwn,y=Object.getPrototypeOf,w=Object.getOwnPropertyDescriptor,m=Object.getOwnPropertyNames,a=Object.defineProperty,d=Object.prototype,b=Symbol.for("ivue.raw"),p=Symbol.for("ivue.scope"),h=Symbol.for("ivue.processed");function s(e){const r=l.toRaw(e);if(r!==e)return r[b]??(r[b]=r);const n=e[b];return n?n===e?n:l.toRaw(n):e[b]=e}function O(e,r,n,o){a(e,r,{configurable:!0,enumerable:!1,get(){const t=s(this);return t[n]??(t[n]=o.bind(t))},set(t){s(this)[n]=t}})}function S(e,r,n,o,t){const f=r[0]==="$";a(e,r,{configurable:!0,enumerable:!1,get:function(){const c=s(this);if(n in c)return c[n];const i=o.call(c);return f?(c[n]=i,i):(l.isRef(i)?c[n]=i:a(e,r,{configurable:!0,enumerable:!1,get(){return o.call(s(this))},set:t?function(u){return t.call(s(this),u)}:void 0}),i)},set:t?function(c){return t.call(s(this),c)}:void 0})}const v=e=>{var r;return typeof e=="function"&&!!e.prototype&&!((r=w(e,"prototype"))!=null&&r.writable)};exports.Reactive=function(e){const r=[];let n=e.prototype;for(;n&&n!==d;)r.push(n),n=y(n);r.reverse();for(const o of r){if(g(o,h))continue;const t=m(o),f=[];for(const c of t){if(c==="constructor")continue;const i=w(o,c);if(typeof i.value=="function"){const u=Symbol(c);f.push(u),O(o,c,u,i.value)}else if(i.get){const u=Symbol(c);f.push(u),S(o,c,u,i.get,i.set)}}a(o,h,{value:f})}return g(e.prototype,"$stopEffects")||(a(e.prototype,"$watch",{enumerable:!1,configurable:!0,writable:!0,value:function(...o){const t=s(this);return(t[p]??(t[p]=l.effectScope(!0))).run(()=>l.watch(...o))}}),a(e.prototype,"$watchEffect",{enumerable:!1,configurable:!0,writable:!0,value:function(...o){const t=s(this);return(t[p]??(t[p]=l.effectScope(!0))).run(()=>l.watchEffect(...o))}}),a(e.prototype,"$stopEffects",{enumerable:!1,configurable:!0,writable:!0,value:function(){const o=s(this);try{const t=o[p];t&&t.stop()}finally{delete o[p];let t=y(o);for(;t&&t!==d;){const f=t[h];if(f)for(const c of f)delete o[c];t=y(t)}}}})),e},exports.isClass=v,exports.propsWithDefaults=(e,r,n)=>{const o={};for(const t in r){const f=e==null?void 0:e[t],c=r[t];o[t]={...c},c.required||f===void 0||(typeof f=="object"&&f!==null?o[t].default=()=>n?n(f):structuredClone(f):v(f)?o[t].default=()=>f:o[t].default=f)}return o};

package/lib/Static.ts

@@ -0,0 +1,86 @@
+/**
+ * `Static()` — the static-side sibling of `Reactive()`.
+ *
+ * Lazily binds every visible static method of a capability class without
+ * touching the raw class, so methods stay referentially stable and safe to
+ * 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
+ * `Reactive()` for those; `Static()` operates on the single class object and
+ * has no instance dimension.
+ *
+ * Ships from `ivue/extras` (not the reactive core) so the primary `ivue`
+ * entry stays minimal.
+ */
+export type ClassConstructor = new (...arguments_: any[]) => any;
+
+export function Static<Class extends ClassConstructor>(targetClass: Class): Class {
+  const SelectedClass = class extends targetClass {};
+  const visitedKeys = new Set<PropertyKey>();
+
+  for (
+    let currentClass: ClassConstructor = targetClass;
+    currentClass !== Function.prototype;
+    currentClass = Object.getPrototypeOf(currentClass)
+  ) {
+    for (const key of Reflect.ownKeys(currentClass)) {
+      if (visitedKeys.has(key)) continue;
+      visitedKeys.add(key);
+
+      const descriptor = Object.getOwnPropertyDescriptor(currentClass, key)!;
+
+      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];
+          },
+        });
+      }
+    }
+  }
+
+  return SelectedClass as Class;
+}

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

@@ -0,0 +1,280 @@
+import { describe, expect, it } from 'vitest';
+import { Static } from '../Static';
+
+describe('Static', () => {
+  it('returns a subclass and leaves the raw class untouched', () => {
+    class $Mailer {
+      static send(message: string) {
+        return `sent:${message}`;
+      }
+    }
+
+    const Mailer = Static($Mailer);
+
+    expect(Mailer).not.toBe($Mailer);
+    expect(Object.getPrototypeOf(Mailer)).toBe($Mailer);
+    // the raw class keeps its plain data-property descriptor
+    const rawDescriptor = Object.getOwnPropertyDescriptor($Mailer, 'send')!;
+    expect(typeof rawDescriptor.value).toBe('function');
+    expect(rawDescriptor.get).toBeUndefined();
+  });
+
+  it('binds methods lazily with stable identity, safe to detach', () => {
+    class $Counter {
+      static total = 0;
+      static bump() {
+        this.total++;
+        return this.total;
+      }
+    }
+
+    const Counter = Static($Counter);
+    const firstRead = Counter.bump;
+
+    expect(Counter.bump).toBe(firstRead); // cached after first access
+    const detached = Counter.bump;
+    expect(detached()).toBe(1); // `this` survives detachment
+    expect(Counter.total).toBe(1);
+  });
+
+  it('walks the static inheritance chain; child overrides win', () => {
+    class $Base {
+      static describe() {
+        return 'base';
+      }
+      static inheritedOnly() {
+        return 'inherited';
+      }
+    }
+    class $Child extends $Base {
+      static describe() {
+        return 'child';
+      }
+    }
+
+    const Child = Static($Child);
+    const describe = Child.describe;
+    const inheritedOnly = Child.inheritedOnly;
+
+    expect(describe()).toBe('child');
+    expect(inheritedOnly()).toBe('inherited');
+  });
+
+  it('skips non-function statics and preserves enumerability', () => {
+    class $Config {
+      static baseUrl = 'https://example.test';
+      static resolve(path: string) {
+        return this.baseUrl + path;
+      }
+    }
+
+    const Config = Static($Config);
+
+    expect(Config.baseUrl).toBe('https://example.test');
+    // class static methods are non-enumerable by construction — the lazy
+    // accessor and the materialized bound method must both preserve that
+    const before = Object.getOwnPropertyDescriptor(Config, 'resolve')!;
+    expect(before.enumerable).toBe(false);
+    Config.resolve; // materialize the bound method
+    const after = Object.getOwnPropertyDescriptor(Config, 'resolve')!;
+    expect(after.enumerable).toBe(false);
+    expect(Config.resolve('/path')).toBe('https://example.test/path');
+  });
+
+  it('binds `this` to the wrapped class, so statics compose', () => {
+    class $Report {
+      static header() {
+        return 'HEADER';
+      }
+      static render() {
+        return `${this.header()}|body`;
+      }
+    }
+
+    const Report = Static($Report);
+    const render = Report.render;
+
+    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/lib/__tests__/coverage-completion.vitest.spec.ts

@@ -3,6 +3,7 @@
  */
 import { describe, expect, it } from 'vitest';
 import * as packageEntry from '../index';
+import * as extrasEntry from '../extras';
 import { Kernel, kernel } from '../kernel';
 
 describe('package entry (index.ts)', () => {
@@ -11,6 +12,12 @@ describe('package entry (index.ts)', () => {
   });
 });
 
+describe('extras entry (extras.ts)', () => {
+  it('re-exports the toolkit beyond the core', () => {
+    expect(typeof extrasEntry.Static).toBe('function');
+  });
+});
+
 describe('Kernel', () => {
   it('sets, gets, falls back, clears', () => {
     const container = new Kernel();

package/lib/extras.ts

@@ -0,0 +1,9 @@
+/**
+ * `ivue/extras` — the ivue toolkit beyond the reactive core.
+ *
+ * Kept out of the primary `ivue` entry so that entry stays minimal (the
+ * 1.1kb reactive engine). Import these explicitly:
+ *
+ *   import { Static } from 'ivue/extras';
+ */
+export { Static, type ClassConstructor } from './Static';

package/package.json

@@ -1,17 +1,22 @@
 {
   "name": "ivue",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Infinite Vue – Class Based Architecture for Vue 3",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.es.js",
-      "require": "./dist/index.umd.js"
+      "require": "./dist/index.cjs"
+    },
+    "./extras": {
+      "types": "./dist/extras.d.ts",
+      "import": "./dist/extras.es.js",
+      "require": "./dist/extras.cjs"
     },
     "./package.json": "./package.json"
   },
-  "main": "./dist/index.umd.js",
+  "main": "./dist/index.cjs",
   "module": "./dist/index.es.js",
   "types": "./dist/index.d.ts",
   "scripts": {
@@ -35,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",

package/dist/index.umd.js

@@ -1 +0,0 @@
-(function(l,f){typeof exports=="object"&&typeof module<"u"?f(exports,require("vue")):typeof define=="function"&&define.amd?define(["exports","vue"],f):f((l=typeof globalThis<"u"?globalThis:l||self).ivue={},l.Vue)})(this,function(l,f){"use strict";const g=Object.hasOwn,d=Object.getPrototypeOf,v=Object.getOwnPropertyDescriptor,O=Object.getOwnPropertyNames,a=Object.defineProperty,m=Object.prototype,y=Symbol.for("ivue.raw"),b=Symbol.for("ivue.scope"),h=Symbol.for("ivue.processed");function s(e){const r=f.toRaw(e);if(r!==e)return r[y]??(r[y]=r);const n=e[y];return n?n===e?n:f.toRaw(n):e[y]=e}function j(e,r,n,o){a(e,r,{configurable:!0,enumerable:!1,get(){const t=s(this);return t[n]??(t[n]=o.bind(t))},set(t){s(this)[n]=t}})}function S(e,r,n,o,t){const u=r[0]==="$";a(e,r,{configurable:!0,enumerable:!1,get:function(){const c=s(this);if(n in c)return c[n];const i=o.call(c);return u?(c[n]=i,i):(f.isRef(i)?c[n]=i:a(e,r,{configurable:!0,enumerable:!1,get(){return o.call(s(this))},set:t?function(p){return t.call(s(this),p)}:void 0}),i)},set:t?function(c){return t.call(s(this),c)}:void 0})}const w=e=>{var r;return typeof e=="function"&&!!e.prototype&&!((r=v(e,"prototype"))!=null&&r.writable)};l.Reactive=function(e){const r=[];let n=e.prototype;for(;n&&n!==m;)r.push(n),n=d(n);r.reverse();for(const o of r){if(g(o,h))continue;const t=O(o),u=[];for(const c of t){if(c==="constructor")continue;const i=v(o,c);if(typeof i.value=="function"){const p=Symbol(c);u.push(p),j(o,c,p,i.value)}else if(i.get){const p=Symbol(c);u.push(p),S(o,c,p,i.get,i.set)}}a(o,h,{value:u})}return g(e.prototype,"$stopEffects")||(a(e.prototype,"$watch",{enumerable:!1,configurable:!0,writable:!0,value:function(...o){const t=s(this);return(t[b]??(t[b]=f.effectScope(!0))).run(()=>f.watch(...o))}}),a(e.prototype,"$watchEffect",{enumerable:!1,configurable:!0,writable:!0,value:function(...o){const t=s(this);return(t[b]??(t[b]=f.effectScope(!0))).run(()=>f.watchEffect(...o))}}),a(e.prototype,"$stopEffects",{enumerable:!1,configurable:!0,writable:!0,value:function(){const o=s(this);try{const t=o[b];t&&t.stop()}finally{delete o[b];let t=d(o);for(;t&&t!==m;){const u=t[h];if(u)for(const c of u)delete o[c];t=d(t)}}}})),e},l.isClass=w,l.propsWithDefaults=(e,r,n)=>{const o={};for(const t in r){const u=e==null?void 0:e[t],c=r[t];o[t]={...c},c.required||u===void 0||(typeof u=="object"&&u!==null?o[t].default=()=>n?n(u):structuredClone(u):w(u)?o[t].default=()=>u:o[t].default=u)}return o},Object.defineProperty(l,Symbol.toStringTag,{value:"Module"})});