ivue 2.4.0 → 2.6.0

package/lib/Static.ts

@@ -42,6 +42,11 @@ export type ClassConstructor = new (...arguments_: any[]) => any;
 
 const hasOwn = Object.hasOwn;
 
+// Every bind/cache symbol this module ever issues — so a second wrap can
+// recognize an ancestor's runtime residue even for the unregistered
+// symbols that back symbol-keyed methods.
+const issuedCacheKeys = new Set<PropertyKey>();
+
 export function Static<Class extends ClassConstructor>(targetClass: Class): Class {
   const SelectedClass = class extends targetClass {};
   const visitedKeys = new Set<PropertyKey>();
@@ -55,14 +60,38 @@ export function Static<Class extends ClassConstructor>(targetClass: Class): Clas
       if (visitedKeys.has(key)) continue;
       visitedKeys.add(key);
 
+      // An already-wrapped ancestor that has been READ owns its bind/cache
+      // symbol properties. They are runtime residue, not API — re-wrapping
+      // them would install an ancestor-bound function where the child's
+      // own chain lookup expects to bind for itself.
+      if (typeof key === 'symbol' && Symbol.keyFor(key)?.startsWith('ivue.static')) continue;
+      if (issuedCacheKeys.has(key)) continue; // the unregistered symbols backing symbol-keyed methods
+
       const descriptor = Object.getOwnPropertyDescriptor(currentClass, key)!;
 
       if (typeof descriptor.value === 'function') {
+      // HOT-LOOP READY — measured, twice, after two wrong theories. The
+      // bind happens ONCE: the first read defines an own bind-key
+      // property holding the bound function; every later read returns
+      // it. A HOISTED bound method is exactly plain-function speed
+      // (in-browser, 9M calls, fresh-page medians: module fn 31.7ms,
+      // hoisted bound method 30.0ms). The ONLY per-call cost is reading
+      // the method THROUGH the accessor inside the loop (84.6ms same
+      // loop) — so in a million-call loop, destructure the methods once
+      // (`const { method } = X.Class` — a late read of the mutable slot,
+      // so a subclass swap is still honored) and pay the accessor once.
+      // Ordinary call counts never notice any of this.
+      //
+      // Benchmark honestly: a shared bench(fn) harness makes the call
+      // site megamorphic and slows every variant measured after the
+      // first — that artifact once misread bound calls as "48% slower."
+      // Fresh page per variant, dedicated loops.
         const method = descriptor.value;
         const bindKey =
           typeof key === 'string'
             ? Symbol.for(`ivue.staticBound.${key}`)
             : Symbol('ivue.staticBound');
+        issuedCacheKeys.add(bindKey);
 
         Object.defineProperty(SelectedClass, key, {
           configurable: true,
@@ -85,6 +114,7 @@ export function Static<Class extends ClassConstructor>(targetClass: Class): Clas
       ) {
         const getter = descriptor.get;
         const cacheKey = Symbol.for(`ivue.staticCache.${key}`);
+        issuedCacheKeys.add(cacheKey);
 
         Object.defineProperty(SelectedClass, key, {
           configurable: true,

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

@@ -13,10 +13,12 @@ import {
 } from 'vue';
 
 import {
+  clone,
   isClass,
   propsWithDefaults,
   Reactive,
   type ReactiveInstance,
+  definePropTypes,
 } from '../Reactive';
 
 /**
@@ -418,18 +420,18 @@ describe('Reactive()', () => {
         }
       }
       class Mid extends Base {
-        get summary() {
+        override get summary() {
           return computed(() => `(Mid>${super.summary.value})`);
         }
-        get chain() {
+        override get chain() {
           return super.chain + '->Mid';
         }
       }
       class Leaf extends Mid {
-        get summary() {
+        override get summary() {
           return computed(() => `{Leaf>${super.summary.value}}`);
         }
-        get chain() {
+        override get chain() {
           return super.chain + '->Leaf';
         }
       }
@@ -446,7 +448,7 @@ describe('Reactive()', () => {
         }
       }
       class Child extends Base {
-        get val() {
+        override get val() {
           return computed(() => 10 + super.val.value);
         }
       }
@@ -491,13 +493,13 @@ describe('Reactive()', () => {
       }
     }
     class L2 extends L1 {
-      get tag() {
+      override get tag() {
         return computed(() => `L2(${super.tag.value})`);
       }
-      get name() {
+      override get name() {
         return super.name + '>L2';
       }
-      greet() {
+      override greet() {
         return super.greet() + '/L2';
       }
     }
@@ -505,18 +507,18 @@ describe('Reactive()', () => {
       get extra() {
         return ref(5);
       }
-      get tag() {
+      override get tag() {
         return computed(() => `L3[${super.tag.value}]`);
       }
-      get name() {
+      override get name() {
         return super.name + '>L3';
       }
     }
     class L4 extends L3 {
-      get tag() {
+      override get tag() {
         return computed(() => `L4{${super.tag.value}}`);
       }
-      get name() {
+      override get name() {
         return super.name + '>L4';
       }
       // computed in the child aggregating refs declared 3 and 1 levels up
@@ -525,7 +527,7 @@ describe('Reactive()', () => {
           () => (this as any).base.value + (this as any).extra.value,
         );
       }
-      greet() {
+      override greet() {
         return super.greet() + '/L4';
       }
     }
@@ -985,7 +987,7 @@ describe('propsWithDefaults()', () => {
     expect(out.nul.default).toBe(null); // null → else branch, assigned directly
   });
 
-  it('wraps object/array defaults in a factory that structuredClones', () => {
+  it('wraps object/array defaults in a factory that copies their containers', () => {
     const typed = { o: { type: Object }, a: { type: Array } };
     const defaults = { o: { nested: { k: 1 } }, a: [1, 2, 3] };
     const out = propsWithDefaults(defaults, { ...typed }) as Record<
@@ -1021,6 +1023,49 @@ describe('propsWithDefaults()', () => {
     expect(v).toEqual({ k: 1, cloned: true });
   });
 
+  it('isolates default containers while preserving nested constructors, callbacks and opaque objects', () => {
+    class Runner {}
+    class Tuning { gain = 1; }
+    const onChange = () => 1;
+    const tuning = new Tuning();
+    const date = new Date(0);
+    const cache = new Map([['gain', 1]]);
+    const defaults = { options: { limits: { count: 5 }, runner: Runner, onChange, tuning, date, cache } };
+    const props = propsWithDefaults(defaults, { options: { type: Object } }) as Record<string, any>;
+    const first = props.options.default();
+    const second = props.options.default();
+
+    first.limits.count = 2;
+    expect(second.limits.count).toBe(5);
+    expect(defaults.options.limits.count).toBe(5);
+    expect(first.runner).toBe(Runner);
+    expect(first.onChange).toBe(onChange);
+    expect(first.tuning).toBe(tuning);
+    expect(first.date).toBe(date);
+    expect(first.cache).toBe(cache);
+    // The public copier uses the same ownership policy as the props factory.
+    const copied = clone(defaults.options);
+    expect(copied.limits).not.toBe(defaults.options.limits);
+    expect(copied.runner).toBe(Runner);
+  });
+
+  it('accepts structuredClone explicitly for cyclic data and independent built-in objects', () => {
+    const options: { date: Date; cache: Map<string, number>; self?: unknown } = {
+      date: new Date(0), cache: new Map([['gain', 1]]),
+    };
+    options.self = options;
+    const props = propsWithDefaults({ options }, { options: { type: Object } }, structuredClone) as Record<string, any>;
+    const first = props.options.default();
+    const second = props.options.default();
+
+    expect(first.self).toBe(first);
+    expect(first.date).not.toBe(second.date);
+    expect(first.date.getTime()).toBe(0);
+    first.cache.set('gain', 9);
+    expect(second.cache.get('gain')).toBe(1);
+    expect(options.cache.get('gain')).toBe(1);
+  });
+
   it('wraps a class default in a factory that returns the class itself', () => {
     class Cool {
       x = 1;
@@ -1112,3 +1157,14 @@ describe('$watchEffect (scoped watchEffect)', () => {
     expect(watchRuns).toBe(1); // sibling watcher in the same scope still fires
   });
 });
+
+describe('definePropTypes()', () => {
+  it('returns the same types map (identity, literal-preserving)', () => {
+    const types = definePropTypes({
+      title: { type: String, required: true },
+      size: { type: Number },
+    });
+    expect(types.title.required).toBe(true);
+    expect(types.size.type).toBe(Number);
+  });
+});

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

@@ -49,7 +49,7 @@ describe('Static', () => {
       }
     }
     class $Child extends $Base {
-      static describe() {
+      static override describe() {
         return 'child';
       }
     }
@@ -426,6 +426,65 @@ describe('Static $-cached getters', () => {
     expect(settle()).toBe(70); // inherited method binds to the child, detached
   });
 
+  // invariant: A prototype level is transformed at most once (ivue.invariants.md)
+  it('re-wrapping a subclass never resurrects a parent-bound method through the bind cache', () => {
+    // The double-wrap pattern the manual prescribes: a Static parent, a raw
+    // subclass extending it, and Static() applied again to the subclass.
+    // The parent is READ FIRST, so its bind cache (an own symbol property)
+    // exists when the second wrap walks the chain — that cache must be
+    // invisible to the walk, or the child's methods run with the parent
+    // as receiver.
+    class $Fleet {
+      static get vessels(): string[] {
+        return ['tug'];
+      }
+
+      static roster() {
+        return this.vessels.join(',');
+      }
+    }
+
+    const Fleet = Static($Fleet);
+    expect(Fleet.roster()).toBe('tug'); // parent reads (and caches its bound method) first
+
+    class $HarborFleet extends Fleet {
+      static override get vessels(): string[] {
+        return [...super.vessels, 'ferry'];
+      }
+    }
+    const HarborFleet = Static($HarborFleet);
+
+    expect(HarborFleet.roster()).toBe('tug,ferry'); // the child's override, not the parent's snapshot
+    const roster = HarborFleet.roster;
+    expect(roster()).toBe('tug,ferry'); // detached, still child-bound
+  });
+
+  // invariant: A prototype level is transformed at most once (ivue.invariants.md)
+  it('re-wrapping skips the unregistered bind caches of symbol-keyed methods too', () => {
+    const describeKind = Symbol('describeKind');
+    class $Signal {
+      static get kind(): string {
+        return 'base';
+      }
+
+      static [describeKind]() {
+        return `kind:${this.kind}`;
+      }
+    }
+
+    const Signal = Static($Signal);
+    expect((Signal as any)[describeKind]()).toBe('kind:base'); // parent reads first — unregistered bind cache lands
+
+    class $AlertSignal extends Signal {
+      static override get kind(): string {
+        return 'alert';
+      }
+    }
+    const AlertSignal = Static($AlertSignal);
+
+    expect((AlertSignal as any)[describeKind]()).toBe('kind:alert'); // child receiver, not the parent snapshot
+  });
+
   it('walks the raw inheritance chain — ancestor $-getters cache per receiver', () => {
     class $Base {
       static get scale() {

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

@@ -13,6 +13,7 @@ import {
   ivue,
   propertiesAccessorsMaps,
   propsWithDefaults,
+  definePropTypes,
 } from '../ivue';
 const {
   copyOwnProps,
@@ -76,21 +77,21 @@ class ProductItem extends Item {
 }
 
 class StoreItem extends ProductItem {
-  _productType = iref('store');
-  get productType() {
+  override _productType = iref('store');
+  override get productType() {
     const prefix = super.productFeel ?? '';
     return (prefix ? prefix + ':' : '') + this._productType;
   }
-  set productFeel(value: string) {
+  override set productFeel(value: string) {
     this._productFeel = value;
   }
 }
 
 class RetailStoreItem extends StoreItem {
-  _productType = iref('retail');
+  override _productType = iref('retail');
   /** Do not overwrite productType getter here, on purpose. */
   productHistory = iref([]);
-  get testProperty() {
+  override get testProperty() {
     return this._testProperty;
   }
   calculateSize() {
@@ -1885,3 +1886,14 @@ describe('ivue coverage edge cases', () => {
     expect(cloned.value).toBe(7);
   });
 });
+
+describe('definePropTypes()', () => {
+  it('returns the same types map (identity, literal-preserving)', () => {
+    const types = definePropTypes({
+      title: { type: String, required: true },
+      size: { type: Number },
+    });
+    expect(types.title.required).toBe(true);
+    expect(types.size.type).toBe(Number);
+  });
+});

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

@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'vitest';
+import { shallowReactive, shallowReadonly } from 'vue';
+import { nestedProps, type NestedPartial } from '../extras';
+
+type Knobs = {
+  wheel: { gain: number; follow: number };
+  touch: { gain: number; inertia: number; list: number[] };
+  label: string;
+};
+
+const defaults = (): Knobs => ({
+  wheel: { gain: 1, follow: 0.1 },
+  touch: { gain: 1.3, inertia: 30, list: [1, 2, 3] },
+  label: 'default'
+});
+
+describe('nestedProps', () => {
+  it('preserves null-prototype defaults, literal __proto__ keys and sparse arrays', () => {
+    const sparse = new Array<{ offset: number }>(2);
+    sparse[1] = { offset: 2 };
+    const bare = Object.assign(Object.create(null), { gain: 1 });
+    const literal = { ['__proto__']: { gain: 2 } };
+    const sharedDefaults = { scroll: { sparse, bare, literal } };
+    const filled = nestedProps({ scroll: {} }, sharedDefaults) as typeof sharedDefaults;
+
+    expect(Object.getPrototypeOf(filled.scroll.bare)).toBeNull();
+    expect(filled.scroll.bare).not.toBe(bare);
+    expect(Object.getPrototypeOf(filled.scroll.literal)).toBe(Object.prototype);
+    expect(Object.hasOwn(filled.scroll.literal, '__proto__')).toBe(true);
+    expect(filled.scroll.literal.__proto__).not.toBe(literal.__proto__);
+    expect(filled.scroll.sparse.length).toBe(2);
+    expect(0 in filled.scroll.sparse).toBe(false);
+    filled.scroll.sparse[1].offset = 9;
+    expect(sparse[1].offset).toBe(2);
+  });
+
+  it('copies missing default objects and arrays independently for each instance', () => {
+    const sharedDefaults = { scroll: { touch: { gain: 1, points: [{ offset: 2 }] }, steps: [1, 2] } };
+    const first = nestedProps({ scroll: {} }, sharedDefaults) as typeof sharedDefaults;
+    const second = nestedProps({ scroll: {} }, sharedDefaults) as typeof sharedDefaults;
+
+    first.scroll.touch.gain = 9;
+    first.scroll.touch.points[0].offset = 8;
+    first.scroll.steps.push(3);
+
+    expect(second).toEqual({ scroll: { touch: { gain: 1, points: [{ offset: 2 }] }, steps: [1, 2] } });
+    expect(sharedDefaults).toEqual(second);
+    expect(second.scroll.touch).not.toBe(sharedDefaults.scroll.touch);
+    expect(second.scroll.steps).not.toBe(sharedDefaults.scroll.steps);
+  });
+
+  it('preserves supplied containers and opaque default values when copying missing branches', () => {
+    class Tuning { gain = 9; }
+    const tuning = new Tuning();
+    const callback = () => 1;
+    const suppliedList = [7];
+    const supplied = { scroll: { list: suppliedList } };
+    const sharedDefaults = { scroll: { list: [1], touch: { tuning, callback, label: null } } };
+    const filled = nestedProps(supplied, sharedDefaults) as typeof sharedDefaults;
+
+    expect(filled).toBe(supplied);
+    expect(filled.scroll.list).toBe(suppliedList);
+    expect(filled.scroll.touch).not.toBe(sharedDefaults.scroll.touch);
+    expect(filled.scroll.touch.tuning).toBe(tuning);
+    expect(filled.scroll.touch.callback).toBe(callback);
+    expect(filled.scroll.touch.label).toBeNull();
+  });
+
+  it('fills a partial object from the defaults at every depth, in place, keeping every supplied leaf', () => {
+    const supplied: NestedPartial<Knobs> = { wheel: { gain: 2 }, label: 'mine' };
+    const props = nestedProps(supplied, defaults());
+    expect(props).toBe(supplied);
+    expect(props.wheel).toEqual({ gain: 2, follow: 0.1 });
+    expect(props.label).toBe('mine');
+    // A top-level prop is Vue's to default: never written here.
+    expect('touch' in props).toBe(false);
+  });
+
+  it('recurses through every plain-object level, filling only what is missing', () => {
+    const tree = { a: { b: { c: 9 }, e: 5 } };
+    const filled = nestedProps({ tree }, { tree: { a: { b: { c: 1, d: 2 }, e: 3, f: 4 } } });
+    expect(filled.tree).toBe(tree);
+    expect(filled.tree).toEqual({ a: { b: { c: 9, d: 2 }, e: 5, f: 4 } });
+  });
+
+  it('skips a top-level prop that is not a plain object on both sides, and fills a prototype-less default', () => {
+    const bareDefault = Object.create(null) as { z: number; y: number };
+    bareDefault.z = 1;
+    bareDefault.y = 2;
+    const props = { list: null as unknown as number[], label: 'mine', bare: { z: 5 }, fn: () => 1 };
+    const filled = nestedProps(props, { list: [1, 2], label: 'default', bare: bareDefault, fn: { a: 1 } });
+    expect(filled.list).toBeNull();
+    expect(filled.label).toBe('mine');
+    expect(filled.bare).toEqual({ z: 5, y: 2 });
+    expect(typeof filled.fn).toBe('function');
+  });
+
+  it('treats a nested undefined as absent and a nested null as a value', () => {
+    const props = nestedProps(
+      { wheel: { gain: undefined, follow: null } } as unknown as NestedPartial<Knobs>,
+      defaults()
+    );
+    expect(props.wheel.gain).toBe(1);
+    expect(props.wheel.follow).toBeNull();
+  });
+
+  it('takes arrays, class instances and functions whole, never merged', () => {
+    class Tuning {
+      gain = 9;
+    }
+    const tuning = new Tuning();
+    const props = nestedProps(
+      { touch: { list: [7] }, wheel: tuning } as unknown as NestedPartial<Knobs>,
+      defaults()
+    );
+    expect(props.touch.list).toEqual([7]);
+    expect(props.touch.inertia).toBe(30);
+    expect(props.wheel).toBe(tuning);
+    expect((props.wheel as unknown as Tuning).gain).toBe(9);
+    // An object supplied where the default is an array is kept as is.
+    const odd = nestedProps({ touch: { list: { 0: 7 } } } as unknown as NestedPartial<Knobs>, defaults());
+    expect(odd.touch.list).toEqual({ 0: 7 });
+    // A prototype-less object is plain too.
+    const bare = Object.create(null) as { gain: number };
+    bare.gain = 4;
+    const filled = nestedProps({ wheel: bare } as unknown as NestedPartial<Knobs>, defaults());
+    expect(filled.wheel).toBe(bare);
+    expect(filled.wheel.follow).toBe(0.1);
+  });
+
+  it('works through Vue’s shallow props proxy: the nested object is the parent’s and is filled directly', () => {
+    const wheel = { gain: 2 };
+    const props = shallowReadonly(shallowReactive({ wheel } as NestedPartial<Knobs>));
+    const filled = nestedProps(props, defaults());
+    expect(filled.wheel.follow).toBe(0.1);
+    expect(wheel).toEqual({ gain: 2, follow: 0.1 });
+  });
+
+  it('customCloner is the copy policy for default branches: identity shares them, structuredClone copies built-ins', () => {
+    const wheelDefault = { gain: 1, follow: 0.1 };
+    const first = nestedProps({} as NestedPartial<Knobs>, { wheel: wheelDefault } as Knobs);
+    expect(first.wheel).not.toBe(wheelDefault);
+    // The caller owns a fresh tree per instance and says so: no copy.
+    const owned = { list: [7] };
+    const identity = nestedProps({ touch: {} } as NestedPartial<Knobs>, { touch: owned } as unknown as Knobs, (value) => value);
+    expect(identity.touch.list).toBe(owned.list);
+    // structuredClone gives Date defaults their own copies.
+    const stamp = new Date(0);
+    const copied = nestedProps({ meta: {} } as { meta: { stamp?: Date } }, { meta: { stamp } }, structuredClone);
+    expect(copied.meta.stamp).not.toBe(stamp);
+    expect(copied.meta.stamp?.getTime()).toBe(0);
+  });
+});

package/lib/clone.ts

@@ -0,0 +1,21 @@
+/** Copy plain configuration containers; retain callbacks, constructors and
+ *  opaque objects by reference. Container trees must be acyclic. */
+export function clone<T>(value: T): T {
+  if (Array.isArray(value)) {
+    const copy = new Array(value.length);
+    for (let index = 0; index < value.length; index++) {
+      if (index in value) copy[index] = clone(value[index]);
+    }
+    return copy as T;
+  }
+  if (
+    value === null ||
+    typeof value !== 'object' ||
+    (value.constructor !== Object && value.constructor !== undefined)
+  ) return value;
+
+  // Preserve null prototypes and literal __proto__ keys without entry arrays.
+  const copy: Record<string, unknown> = { __proto__: Object.getPrototypeOf(value), ...value };
+  for (const key in copy) copy[key] = clone(copy[key]);
+  return copy as T;
+}

package/lib/extras.ts

@@ -8,3 +8,4 @@
  */
 export { Static, type ClassConstructor } from './Static';
 export { LazyShared } from './LazyShared';
+export { nestedProps, type NestedPartial, type NestedProps } from './nestedProps';

package/lib/ivue.ts

@@ -130,9 +130,15 @@ export type ExtractEmitTypes<T extends Record<string, any>> =
 
 /**
  * Extract properties as all assigned properties because they have defaults.
+ * Props declared `required: true` are filtered out (they can never carry a
+ * default); declare the types map with a literal-preserving generic call so
+ * the `required: true` literal survives `typeof`.
  */
 export type ExtractPropDefaultTypes<O> = {
-  [K in keyof O]: ValueOf<ExtractPropTypes<O>, K>;
+  [K in keyof O as O[K] extends { required: true } ? never : K]: ValueOf<
+    ExtractPropTypes<O>,
+    K
+  >;
 };
 
 /**
@@ -779,6 +785,14 @@ export const isClass = (val: any): boolean => {
  * @param typedProps Props declared in defineComponent() style with type and possibly required declared, but without default
  * @returns Props declared in defineComponent() style with all properties having default property declared.
  */
+/**
+ * Identity helper for a prop-TYPES map: generic inference preserves the
+ * `required: true` literal that a bare object const widens to `boolean`,
+ * which ExtractPropDefaultTypes' required-key filter depends on.
+ */
+export const definePropTypes = <T extends VuePropsObject>(types: T): T =>
+  types;
+
 export const propsWithDefaults = <T extends VuePropsObject>(
   defaults: Record<string, any>,
   typedProps: T,