ivue 1.6.1 → 2.0.0

package/lib/Reactive.ts

@@ -1,100 +1,128 @@
-import { toRaw, isRef, type Ref } from 'vue';
+import {
+  effectScope,
+  isRef,
+  toRaw,
+  watch,
+  watchEffect,
+  type ExtractPropTypes,
+  type Ref,
+} from 'vue';
 
 /**
  * Constants & Helpers
  */
-const prototypeHasOwnProperty = Object.prototype.hasOwnProperty.call.bind(
-  Object.prototype.hasOwnProperty
-);
+const hasOwn = Object.hasOwn;
 const getPrototypeOf = Object.getPrototypeOf;
 const getOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
-const defineProperty = Object.defineProperty;
 const getOwnPropertyNames = Object.getOwnPropertyNames;
+const defineProperty = Object.defineProperty;
 const objectPrototype = Object.prototype;
-const getOwnPropertySymbols = Object.getOwnPropertySymbols;
 
-const $stopEffects = '$stopEffects';
-const fn = 'function';
-const RAW = Symbol('ivue_raw');
-const SK_MAP = '__ivue_sk'; // Store for cache keys
-const PROCESSED = Symbol('ivue_processed'); // Flag to mark prototype as "Reactified"
+// Identity symbols are global so every bundled copy agrees with objects
+// stamped by another copy of the engine.
+const RAW = Symbol.for('ivue.raw'); // Per-instance back-pointer to the raw object
+const SCOPE = Symbol.for('ivue.scope'); // Lazily-created per-instance effect scope
+// Marks a prototype level as "Reactified"; its VALUE is the list of
+// engine-created instance-cache symbols for that level, so teardown can
+// remove exactly the engine's cells and nothing else.
+const PROCESSED = Symbol.for('ivue.processed');
 
 /**
- * Get unique symbol key for super method/property.
+ * Resolve the TRUE raw instance from whatever `this` the engine was entered
+ * with — the raw object itself, a Vue `reactive()` proxy, or a foreign proxy
+ * chain such as Vue's component expose proxy.
+ *
+ * Neither primitive is sufficient alone:
+ *
+ * - `toRaw(this)` cannot unwrap a foreign (non-Vue-reactive) proxy — e.g.
+ *   Vue's component expose proxy — so it can return the proxy unchanged.
+ * - The RAW back-pointer read through a Vue reactive proxy comes back
+ *   DEEP-WRAPPED: a reactive proxy wraps symbol-keyed object reads in
+ *   `reactive(raw)`. Binding a method (or computed closure) to that wrapped
+ *   value poisons the per-instance cache with ref-unwrapping `this`
+ *   semantics — `this.x.value` then crashes, because `this.x` auto-unwraps
+ *   to the plain value.
+ *
+ * So: try `toRaw()` first (one step for the common reactive-proxy path —
+ * consulting the pointer first costs a wrap+unwrap round-trip per access),
+ * and fall back to the pointer, normalized with `toRaw()`, for everything
+ * `toRaw()` cannot see through.
  */
-function getSuperKey(proto: any, key: string): symbol {
-  // Ensure the map exists on this specific prototype (shadowing parents)
-  if (!prototypeHasOwnProperty(proto, SK_MAP)) {
-    defineProperty(proto, SK_MAP, {
-      value: {},
-      configurable: true,
-      enumerable: false,
-      writable: true,
-    });
+function resolveRaw(self: any) {
+  const unwrapped = toRaw(self);
+  if (unwrapped !== self) {
+    // Genuine Vue reactive proxy. Stamp the back-pointer (once, directly on
+    // the raw — no proxy set traps) so foreign proxy chains can still
+    // resolve the true raw through it.
+    return unwrapped[RAW] ?? (unwrapped[RAW] = unwrapped);
+  }
+  // `self` is the raw object itself, or a foreign proxy over it.
+  const viaPointer = self[RAW];
+  if (viaPointer) {
+    // A pointer read through a proxy chain may come back deep-wrapped —
+    // normalize; on the raw object it is already the raw itself.
+    return viaPointer === self ? viaPointer : toRaw(viaPointer);
   }
-  const map = proto[SK_MAP];
-  return map[key] || (map[key] = Symbol(key));
+  // First-ever engine access on a plain raw instance (direct `new Class()`).
+  return (self[RAW] = self);
 }
 
 /**
- * Convert method to a lazy-bound prototype method.
+ * Convert a method to a lazy-bound prototype method.
+ *
+ * The bound function is created once, on first access, and cached on the raw
+ * object under a unique per-(prototype,key) symbol — giving referentially
+ * stable, correctly-bound methods with zero per-instance construction cost.
  */
-function convertToLazyBoundMethod(proto: any, key: string, superKey: symbol) {
-  const desc = getOwnPropertyDescriptor(proto, key);
-  if (!desc || typeof desc.value !== fn) return;
-
-  const originalFn = desc.value;
-
+function convertToLazyBoundMethod(
+  proto: any,
+  key: string,
+  superKey: symbol,
+  originalFn: (...args: any[]) => any,
+) {
   defineProperty(proto, key, {
     configurable: true,
     enumerable: false,
     get(this: any) {
-      const raw = this[RAW] ?? (this[RAW] = toRaw(this));
+      const raw = resolveRaw(this);
       return raw[superKey] ?? (raw[superKey] = originalFn.bind(raw));
     },
     set(this: any, newFn: any) {
-      toRaw(this)[superKey] = newFn;
+      resolveRaw(this)[superKey] = newFn;
     },
   });
 }
 
 /**
- * Convert a property to a lazy-computed property.
+ * Convert a getter to a lazily-cached Ref cell.
+ *
+ * Only ever called when the descriptor has a getter, so `originalGetter` is
+ * always defined here. A getter that returns any Ref — ref(), shallowRef(),
+ * computed() (a ComputedRef IS a Ref) — is cached under the instance symbol
+ * (stable reactive identity); a getter that returns a plain value
+ * de-optimizes back to a native getter on the prototype, removing all
+ * overhead for future instances.
  */
-function convertToLazyComputed<T extends object>(
-  proto: T,
+function convertToLazyRef(
+  proto: any,
   key: string,
-  superKey: symbol
+  superKey: symbol,
+  originalGetter: (this: any) => any,
+  originalSetter: ((this: any, v: any) => any) | undefined,
 ) {
-  const desc = getOwnPropertyDescriptor(proto, key);
-  const originalGetter = desc?.get;
-  const originalSetter = desc?.set;
-
-  // Optimization: Properties starting with $ are assumed singletons
+  // Optimization: Properties starting with $ are assumed singletons.
   const cacheWhole = key[0] === '$';
 
-  // DEV WARNING: Setter/Getter mismatch
-  if (import.meta.env.DEV && originalGetter && originalSetter) {
-    try {
-      const testVal = originalGetter.call({});
-      if (isRef(testVal)) {
-        console.warn(
-          `[ivue] API conflict on "${key}": Getter returns Ref but Setter is standard.`
-        );
-      }
-    } catch (e) {}
-  }
-
   const newGetter = function (this: any) {
-    const raw = toRaw(this);
+    const raw = resolveRaw(this);
 
-    // 1. Check Cache
+    // 1. Check cache
     if (superKey in raw) return raw[superKey];
 
-    // 2. Execute Original
-    const result = originalGetter!.call(raw);
+    // 2. Execute original
+    const result = originalGetter.call(raw);
 
-    // 3. Handle Result
+    // 3. Handle result
     if (cacheWhole) {
       // Cache result forever (Singleton pattern)
       raw[superKey] = result;
@@ -105,19 +133,17 @@ function convertToLazyComputed<T extends object>(
       // Cache Ref instance (Reactivity pattern)
       raw[superKey] = result;
     } else {
-      // DE-OPTIMIZATION: It's just a value. Restore original getter on prototype.
-      // This removes overhead for all future calls on this prototype.
+      // DE-OPTIMIZATION: It's just a value. Restore a native getter on the
+      // prototype, removing the wrapper overhead for all future instances.
       defineProperty(proto, key, {
         configurable: true,
         enumerable: false,
-        get: originalGetter
-          ? function (this: any) {
-              return originalGetter.call(toRaw(this));
-            }
-          : undefined,
+        get(this: any) {
+          return originalGetter.call(resolveRaw(this));
+        },
         set: originalSetter
           ? function (this: any, v: any) {
-              return originalSetter.call(toRaw(this), v);
+              return originalSetter.call(resolveRaw(this), v);
             }
           : undefined,
       });
@@ -129,10 +155,10 @@ function convertToLazyComputed<T extends object>(
   defineProperty(proto, key, {
     configurable: true,
     enumerable: false,
-    get: originalGetter ? newGetter : undefined,
+    get: newGetter,
     set: originalSetter
       ? function (this: any, v: any) {
-          return originalSetter.call(toRaw(this), v);
+          return originalSetter.call(resolveRaw(this), v);
         }
       : undefined,
   });
@@ -141,10 +167,10 @@ function convertToLazyComputed<T extends object>(
 /**
  * Create a reactive class.
  * @param targetClass The class to make reactive.
- * @returns A reactive version of the class.
+ * @returns A reactive version of the class (the same class, transformed in place).
  */
 export function Reactive<C extends new (...args: any) => any>(
-  targetClass: C
+  targetClass: C,
 ): ReactiveClass<C> & { Instance: ReactiveInstance<InstanceType<C>> } {
   const chain: any[] = [];
 
@@ -158,53 +184,109 @@ export function Reactive<C extends new (...args: any) => any>(
   chain.reverse();
 
   for (const prototype of chain) {
-    // OPTIMIZATION: Skip if this prototype layer is already "Reactified"
+    // OPTIMIZATION: Skip if this prototype layer is already "Reactified".
     // This handles diamond inheritance and multiple Reactive children safely.
-    if (prototypeHasOwnProperty(prototype, PROCESSED)) continue;
+    if (hasOwn(prototype, PROCESSED)) continue;
 
     const names = getOwnPropertyNames(prototype);
+    const cacheKeys: symbol[] = [];
 
     for (const key of names) {
       if (key === 'constructor') continue;
-      const desc = getOwnPropertyDescriptor(prototype, key);
-      if (!desc) continue;
-
-      const superKey = getSuperKey(prototype, key);
-
-      if (typeof desc.value === fn) {
-        convertToLazyBoundMethod(prototype, key, superKey);
+      const desc = getOwnPropertyDescriptor(prototype, key)!;
+
+      if (typeof desc.value === 'function') {
+        // A fresh symbol per (prototype,key). Because each prototype level gets
+        // its own symbol, a child override and its `super` counterpart cache
+        // under different keys and never collide.
+        const superKey = Symbol(key);
+        cacheKeys.push(superKey);
+        convertToLazyBoundMethod(prototype, key, superKey, desc.value);
       } else if (desc.get) {
-        convertToLazyComputed(prototype, key, superKey);
+        const superKey = Symbol(key);
+        cacheKeys.push(superKey);
+        convertToLazyRef(prototype, key, superKey, desc.get, desc.set);
       }
     }
 
-    // Mark this specific prototype level as processed
+    // Mark this prototype level as processed; the marker carries the
+    // level's engine cache keys (see PROCESSED above).
     defineProperty(prototype, PROCESSED, {
-      configurable: false,
-      enumerable: false,
-      value: true,
+      value: cacheKeys,
     });
   }
 
-  // Inject cleanup
-  if (!prototypeHasOwnProperty(targetClass.prototype, $stopEffects)) {
-    defineProperty(targetClass.prototype, $stopEffects, {
+  // Inject the $watch/$watchEffect/$stopEffects helpers. The guard is an
+  // IDEMPOTENCY SENTINEL only — one key stands for the whole trio, so a
+  // repeated Reactive() call (diamond imports, duplicate bundled engine
+  // copies) skips re-injection. It is NOT override protection: the $-helper
+  // names are reserved engine API (richer cleanup is an ordinary method
+  // that calls $stopEffects() itself — ivue never auto-calls user code).
+  if (!hasOwn(targetClass.prototype, '$stopEffects')) {
+    /**
+     * Register a watcher in this instance's lazily-created effect scope.
+     * The scope is allocated only on first use, so pure-data classes that
+     * never watch pay nothing. Has the same signature as Vue's `watch`.
+     */
+    defineProperty(targetClass.prototype, '$watch', {
+      enumerable: false,
+      configurable: true,
+      writable: true,
+      value: function (this: any, ...args: any[]) {
+        const raw = resolveRaw(this);
+        const scope =
+          raw[SCOPE] ?? (raw[SCOPE] = effectScope(true /* detached */));
+        return scope.run(() => (watch as any)(...args));
+      },
+    });
+
+    /**
+     * Register a watchEffect in the same lazy per-instance scope.
+     */
+    defineProperty(targetClass.prototype, '$watchEffect', {
+      enumerable: false,
+      configurable: true,
+      writable: true,
+      value: function (this: any, ...args: any[]) {
+        const raw = resolveRaw(this);
+        const scope =
+          raw[SCOPE] ?? (raw[SCOPE] = effectScope(true /* detached */));
+        return scope.run(() => (watchEffect as any)(...args));
+      },
+    });
+
+    /**
+     * Tear down the instance: stop its effect scope (any watchers created via
+     * $watch) and drop all cached cells so refs/computeds become collectable.
+     * No hooks — ivue never calls user code; compose richer cleanup as an
+     * ordinary method that does its own work and then calls $stopEffects().
+     */
+    defineProperty(targetClass.prototype, '$stopEffects', {
       enumerable: false,
       configurable: true,
       writable: true,
       value: function (this: any) {
-        const raw = toRaw(this);
-        if (typeof raw.stopEffects === fn) raw.stopEffects();
-
-        const symbols = getOwnPropertySymbols(raw);
-        for (const symbol of symbols) {
-          if (symbol === RAW) continue;
-          const cached = raw[symbol];
-          // Stop computed/effect if present
-          if (cached && cached.effect && typeof cached.effect.stop === fn) {
-            cached.effect.stop();
+        const raw = resolveRaw(this);
+        try {
+          const scope = raw[SCOPE];
+          if (scope) scope.stop();
+        } finally {
+          // SCOPE is ivue-owned but is not a method/getter cache key.
+          delete raw[SCOPE];
+
+          // Each processed prototype's PROCESSED marker carries the
+          // symbols it may cache on an instance. Walk Child -> Base and
+          // remove only those known keys.
+          let prototype = getPrototypeOf(raw);
+          while (prototype && prototype !== objectPrototype) {
+            const cacheKeys = prototype[PROCESSED] as
+              | readonly symbol[]
+              | undefined;
+            if (cacheKeys) {
+              for (const cacheKey of cacheKeys) delete raw[cacheKey];
+            }
+            prototype = getPrototypeOf(prototype);
           }
-          delete raw[symbol];
         }
       },
     });
@@ -273,34 +355,47 @@ export const isClass = (val: any): boolean => {
  * but leave primitive properties and functions intact so that
  * the final object is fully defineComponent() style compatible.
  *
+ * The default cloner is the native `structuredClone` (zero-dependency, handles
+ * plain data, Map/Set/Date/typed arrays, circular refs). For defaults that
+ * contain class instances or functions — which `structuredClone` cannot clone —
+ * pass a `customCloner` such as lodash `cloneDeep`.
+ *
  * @param defaults Regular object of default key -> values
  * @param typedProps Props declared in defineComponent() style with type and possibly required declared, but without default
+ * @param customCloner Optional cloner used for object/array defaults (defaults to structuredClone)
  * @returns Props declared in defineComponent() style with all properties having default property declared.
  */
 export const propsWithDefaults = <T extends VuePropsObject>(
   defaults: Record<string, any>,
   typedProps: T,
   // Optional: Allows user to pass a custom cloner if structuredClone isn't enough
-  customCloner?: (val: any) => any
+  customCloner?: (val: any) => any,
 ): VuePropsWithDefaults<T> => {
+  // NON-MUTATING: descriptor objects are routinely SHARED between props
+  // maps (`{ ...baseParamsTypes, extra }` — the spread copies the outer
+  // object but every inner `{ type }` descriptor stays the same reference).
+  // Writing `.default` in place would silently rewrite the base component's
+  // defaults; each descriptor is copied instead.
+  const result: Record<string, any> = {};
   for (const prop in typedProps) {
     const def = defaults?.[prop];
     const typed = typedProps[prop];
+    result[prop] = { ...typed };
 
     if (typed.required || def === undefined) continue;
 
     if (typeof def === 'object' && def !== null) {
-      typedProps[prop].default = () =>
+      result[prop].default = () =>
         customCloner ? customCloner(def) : structuredClone(def);
     } else {
       if (isClass(def)) {
-        typedProps[prop].default = () => def;
+        result[prop].default = () => def;
       } else {
-        typedProps[prop].default = def;
+        result[prop].default = def;
       }
     }
   }
-  return typedProps as VuePropsWithDefaults<T>;
+  return result as VuePropsWithDefaults<T>;
 };
 
 /**
@@ -310,29 +405,105 @@ type GetterKeys<T> = {
   [K in keyof T]: T[K] extends (...args: any[]) => any
     ? never
     : T[K] extends undefined
-    ? never
-    : K;
+      ? never
+      : K;
 }[keyof T];
 
 type GetterReturn<T, K extends keyof T> = T[K] extends (...args: any[]) => any
   ? never
   : T[K];
 type WritableComputedLike = Ref<any> & { set: (...args: any[]) => any };
-type IsWritableGetter<R> = R extends Ref<any>
-  ? true
-  : R extends WritableComputedLike
-  ? true
-  : false;
+type IsWritableGetter<R> =
+  R extends Ref<any> ? true : R extends WritableComputedLike ? true : false;
 
 type WritableGetters<T> = {
-  [K in GetterKeys<T> as IsWritableGetter<GetterReturn<T, K>> extends true
-    ? K
-    : never]-?: T[K];
+  [
+    K in GetterKeys<T> as IsWritableGetter<GetterReturn<T, K>> extends true
+      ? K
+      : never
+  ]-?: T[K];
 };
 
 export type ReactiveInstance<T> = T &
-  WritableGetters<T> & { $stopEffects: () => void };
+  WritableGetters<T> & {
+    /** Register a watcher in the instance's lazy effect scope (same signature as Vue `watch`). */
+    $watch: typeof watch;
+    /** Register a watchEffect in the instance's lazy effect scope (same signature as Vue `watchEffect`). */
+    $watchEffect: typeof watchEffect;
+    /** Stop the instance's effect scope and drop cached cells. */
+    $stopEffects: () => void;
+  };
 
 export type ReactiveClass<C extends new (...args: any) => any> = new (
   ...args: ConstructorParameters<C>
 ) => ReactiveInstance<InstanceType<C>>;
+
+/**
+ * Component-authoring type utilities (types only — erased at build time).
+ * These complement `propsWithDefaults` for the params/defaults component
+ * architecture: object-declared emits, extensible slots, and precise
+ * handler-parameter extraction.
+ */
+
+/** Any JavaScript function of any type. */
+export type AnyFn = (...args: any[]) => any;
+
+/** Convert Record to Union Type. */
+export type RecordToUnion<T extends Record<string, any>> = T[keyof T];
+
+/** Gets object T property by key K. */
+export type ValueOf<T extends Record<any, any>, K extends keyof T> = T[K];
+
+/** Convert Union Type to Intersection Type. */
+export type UnionToIntersection<U> = (
+  U extends any ? (k: U) => void : never
+) extends (k: infer I) => void
+  ? I
+  : never;
+
+/** Prefix keys of an interface T with a prefix P. */
+export type PrefixKeys<T, P extends string | undefined = undefined> = {
+  [K in Extract<keyof T, string> as P extends string ? `${P}${K}` : K]: T[K];
+};
+
+/** Extracts object-declared emit validators into the emit-function interface. */
+export type ExtractEmitTypes<T extends Record<string, any>> =
+  UnionToIntersection<
+    RecordToUnion<{
+      [K in keyof T]: (evt: K, ...args: Parameters<T[K]>) => void;
+    }>
+  >;
+
+/**
+ * Extract properties as all-assigned (non-optional) because every one of
+ * them carries a default.
+ */
+export type ExtractPropDefaultTypes<O> = {
+  [K in keyof O]: K extends keyof ExtractPropTypes<O>
+    ? ExtractPropTypes<O>[K]
+    : never;
+};
+
+/**
+ * Extend a slots interface T with prefixed 'before--' & 'after--' slots to
+ * create fully extensible wrapped components.
+ */
+export type ExtendSlots<T> = PrefixKeys<T, 'before--'> &
+  T &
+  PrefixKeys<T, 'after--'>;
+
+/** Get function arguments Parameters<F> parameter by index K. */
+export type FnParameter<F extends AnyFn, K extends number> = Parameters<F>[K];
+
+/** Get interface T property K's function arguments as Parameters. */
+export type IFnParameters<
+  T extends Record<any, any>,
+  K extends string,
+> = Parameters<Required<Pick<T, K>>[K]>;
+
+/** Get interface T property P's function parameter by index K. */
+export type IFnParameter<
+  T extends Record<any, any>,
+  P extends keyof T,
+  K extends number,
+> = FnParameter<NonNullable<T[P]> extends AnyFn ? NonNullable<T[P]> : never, K>;