ivue 1.5.8 → 2.0.0

package/lib/ivue.ts

@@ -1,35 +1,65 @@
-/* eslint-disable @typescript-eslint/ban-types */
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import type { ComputedRef, ExtractPropTypes, Ref, ToRef } from 'vue';
-import { computed, reactive, ref, shallowRef, toRef } from 'vue';
+import { computed, markRaw, reactive, ref, shallowRef, toRef } from 'vue';
 import type { Ref as DemiRef } from 'vue-demi';
 
+/** Cached global methods. */
+const isArray = Array.isArray;
+const createObject = Object.create;
+const defineProperty = Object.defineProperty;
+const getPrototypeOf = Object.getPrototypeOf;
+const getOwnPropertyNames = Object.getOwnPropertyNames;
+const getOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
+const getOwnPropertyDescriptors = Object.getOwnPropertyDescriptors;
+
+
 /** Types */
 /**
  * IVue core reactive instance type with an extended .toRefs() method added.
  */
 export type IVue<T extends AnyClass> = InstanceType<T> & {
   toRefs: IVueToRefsFn<T>;
+  clone: IVueClone<T>;
 };
 
+/**
+ * Type definition for `.clone()` method creates a deep clone of the ivue instance.
+ */
+export type IVueClone<T extends AnyClass> = (
+  ...cloneArgs: CloneArgsFor<InstanceType<T>>
+) => IVue<T>;
+
 /**
  * Type definition for `.toRefs()` method converts reactive class properties to composable .value properties.
  * But if props = true OR unwrap = true is specified, the refs will be unwrapped refs to be able to be merged with the the root class properties without losing reactivity.
  */
+/** Extract only non-method keys from a type */
+type NonMethodKeys<T> = {
+  [K in keyof T]: T[K] extends AnyFn ? never : K;
+}[keyof T];
+
+/** Create a type with only data properties and accessors */
+type DataProperties<T> = Pick<T, NonMethodKeys<T>>;
+
+/**
+ * Simplified IVueToRefsFn that only works with data properties
+ */
 interface IVueToRefsFn<T extends AnyClass> {
-  <P extends keyof InstanceType<T>>(props: P[]): Pick<
+  <P extends keyof IVueRefs<InstanceType<T>>>(props: P[]): Pick<
     IVueRefs<InstanceType<T>>,
     P
   >;
-  <P extends keyof InstanceType<T>>(props: P[], unwrap: false): Pick<
+
+  <P extends keyof IVueRefs<InstanceType<T>>>(props: P[], unwrap: false): Pick<
     IVueRefs<InstanceType<T>>,
     P
   >;
-  <P extends keyof InstanceType<T>>(props: P[], unwrap: true): Pick<
-    InstanceType<T>,
-    P
-  >;
-  (props: true): InstanceType<T>;
+
+  <P extends keyof DataProperties<InstanceType<T>>>(
+    props: P[],
+    unwrap: true
+  ): Pick<DataProperties<InstanceType<T>>, P>;
+
+  (props: true): DataProperties<InstanceType<T>>;
   (props: false): IVueRefs<InstanceType<T>>;
   (): IVueRefs<InstanceType<T>>;
 }
@@ -39,7 +69,7 @@ interface IVueToRefsFn<T extends AnyClass> {
  * also knows NOT to convert functions to .value Refs but to leave them as is.
  */
 export type IVueRefs<T> = {
-  [K in keyof T]: T[K] extends Function ? T[K] : ToRef<T[K]>;
+  [K in keyof T as T[K] extends AnyFn ? never : K]: ToRef<T[K]>;
 };
 
 /**
@@ -72,7 +102,7 @@ export type Use<T = any> = T extends Ref | DemiRef
   : UnwrapComposableRefs<T extends AnyFn ? ReturnType<T> : T>;
 
 /**
- * Extracts object defined emit types by converting them to a plain interface
+ * Extracts object defined emit types by converting them to a plain interface.
  */
 export type ExtractEmitTypes<T extends Record<string, any>> =
   UnionToIntersection<
@@ -104,12 +134,12 @@ export type AnyFn = (...args: any[]) => any;
 /**
  * Any JavaScript class of any type.
  */
-export type AnyClass = abstract new (...args: any[]) => any;
+export type AnyClass = new (...args: any[]) => any;
 
 /**
- * Descriptors map type.
+ * Accessors map type.
  */
-type Descriptors = Map<string, PropertyDescriptor>;
+type Accessors = Map<string, PropertyDescriptor>;
 
 /**
  * Computeds hash map type.
@@ -130,23 +160,6 @@ export type PrefixKeys<T, P extends string | undefined = undefined> = {
   [K in Extract<keyof T, string> as P extends string ? `${P}${K}` : K]: T[K];
 };
 
-/**
- * Get Interface's property's function arguments Parmeters<F>
- */
-export type IFnParameters<
-  T extends Record<any, any>,
-  K extends string
-> = Parameters<Required<Pick<T, K>>[K]>;
-
-/**
- * Get Interface's [T] property's [P] function arguments Parmeters<F> parameter by key [K]
- */
-export type IFnParameter<
-  T extends Record<any, any>,
-  P extends keyof T,
-  K extends number
-> = FnParameter<ValueOf<T, P>, K>;
-
 /**
  * Get function arguments Parmeters<F> parameter by key K
  */
@@ -155,80 +168,226 @@ export type FnParameter<F extends AnyFn, K extends number> = Parameters<F>[K];
 /**
  * Convert Union Type to Intersection Type.
  */
-export type UnionToIntersection<U> = (
-  U extends any ? (k: U) => void : never
-) extends (k: infer I) => void
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
+  k: infer I
+) => void
   ? I
   : never;
 
 /**
  * Convert Record to Union Type.
  */
-export type RecordToUnion<T extends Record<string, any>> = T[keyof T];
+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> = T[K];
+type ValueOf<T extends Record<any, any>, K> = T[K];
+
+/**
+ * Props Map Value type.
+ */
+type PropsMapValue = {
+  allProps: Map<string, PropKind>;
+  onlyProps: Set<string>;
+};
+
+/**
+ * Accessors and Methods map type.
+ */
+type AccessorsMethodsMap = {
+  accessors: Accessors;
+  methods: Set<string>;
+};
+
+export type IVueInstanceBase = {
+  init?: (...args: any[]) => void;
+};
+
+/**
+ * IVue static configuration interface.
+ */
+export interface IVueStaticConfig<T> {
+  ivueGlobalStore?: boolean;
+  ivueCloneByReference?: Set<keyof T>;
+  ivueDisableReactivity?: Set<keyof T>;
+}
+
+/**
+ * IVue constructor type.
+ */
+export type IVueConstructor<T> = new (...args: any[]) => T;
+
+/**
+ * IVue class type with static configuration.
+ */
+export type IVueClass<T> = IVueConstructor<T> & IVueStaticConfig<T>;
+
+/**
+ * Get IVue init() method arguments IVueInitArgs<T>
+ */
+export type IVueInitArgs<T extends IVueInstanceBase> = T['init'] extends (
+  ...args: any[]
+) => any
+  ? Parameters<T['init']>
+  : never;
+
+/**
+ * Get Interface's method keys MethodKeys<T>
+ */
+type MethodKeys<T> = {
+  [P in keyof T]: T[P] extends (...args: any[]) => any ? P : never;
+}[keyof T];
+
+/**
+ * Get Interface's property's function arguments Parameters<F>
+ */
+export type IFnParameters<
+  T extends Record<any, any> | InstanceType<AnyClass>,
+  K extends MethodKeys<T>
+> = Parameters<Extract<Required<Pick<T, K>>[K], AnyFn>>;
+
+/**
+ * Get Interface's [T] property's [P] function arguments Parmeters<F> parameter by key [K]
+ */
+export type IFnParameter<
+  T extends Record<any, any>,
+  P extends keyof T,
+  K extends number
+> = FnParameter<ValueOf<T, P>, K>;
+
+export type IVueDeepCloneArgsMap = Map<AnyClass, any[]>;
+
+type CloneArgsFor<T> = T extends {
+  init: (isClone: boolean, ...rest: infer A) => any;
+}
+  ? A
+  : [];
 /** Types End. */
 
+export const IVUE_INSTANCE_SYMBOL = Symbol('IVUE_INSTANCE');
+
 /**
- * Store all descriptors for each class prototype processed by
- * @see {getAllClassDescriptors}
+ * Stores accessors for each class prototype processed by
+ * @see {getClassAccessorsMethodsMap}. Uses WeakMap to allow garbage collection
+ * of unused class accessors, ensuring memory efficiency in long-running applications.
  */
-export const descriptorsMap = new Map();
+export let accessorsMethodsMaps = new WeakMap<object, AccessorsMethodsMap>();
 
 /**
- * Get descriptors of an entire class prototype ancestors chain as a Map.
+ * Get accessors of an entire class prototype ancestors chain as a Map.
  * Completely emulates JavaScript class inheritance chain for getters and setters.
  *
  * @param className
- * @return {Descriptors}
+ * @return {AccessorsMethodsMap}
  */
-export function getAllClassDescriptors(className: AnyClass): Descriptors {
-  /* Retrieve descriptors from cache */
-  if (descriptorsMap.has(className)) {
-    return descriptorsMap.get(className);
+const getClassAccessorsMethodsMap = (
+  className: AnyClass
+): AccessorsMethodsMap => {
+  if (accessorsMethodsMaps.has(className)) {
+    return accessorsMethodsMaps.get(className) as AccessorsMethodsMap;
   }
 
-  const savedDescriptors: Descriptors = new Map();
+  const savedAccessors: Accessors = new Map();
+  const savedMethods: Set<string> = new Set();
 
   let prototype = className.prototype;
-  while (prototype.constructor !== Object) {
-    Object.entries(Object.getOwnPropertyDescriptors(prototype)).forEach(
-      ([propertyName, currentDescriptor]) => {
-        const savedDescriptor = savedDescriptors.get(propertyName);
-        /** Emulate inheritance chain of getters and setters. */
-        if (
-          savedDescriptor !== currentDescriptor &&
-          (currentDescriptor?.get || currentDescriptor?.set)
-        ) {
-          /** Overwrite descriptors if they were already set. */
-          if (savedDescriptor?.get)
-            currentDescriptor.get = savedDescriptor?.get;
-          if (savedDescriptor?.set)
-            currentDescriptor.set = savedDescriptor?.set;
-
-          /** Store descriptors. */
-          savedDescriptors.set(propertyName, currentDescriptor);
+  while (prototype && prototype !== Object.prototype) {
+    const accessors = getOwnPropertyDescriptors(prototype);
+    for (const propertyName in accessors) {
+      if (propertyName === 'constructor') continue;
+      const descriptor = accessors[propertyName];
+      if (descriptor.get || descriptor.set) {
+        // Only add if it hasn't been defined yet (i.e. subclass overrides win)
+        if (!savedAccessors.has(propertyName)) {
+          savedAccessors.set(propertyName, descriptor);
         }
+      } else if (typeof descriptor.value === 'function') {
+        savedMethods.add(propertyName);
       }
-    );
-    /** Walk up the prototype ancestors chain. */
-    prototype = Object.getPrototypeOf(prototype);
+    }
+    prototype = getPrototypeOf(prototype);
   }
 
-  /** Save descriptors in the descriptors map for each class. */
-  descriptorsMap.set(className, savedDescriptors);
+  const propertyMap = {
+    accessors: savedAccessors,
+    methods: savedMethods,
+  };
+  accessorsMethodsMaps.set(className, propertyMap);
 
-  return savedDescriptors;
+  return propertyMap;
+};
+
+/**
+ * Property kind enum for distinguishing between data properties and accessors.
+ */
+const enum PropKind {
+  Data = 0,
+  Accessor = 2,
 }
 
+/**
+ * Stores properties for each class prototype processed by
+ * @see {getClassPropertiesAccessorsMap}. Uses WeakMap to allow garbage collection
+ * of unused class properties, ensuring memory efficiency in long-running applications.
+ */
+export let propertiesAccessorsMaps: WeakMap<object, PropsMapValue> =
+  new WeakMap();
+
+/**
+ * 'caller', 'callee', 'arguments', 'constructor' are
+ * special object properties, so should be skipped.
+ * Also skip 'toRefs' as it's added by ivue and not part of the class itself.
+ */
+const skipProps = new Set(['caller', 'callee', 'arguments', 'constructor']);
+
+/**
+ * Get properties of an entire class prototype ancestors chain as a Map.
+ */
+const getClassPropertiesAccessorsMap = (obj: object): PropsMapValue => {
+  const constructor = obj.constructor;
+  /* Retrieve props from cache. */
+  if (propertiesAccessorsMaps.has(constructor)) {
+    return propertiesAccessorsMaps.get(constructor) as PropsMapValue;
+  }
+
+  const { accessors, methods } =
+    accessorsMethodsMaps.get(constructor) ??
+    getClassAccessorsMethodsMap(constructor as AnyClass);
+
+  const onlyProps = new Set<string>();
+  const allProps: Map<string, PropKind> = new Map();
+
+  do {
+    const propertyNames = getOwnPropertyNames(obj);
+    for (let i = 0, j = propertyNames.length; i < j; i++) {
+      const property = propertyNames[i];
+
+      if (skipProps.has(property)) continue; // Skip special properties
+      if (allProps.has(property)) continue; // Already defined in subclass, skip it
+
+      if (accessors.has(property)) {
+        allProps.set(property, PropKind.Accessor);
+      } else if (!methods.has(property)) {
+        onlyProps.add(property);
+        allProps.set(property, PropKind.Data);
+      }
+    }
+
+    obj = getPrototypeOf(obj);
+  } while (obj && obj.constructor !== Object);
+
+  const result = { allProps, onlyProps };
+  propertiesAccessorsMaps.set(constructor, result);
+
+  return result;
+};
+
 /**
  * Infinite Vue (ivue) class reactive initializer.
  *
  * Converts class instance to a reactive object,
- * where descriptors are converted to computeds.
+ * where accessors are converted to computeds.
  *
  * You can turn off computed behaviour by adding static
  * ivue object and setting the getter props to false.
@@ -244,91 +403,209 @@ export function getAllClassDescriptors(className: AnyClass): Descriptors {
  * @param args Class constructor arguments that you would pass to a `new AnyClass(args...)`
  * @returns {IVue<T>}
  */
-export function ivue<T extends AnyClass>(
+export const ivue = <T extends AnyClass>(
   className: T,
   ...args: InferredArgs<T>
-): IVue<T> {
-  const descriptors: Descriptors = getAllClassDescriptors(className);
-  const computeds: Computeds | any = descriptors?.size ? {} : null;
+): IVue<T> => {
+  const { accessors, methods } = getClassAccessorsMethodsMap(className);
+  const computeds: Computeds | any = accessors?.size
+    ? createObject(null)
+    : null;
 
-  // @ts-expect-error Abstract class initialization
+  /** Create a reactive instance of the class. */
   const vue = reactive(new className(...args));
 
-  /** Setup descriptors as computeds. */
-  for (const [prop, descriptor] of descriptors) {
-    /* If prop exists on static getter className.ivue[prop]
-     * We do not convert it to computed. Because sometimes
-     * we want a normal getter. */
-    if ((className as any)?.ivue?.[prop] === false) continue;
+  /** Setup accessors as computeds. */
+  for (const [prop, descriptor] of accessors) {
     /** Convert descriptor to computed. */
-    Object.defineProperty(vue, prop, {
-      get: descriptor.get
-        ? () =>
-            prop in computeds
-              ? /** Get the existing computed, because we are in reactive scope, .value will auto unwrap itself. */
-                computeds[prop]
-              : /** Create the computed and return it, because we are in reactive scope, .value will auto unwrap itself. */
-                (computeds[prop] = computed({
-                  get: descriptor.get?.bind(vue) as any,
-                  set: descriptor.set?.bind(vue),
-                } as any))
-        : undefined,
-      set: descriptor.set?.bind(vue),
-      enumerable: false,
+    defineProperty(vue, prop, {
+      get: () =>
+        computeds[prop] ??
+        (computeds[prop] = computed({
+          get: descriptor.get?.bind(vue) as unknown,
+          set: descriptor.set?.bind(vue),
+        } as any)) /** Create the computed and return it, because we are in reactive scope, .value will auto unwrap itself. */,
+      enumerable: descriptor.enumerable,
+      configurable: descriptor.configurable,
     });
   }
 
-  Object.defineProperty(vue, 'toRefs', {
-    get: () => ivueToRefs(vue, descriptors as Descriptors, computeds),
+  /** Disable reactivity for specified properties. */
+  const nonReactiveProps = (className as any)?.ivueDisableReactivity;
+  if (nonReactiveProps) {
+    for (const prop of nonReactiveProps) {
+      const descriptor = accessors.get(prop);
+      if (descriptor) {
+        defineProperty(vue, prop, {
+          get: descriptor.get?.bind(vue),
+          set: descriptor.set?.bind(vue),
+          enumerable: descriptor.enumerable,
+          configurable: descriptor.configurable,
+        });
+      } else {
+        console.log('des  criptor', prop, descriptor);
+        vue[prop] = markRaw(vue[prop]);
+      }
+    }
+  }
+
+  // In ivue(), for method binding:
+  const methodDescriptor: PropertyDescriptor = {
+    writable: true,
+    configurable: true,
+    enumerable: false,
+  };
+  /** Bind all methods to the vue instance. */
+  for (const methodName of methods) {
+    methodDescriptor.value = vue[methodName].bind(vue);
+    defineProperty(vue, methodName, methodDescriptor);
+  }
+
+  /** Define .toRefs() method on the vue instance. */
+  defineProperty(vue, 'toRefs', {
+    get: (() => {
+      /** Lazy loaded toRefs function cache. */
+      let toRefsFn: IVueToRefsFn<T> | null = null;
+      return () =>
+        toRefsFn ?? (toRefsFn = ivueToRefs(vue, accessors, computeds));
+    })(),
+    enumerable: false,
+  });
+
+  /** Define .clone() method on the vue instance. */
+  defineProperty(vue, 'clone', {
+    value: (...cloneArgs: CloneArgsFor<InstanceType<T>>) =>
+      ivueClone(className, args, vue, accessors, methods, cloneArgs),
+    enumerable: false,
+  });
+
+  /** Mark as ivue instance */
+  defineProperty(vue, IVUE_INSTANCE_SYMBOL, {
+    value: true,
     enumerable: false,
+    configurable: false,
+    writable: false,
   });
 
   /** Run ivue .init() initializer method, if it exists in the class. */
-  if ('init' in vue) vue.init();
+  vue?.init?.(false);
 
   return vue;
-}
+};
 
-/**
- * Store all props for each class prototype processed by:
- * @see {getAllClassProperties}
- */
-const propsMap: Map<object, Set<string> | any> = new Map();
+const ivueClone = <T extends AnyClass>(
+  className: T,
+  args: InferredArgs<T>,
+  vueSrc: IVue<T>,
+  accessors: Accessors,
+  methods: Set<string>,
+  cloneArgs: CloneArgsFor<InstanceType<T>> = [] as CloneArgsFor<InstanceType<T>>
+): IVue<T> => {
+  const computeds: Computeds | any = accessors?.size
+    ? createObject(null)
+    : null;
+
+  /** Create a reactive instance of the class. */
+  const vue = reactive(new className(...args));
+  const { onlyProps } = getClassPropertiesAccessorsMap(vue);
 
-/**
- * Get properties of an entire class prototype ancestors chain as a Map.
- */
-export function getAllClassProperties(obj: object): Set<string> {
-  /* Retrieve props from cache */
-  if (propsMap.has(obj.constructor)) {
-    return propsMap.get(obj.constructor);
+  /** Clone properties. */
+  const cloneByRef = (className as any).ivueCloneByReference;
+  const deepCloneArgs = activeDeepCloneArgsMap.get(className);
+
+  if (cloneByRef) {
+    for (const prop of onlyProps) {
+      vue[prop] = cloneByRef.has(prop)
+        ? vueSrc[prop]
+        : deepClone(vueSrc[prop], deepCloneArgs);
+    }
+  } else {
+    for (const prop of onlyProps) {
+      vue[prop] = deepClone(vueSrc[prop], deepCloneArgs);
+    }
   }
 
-  const originalConstructor = obj.constructor;
+  /** Setup accessors as computeds. */
+  for (const [prop, descriptor] of accessors) {
+    /** Convert descriptor to computed. */
+    defineProperty(vue, prop, {
+      get: () =>
+        computeds[prop] ??
+        (computeds[prop] = computed({
+          get: descriptor.get?.bind(vue) as unknown,
+          set: descriptor.set?.bind(vue),
+        } as any)) /** Create the computed and return it, because we are in reactive scope, .value will auto unwrap itself. */,
+      enumerable: descriptor.enumerable,
+      configurable: descriptor.configurable,
+    });
+  }
 
-  const allProps: Set<string> = new Set();
-  do {
-    Object.getOwnPropertyNames(obj).forEach((prop) => {
-      /* 'caller', 'callee', 'arguments', 'constructor' are
-       * special object properties, so should be skipped. */
-      if (!['caller', 'callee', 'arguments', 'constructor'].includes(prop)) {
-        allProps.add(prop);
+  /** Disable reactivity for specified properties. */
+  const nonReactiveProps = (className as any)?.ivueDisableReactivity;
+  if (nonReactiveProps) {
+    for (const prop of nonReactiveProps) {
+      const descriptor = accessors.get(prop);
+      if (descriptor) {
+        defineProperty(vue, prop, {
+          get: descriptor.get?.bind(vue),
+          set: descriptor.set?.bind(vue),
+          enumerable: descriptor.enumerable,
+          configurable: descriptor.configurable,
+        });
+      } else {
+        vue[prop] = markRaw(vue[prop]);
       }
-    });
-    obj = Object.getPrototypeOf(obj);
-  } while (obj.constructor !== Object);
+    }
+  }
 
-  /** Save props in the props map. */
-  propsMap.set(originalConstructor, allProps);
+  /** Bind all methods to the vue instance. */
+  const methodDescriptor: PropertyDescriptor = {
+    writable: true,
+    configurable: true,
+    enumerable: false,
+  };
+  for (const methodName of methods) {
+    methodDescriptor.value = vue[methodName].bind(vue);
+    defineProperty(vue, methodName, methodDescriptor);
+  }
 
-  return allProps;
-}
+  /** Define .toRefs() method on the vue instance. */
+  defineProperty(vue, 'toRefs', {
+    get: (() => {
+      /** Lazy loaded toRefs function cache. */
+      let toRefsFn: IVueToRefsFn<T> | null = null;
+      return () =>
+        toRefsFn ?? (toRefsFn = ivueToRefs(vue, accessors, computeds));
+    })(),
+    enumerable: false,
+  });
+
+  /** Define .clone() method on the vue instance. */
+  defineProperty(vue, 'clone', {
+    value: (...cloneArgs: CloneArgsFor<InstanceType<T>>) =>
+      ivueClone(className, args, vue, accessors, methods, cloneArgs),
+    enumerable: false,
+  });
+
+  /** Mark as ivue instance */
+  defineProperty(vue, IVUE_INSTANCE_SYMBOL, {
+    value: true,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+
+  /** Run ivue .init() initializer method, if it exists in the class. */
+  vue?.init?.(true, ...cloneArgs);
+
+  return vue;
+};
 
 /**
  * `iref()` is an alias for Vue ref() function but returns an unwrapped type without the .value
  * `iref()` does not alter the behavior of ref(), but simply transforms the type to an unwrapped raw value.
  * @param val T
- * @returns {T}
+ * @returns {T} Ref but with type unwrapped
  */
 export const iref = ref as <T = any>(value?: T) => T;
 
@@ -336,132 +613,87 @@ export const iref = ref as <T = any>(value?: T) => T;
  * `ishallowRef()` is an alias for Vue shallowRef() function but returns an unwrapped type without the .value
  * `ishallowRef()` does not alter the behavior of shallowRef(), but simply transforms the type to an unwrapped raw value.
  * @param val T
- * @returns {T}
+ * @returns {T} ShallowRef but with type unwrapped
  */
 export const ishallowRef = shallowRef as <T = any>(value?: T) => T;
 
 /**
- * Three modes of operation:
- * 1. `iuse(useComposable(arg, arg2, arg3, ...))` converts the return types of a Composable / Ref to pure raw unwrapped type definition.
- * Returns for all properties of an object an unwrapped raw type definition,
- * unwraps direct Refs & ComputedRefs as well down to their raw types.
+ * `iuse()` is a helper function that unwraps any Vue 3 composable return type down to its bare types.
  *
- * 2. `iuse(useComposable, arg, arg2, arg3, ...)` for cleaner syntax for #1, it does exactly the same thing but
- * here the TypeScript inference works for composable function arguments to assist you with intellisence,
- * like they work for constructor arguments in the cause of `ivue()` core function,
- * making the API cleaner to look at and make it compatible with how this function operates with classes, see #3.
+ * It does not alter the behavior of the composable, but simply transforms the type to an unwrapped raw value.
  *
- * 3. `iuse(AnyClass, ...args)` If AnyClass is supplied and that class's arguments into `iuse(AnyClass, ...args)`,
- * it returns an 'ivue(AnyClass, ...args).toRefs()` object for all properties but casts
- * their types as raw (no-Ref) types to fit with reactive() structure of the ivue class context.
- */
-export function iuse<T extends AnyClass | AnyFn | Object | any>(
-  classFunctionObject?: T,
-  ...args: T extends AnyClass
-    ? InferredArgs<T>
-    : T extends AnyFn
-    ? Parameters<T extends (...args: any[]) => any ? T : any>
-    : any
-): T extends AnyClass ? InstanceType<T> : Use<T> {
-  return typeof classFunctionObject === 'function'
-    ? isClass(classFunctionObject)
-      ? /** Run IVUE but return full Refs, yet property 'true' makes `.toRefs(true)` cast the type to the unwrapped raw type definition instead of a `.value` Ref. */
-        ivue(
-          classFunctionObject as T extends AnyClass ? T : any,
-          ...(args as InferredArgs<T extends AnyClass ? T : any>)
-        ).toRefs(true)
-      : /** Run Vue 3 Standard Composable but also unwrap it to bare raw types. */
-        (classFunctionObject as AnyFn)(
-          ...(args as Parameters<T extends AnyFn ? AnyFn : any>)
-        )
-    : (classFunctionObject as unknown as Use<T>) /** Unwrap any other Object or any type down to its bare types. */;
-}
+ * @param obj Any Vue 3 composable return type or any object or any type
+ * @returns {Use<T>} Composable with types unwrapped
+ */
+export const iuse = <T extends object>(obj: T): Use<T> =>
+  obj as unknown as Use<T>; /** Unwrap any other Object or any type down to its bare types. */
 
 /**
  * Convert reactive ivue class to Vue 3 refs.
  *
  * @param vue @see IVue
- * @param descriptors @see Descriptors
+ * @param accessors @see Accessors
  * @param computeds @see Computeds
  * @returns {ExtendWithToRefs<T>['toRefs']}
  */
-function ivueToRefs<T extends AnyClass>(
+const ivueToRefs = <T extends AnyClass>(
   vue: IVue<T>,
-  descriptors: Descriptors,
+  accessors: Accessors,
   computeds: Computeds
-): IVueToRefsFn<T> {
+): IVueToRefsFn<T> => {
+  /** Caches for toRefs function */
+  /** Cached accessor function */
+  const getAccessor = accessors.get.bind(accessors);
+  /** Get all class properties */
+  const { allProps } = getClassPropertiesAccessorsMap(vue);
+  /** The actual toRefs function returned. */
   return function (
-    props?: (keyof InstanceType<T>)[] | boolean,
+    props: (string & keyof InstanceType<T>)[] | boolean = false,
     unwrap?: boolean /** This property helps with TypeScript function definition overloading of return types and is not being used inside the function itself. */
   ): any /** @see {ReturnType<IVueToRefsFn<T>>} */ {
     /** Resulting refs store. */
-    const result: Record<string | number | symbol, any> = {};
-
-    /** Output specific props only, if props are specified. */
-    if (Array.isArray(props)) {
-      for (let i = 0; i < props.length; i++) {
-        const prop = props[i] as any;
-        /** Handle descriptors. */
-        if (descriptors.has(prop)) {
-          if (prop in computeds) {
-            /** Return vue computed with .value from computeds store. */
-            result[prop] = computeds[prop];
-          } else {
-            /** Initialize & store vue computed. */
-            const descriptor = descriptors.get(prop);
-            result[prop] = computeds[prop] = computed({
-              get: descriptor?.get?.bind(vue) as any,
-              set: descriptor?.set?.bind(vue),
-            } as any);
-          }
-        } else {
-          /** Handle methods. */
-          if (typeof vue[prop] === 'function') {
-            /** Bind method to vue, makes method destructuring point to right instance. */
-            result[prop] = vue[prop].bind(vue);
-          } else {
-            /** Convert simple reactive prop to a Ref. */
-            result[prop] = toRef(vue, prop);
-          }
-        }
+    const result: Record<string, any> = {};
+
+    /** Convert all props to refs and leave functions as is. */
+    if (isArray(props)) {
+      for (const prop of props) {
+        const kind = allProps.get(prop);
+        resolveIvueToRefs(result, prop, kind, vue, getAccessor, computeds);
       }
     } else {
-      /** Convert all props to refs and leave functions as is. */
-      let allProps: null | Set<string> = new Set(getAllClassProperties(vue));
-
-      /** Convert descriptors (non enumerable by default in JS). */
-      descriptors.forEach((descriptor, prop) => {
-        if (prop in computeds) {
-          /** Return vue computed with .value from computeds store. */
-          result[prop] = computeds[prop];
-        } else {
-          /** Initialize vue computed ref & store it in result. */
-          result[prop] = computeds[prop] = computed({
-            get: descriptor.get?.bind(vue) as any,
-            set: descriptor.set?.bind(vue),
-          } as any);
-        }
-        /** Delete descriptor from props as it was already processed. */
-        allProps?.delete(prop as string);
-      });
-
-      allProps.forEach((prop) => {
-        if (typeof vue[prop] === 'function') {
-          /** Bind method to vue, makes method destructuring point to right instance. */
-          result[prop] = vue[prop].bind(vue);
-        } else {
-          /** Convert simple reactive prop to a Ref. */
-          result[prop] = toRef(vue, prop);
-        }
-      });
-
-      /** Memory optimization. */
-      allProps = null;
+      for (const [prop, kind] of allProps.entries()) {
+        resolveIvueToRefs(result, prop, kind, vue, getAccessor, computeds);
+      }
     }
 
-    return result as any;
+    return result as any; /** @see {ReturnType<IVueToRefsFn<T>>} */
   };
-}
+};
+
+/**
+ * Resolve property to ref, method or computed and assign it to result.
+ * @private
+ */
+const resolveIvueToRefs = (
+  result: Record<string, any>,
+  prop: string,
+  kind: PropKind | undefined,
+  vue: IVue<any>,
+  getAccessor: Accessors['get'],
+  computeds: Record<string, ComputedRef<any>>
+): void => {
+  if (kind === PropKind.Accessor) {
+    const descriptor = getAccessor(prop) as PropertyDescriptor;
+    result[prop] =
+      computeds[prop] ??
+      (computeds[prop] = computed({
+        get: descriptor.get?.bind(vue) as unknown,
+        set: descriptor.set?.bind(vue),
+      } as any));
+  } else if (kind === PropKind.Data) {
+    result[prop] = toRef(vue, prop);
+  }
+};
 
 /**
  * Vue props interface in defineComponent() style.
@@ -489,19 +721,19 @@ export type VuePropsWithDefaults<T extends VuePropsObject> = {
  * @param val Any value
  * @returns boolean If it's a JavaScript Class returns true
  */
-export function isClass(val: any): boolean {
+export const isClass = (val: any): boolean => {
   if (typeof val !== 'function') return false; // Not a function, so not a class function either
 
   if (!val.prototype) return false; // Arrow function, so not a class
 
   // Finally -> distinguish between a normal function and a class function
-  if (Object.getOwnPropertyDescriptor(val, 'prototype')?.writable) {
+  if (getOwnPropertyDescriptor(val, 'prototype')?.writable) {
     // Has writable prototype
     return false; // Normal function
   } else {
     return true; // Class -> Not a function
   }
-}
+};
 
 /**
  * Creates props with defaults in defineComponent() style.
@@ -528,26 +760,214 @@ export function 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.
  */
-export function propsWithDefaults<T extends VuePropsObject>(
+export const propsWithDefaults = <T extends VuePropsObject>(
   defaults: Record<string, any>,
-  typedProps: T
-): VuePropsWithDefaults<T> {
+  typedProps: T,
+  deepCloneArgs: IVueDeepCloneArgsMap | undefined = undefined
+): VuePropsWithDefaults<T> => {
   for (const prop in typedProps) {
-    if (typeof defaults?.[prop] === 'object' && defaults?.[prop] !== null) {
+    const def = defaults?.[prop];
+    const typed = typedProps[prop];
+
+    /** Skip if prop is required — Vue will enforce it at runtime */
+    if (typed.required) continue;
+
+    /** Skip if default is undefined */
+    if (def === undefined) continue;
+
+    if (typeof def === 'object' && def !== null) {
       /** Handle Arrays & Objects -> wrap them with an arrow function. */
-      typedProps[prop].default = () => defaults?.[prop];
+      typedProps[prop].default = () => deepClone(def, deepCloneArgs);
     } else {
-      if (isClass(defaults?.[prop])) {
+      if (isClass(def)) {
         /** Handle JavaScript Classes -> wrap them with an arrow function */
-        typedProps[prop].default = () => defaults?.[prop];
+        typedProps[prop].default = () => def;
       } else {
         /** Handle JavaScript Function And All primitive properties -> output directly */
-        typedProps[prop].default = defaults?.[prop];
+        typedProps[prop].default = def;
       }
     }
   }
   return typedProps as VuePropsWithDefaults<T>;
-}
+};
+
+/**
+ * Copies own properties (including symbols and non-enumerable) from source to target.
+ * Recursively deep clones values, but preserves getters/setters as-is.
+ */
+export const copyOwnProps = (
+  source: any,
+  target: any,
+  deepCloneArgs: IVueDeepCloneArgsMap | undefined,
+  seen: WeakMap<object, any>
+) => {
+  // 1. Get all descriptors (String keys AND Symbol keys)
+  const descriptors = Object.getOwnPropertyDescriptors(source);
+
+  // 2. Iterate over all keys returned by Reflect (safety for Proxies/Environments)
+  for (const key of Reflect.ownKeys(descriptors)) {
+    const desc = descriptors[key as any];
+
+    // 3. If it is a data descriptor (has a value), we must deep clone the value.
+    //    We do NOT clone getters/setters (we copy the function reference).
+    if ('value' in desc) {
+      desc.value = deepClone(desc.value, deepCloneArgs, seen);
+    }
+
+    // 4. Define on target
+    Object.defineProperty(target, key, desc);
+  }
+};
+
+export let activeDeepCloneArgsMap = new WeakMap<
+  AnyClass,
+  IVueDeepCloneArgsMap
+>();
+
+export const deepClone = (
+  source: any,
+  deepCloneArgs?: IVueDeepCloneArgsMap,
+  seen: WeakMap<object, any> = new WeakMap()
+): any => {
+  // --- TIER 1: The "Every Call" Checks (Fastest) ---
+  if (source == null || typeof source !== 'object') return source;
+  if (seen.has(source)) return seen.get(source);
+
+  // --- TIER 2: The "Hottest" Collection (Arrays) ---
+  if (isArray(source)) {
+    const len = source.length;
+    const out = new Array(len);
+    seen.set(source, out);
+    for (let i = 0; i < len; i++) {
+      out[i] = deepClone(source[i], deepCloneArgs, seen);
+    }
+    return out;
+  }
+
+  // --- TIER 3: The "Hottest" Objects (Plain Objects) ---
+  const prototype = getPrototypeOf(source);
+  if (prototype === Object.prototype || prototype === null) {
+    const out = createObject(prototype);
+    seen.set(source, out);
+    copyOwnProps(source, out, deepCloneArgs, seen);
+    return out;
+  }
+
+  // --- TIER 4: IVue Special Logic (Your Framework) ---
+  // Checked here because it's specific to your domain
+  if (source[IVUE_INSTANCE_SYMBOL]) {
+    const srcClass = source.constructor as IVueClass<any>;
+    if (srcClass.ivueGlobalStore) {
+      seen.set(source, source);
+      return source;
+    }
+    let out;
+    if (deepCloneArgs?.has(srcClass)) {
+      activeDeepCloneArgsMap.set(srcClass, deepCloneArgs);
+      try {
+        out = source.clone(...(deepCloneArgs.get(srcClass) ?? []));
+      } finally {
+        activeDeepCloneArgsMap.delete(srcClass);
+      }
+    } else {
+      out = source.clone();
+    }
+    seen.set(source, out);
+    return out;
+  }
+
+  // --- TIER 5: Common Built-ins (Sorted by Likelihood) ---
+  // instanceof is fast, but order matters slightly for CPU branch prediction
+  if (source instanceof Date) {
+    return new Date(source.getTime());
+  }
+  if (source instanceof Map) {
+    const out = new (source.constructor as any)();
+    seen.set(source, out);
+    for (const [k, v] of source) {
+      out.set(
+        deepClone(k, deepCloneArgs, seen),
+        deepClone(v, deepCloneArgs, seen)
+      );
+    }
+    return out;
+  }
+  if (source instanceof Set) {
+    const out = new (source.constructor as any)();
+    seen.set(source, out);
+    for (const v of source) {
+      out.add(deepClone(v, deepCloneArgs, seen));
+    }
+    return out;
+  }
+
+  // --- TIER 6: Rare / Heavy Objects (The "Slow" Tail) ---
+  if (source instanceof RegExp) {
+    const out = new RegExp(source.source, source.flags);
+    out.lastIndex = source.lastIndex;
+    return out;
+  }
+  if (source instanceof Error) {
+    const out = new (source.constructor as any)(source.message);
+    seen.set(source, out);
+    copyOwnProps(source, out, deepCloneArgs, seen);
+    return out;
+  }
+  if (
+    source instanceof Promise ||
+    source instanceof WeakMap ||
+    source instanceof WeakSet
+  ) {
+    seen.set(source, source);
+    return source;
+  }
+  if (source instanceof DataView) {
+    // Clone the underlying buffer to ensure deep copy
+    const out = new DataView(
+      source.buffer.slice(0),
+      source.byteOffset,
+      source.byteLength
+    );
+    seen.set(source, out);
+    return out;
+  }
+  // Binary data (less common in UI state, but supported)
+  if (ArrayBuffer.isView(source) && !(source instanceof DataView)) {
+    const out = new (source.constructor as any)(source);
+    seen.set(source, out);
+    return out;
+  }
+  if (source instanceof ArrayBuffer) {
+    const out = source.slice(0);
+    seen.set(source, out);
+    return out;
+  }
+
+  // --- TIER 7: Final Fallback (Custom User Classes) ---
+  // If it's a class instance not handled above
+  const out = createObject(prototype);
+  seen.set(source, out);
+  copyOwnProps(source, out, deepCloneArgs, seen);
+  return out;
+};
+
+/**
+ * Clears the accessorsMethodsMaps, and propertiesAccessorsMaps WeakMaps.
+ * Useful for SSR scenarios where you want to reset the cache between requests.
+ * Also useful for testing purposes to ensure a clean state.
+ */
+export const clearCache = () => {
+  accessorsMethodsMaps = new WeakMap();
+  propertiesAccessorsMaps = new WeakMap();
+  activeDeepCloneArgsMap = new WeakMap();
+};
+
+/** Exported for testing purposes. */
+export const __test__ = {
+  copyOwnProps,
+  getClassAccessorsMethodsMap,
+  getClassPropertiesAccessorsMap,
+};
 
 /** Necessary ivue.ts to be treated as a module. */
 export {};