From 06c5a2d6f070c15483ba1b2469c5e5498d1ada05 Mon Sep 17 00:00:00 2001
From: Evgeny <ekalashnikov@gmail.com>
Date: Tue, 20 Aug 2024 00:10:19 -0400
Subject: [PATCH] super type overloads for toRefs() added to make it much more
 versatile, docs improved

---
 .../components/usage/CounterComposables.vue   |  4 +-
 .../usage/CounterComposablesDestructuring.vue |  2 +-
 .../CounterComposablesIvueDestructuring.vue   | 13 ++---
 .../components/usage/classes/CustomMouse.ts   |  2 +-
 docs/docs/pages/usage.md                      | 51 ++++++++++++++-----
 docs/package.json                             |  2 +-
 docs/yarn.lock                                |  8 +--
 src/ivue.ts                                   | 36 ++++++++-----
 8 files changed, 77 insertions(+), 41 deletions(-)

diff --git a/docs/docs/components/usage/CounterComposables.vue b/docs/docs/components/usage/CounterComposables.vue
index feb7cb3..d73fa9b 100644
--- a/docs/docs/components/usage/CounterComposables.vue
+++ b/docs/docs/components/usage/CounterComposables.vue
@@ -7,8 +7,8 @@ class Counter {
   increment() {
     this.count++;
   }
-  mouse = iuse(useMouse());
-  pointer = iuse(usePointer());
+  mouse = iuse(useMouse);
+  pointer = iuse(usePointer);
 }
 
 const counter = ivue(Counter);
diff --git a/docs/docs/components/usage/CounterComposablesDestructuring.vue b/docs/docs/components/usage/CounterComposablesDestructuring.vue
index 5fe14e3..bbd8dd4 100644
--- a/docs/docs/components/usage/CounterComposablesDestructuring.vue
+++ b/docs/docs/components/usage/CounterComposablesDestructuring.vue
@@ -34,7 +34,7 @@ class Counter {
       y: this.y,
       sum: this.sum,
       total: this.total
-    } = iuse(useCustomMouse(5)));
+    } = iuse(useCustomMouse, 5));
   }
 }
 
diff --git a/docs/docs/components/usage/CounterComposablesIvueDestructuring.vue b/docs/docs/components/usage/CounterComposablesIvueDestructuring.vue
index f432903..390f4ca 100644
--- a/docs/docs/components/usage/CounterComposablesIvueDestructuring.vue
+++ b/docs/docs/components/usage/CounterComposablesIvueDestructuring.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { CustomMouse } from './classes/CustomMouse';
 
-import { ivue, iref, iuse } from 'ivue';
+import { ivue, iref } from '../../../../src/ivue';
 
 class Counter {
   count = iref(0);
@@ -10,11 +10,10 @@ class Counter {
     this.count++;
   }
 
-
   /**
    * 'x', 'y', 'total' are Refs that will be unwrapped to their bare raw types and destructured into the class.
-   * Even though unwrapped (de-Refed), they will maintain their behavior as Refs and thus will maintain reactivity 
-   * and at the same time get destructured into this class root level scope because 
+   * Even though unwrapped (de-Refed), they will maintain their behavior as Refs and thus will maintain reactivity
+   * and at the same time get destructured into this class root level scope because
    * Vue 3's `reactive()` Proxy will be able to resolve those Refs internally.
    */
   x: CustomMouse['x']; // Unwrapped Ref<number> becomes -> number
@@ -28,7 +27,7 @@ class Counter {
       y: this.y,
       sum: this.sum,
       total: this.total,
-    } = iuse(CustomMouse, 5));
+    } = ivue(CustomMouse, 5).toRefs(true));
   }
 }
 
@@ -41,5 +40,7 @@ const counter = ivue(Counter);
   <br />
   Total (computed): {{ counter.total }}
   <br />
-  <button class="button" @click="() => counter.sum()">Click This Big Sum Button To Total X + Y</button>
+  <button class="button" @click="() => counter.sum()">
+    Click This Big Sum Button To Total X + Y
+  </button>
 </template>
diff --git a/docs/docs/components/usage/classes/CustomMouse.ts b/docs/docs/components/usage/classes/CustomMouse.ts
index 6ded518..71022d3 100644
--- a/docs/docs/components/usage/classes/CustomMouse.ts
+++ b/docs/docs/components/usage/classes/CustomMouse.ts
@@ -10,7 +10,7 @@ export class CustomMouse {
   _sum = iref(0);
 
   constructor(public requiredProp: number) {
-    ({ x: this.x, y: this.y } = iuse(useMouse()));
+    ({ x: this.x, y: this.y } = iuse(useMouse));
   }
 
   sum() {
diff --git a/docs/docs/pages/usage.md b/docs/docs/pages/usage.md
index a7195fb..8bd5e5c 100644
--- a/docs/docs/pages/usage.md
+++ b/docs/docs/pages/usage.md
@@ -11,6 +11,7 @@ import CounterInternalRefs from '../components/usage/CounterInternalRefs.vue'
 import CounterComposables from '../components/usage/CounterComposables.vue'
 import CounterComposablesDestructuring from '../components/usage/CounterComposablesDestructuring.vue'
 import CounterComposablesIvueDestructuring from '../components/usage/CounterComposablesIvueDestructuring.vue'
+import CounterComposablesIvue from '../components/usage/CounterComposablesIvue.vue'
 import CounterInsideComposables from '../components/usage/CounterInsideComposables.vue'
 import CounterComputeds from '../components/usage/CounterComputeds.vue'
 import CounterComputedsDisabled from '../components/usage/CounterComputedsDisabled.vue'
@@ -69,7 +70,7 @@ Classic Counter example built with `ivue`
 
 See the highlighted sections related to props.
 ::: code-group
-<<< @/components/usage/CounterWithProps.vue{5-8,11-12,24 vue:line-numbers}
+<<< @/components/usage/CounterWithProps.vue{vue:line-numbers}
 :::
 
 :::details For this example we initialize the component like this:
@@ -91,7 +92,7 @@ See the highlighted sections related to props.
 See the highlighted sections related to using emits.
 
 ::: code-group
-<<< @/components/usage/CounterWithPropsAndEmits.vue{9-11,14,17,23,31 vue:line-numbers}
+<<< @/components/usage/CounterWithPropsAndEmits.vue{vue:line-numbers}
 :::
 
 :::details For this example we initialize the component like this:
@@ -118,7 +119,7 @@ function onIncrement(value: number) {
 ### Refs defined externally in the component outside of the class.
 
 ::: code-group
-<<< @/components/usage/CounterExternalRefs.vue{5,8,12,16,24 vue:line-numbers}
+<<< @/components/usage/CounterExternalRefs.vue{vue:line-numbers}
 :::
 :::details For this example we initialize the component like this:
 
@@ -137,7 +138,7 @@ function onIncrement(value: number) {
 ### Refs defined internally inside of the class.
 
 ::: code-group
-<<< @/components/usage/CounterInternalRefs.vue{7,15,25 vue:line-numbers}
+<<< @/components/usage/CounterInternalRefs.vue{vue:line-numbers}
 :::
 
 :::details For this example we initialize the component like this:
@@ -160,7 +161,7 @@ function onIncrement(value: number) {
 See the highlighted sections related to `defineExpose`.
 
 ::: code-group
-<<< @/components/usage/CounterDefineExpose.vue{8 vue:line-numbers}
+<<< @/components/usage/CounterDefineExpose.vue{vue:line-numbers}
 <<< @/components/usage/CounterDefineExposeClass.ts{ts:line-numbers}
 :::
 
@@ -200,7 +201,7 @@ function decrement() {
 ### Pick allowed interface properties for `defineExpose()`
 
 ::: code-group
-<<< @/components/usage/CounterDefineExposeAdvanced.vue{9,23 vue:line-numbers}
+<<< @/components/usage/CounterDefineExposeAdvanced.vue{vue:line-numbers}
 :::
 
 ## Using Composables
@@ -209,7 +210,7 @@ function decrement() {
 
 See the highlighted sections related to composable usage.
 ::: code-group
-<<< @/components/usage/CounterComposables.vue{4,11,19 vue:line-numbers}
+<<< @/components/usage/CounterComposables.vue{vue:line-numbers}
 :::
 
 :::details For this example we initialize the component like this:
@@ -231,7 +232,7 @@ See the highlighted sections related to composable usage.
 See the highlighted sections related to destructuring composable usage.
 
 ::: code-group
-<<< @/components/usage/CounterComposablesDestructuring.vue{4,10,20-21,23-24,27-32 vue:line-numbers}
+<<< @/components/usage/CounterComposablesDestructuring.vue{vue:line-numbers}
 <<< @/components/usage/functions/useCustomMouse.ts{ts:line-numbers} [functions/useCustomMouse.ts]
 :::
 
@@ -249,12 +250,36 @@ See the highlighted sections related to destructuring composable usage.
 
 <CounterComposablesDestructuring />
 
+
+### Using `ivue` Composables Directly
+
+Using `ivue` based composables assigned to a class property:
+
+::: code-group
+<<< @/components/usage/CounterComposablesIvue.vue{vue:line-numbers}
+<<< @/components/usage/classes/CustomMouse.ts{ts:line-numbers} [classes/CustomMouse.ts]
+:::
+
+:::details For this example we initialize the component like this:
+
+```vue
+<template>
+  <CounterComposablesIvue />
+</template>
+```
+
+:::
+
+<div style="font-size: 18px; font-weight: 500;">Result</div>
+
+<CounterComposablesIvue />
+
 ### Using `ivue` Composables With Destructuring
 
-See the highlighted sections related to using `ivue` based composables.
+See the sections related to using `ivue` based composables initialized through class destructuring assignment.
 
 ::: code-group
-<<< @/components/usage/CounterComposablesIvueDestructuring.vue{14 vue:line-numbers}
+<<< @/components/usage/CounterComposablesIvueDestructuring.vue{vue:line-numbers}
 <<< @/components/usage/classes/CustomMouse.ts{ts:line-numbers} [classes/CustomMouse.ts]
 :::
 
@@ -278,7 +303,7 @@ See the highlighted sections related to using `ivue` based composables.
 See the highlighted sections related to using `ivue` inside a composable.
 
 ::: code-group
-<<< @/components/usage/CounterInsideComposables.vue{14 vue:line-numbers}
+<<< @/components/usage/CounterInsideComposables.vue{vue:line-numbers}
 :::
 
 :::details For this example we initialize the component like this:
@@ -301,7 +326,7 @@ See the highlighted sections related to using `ivue` inside a composable.
 See the highlighted sections related to getters.
 
 ::: code-group
-<<< @/components/usage/CounterComputeds.vue{10,13,23,24 vue:line-numbers}
+<<< @/components/usage/CounterComputeds.vue{vue:line-numbers}
 :::
 
 :::details For this example we initialize the component like this:
@@ -319,7 +344,7 @@ See the highlighted sections related to getters.
 You can disable computed getters via `static ivue = { getter: false }`, see below:
 
 ::: code-group
-<<< @/components/usage/CounterComputedsDisabled.vue{10-12 vue:line-numbers}
+<<< @/components/usage/CounterComputedsDisabled.vue{vue:line-numbers}
 :::
 
 The result of this example is identical to the above.
diff --git a/docs/package.json b/docs/package.json
index 566a982..b956992 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -18,7 +18,7 @@
     "eslint-plugin-import": "^2.29.1",
     "eslint-plugin-vue": "^9.14.1",
     "execa": "^8.0.0",
-    "ivue": "^1.2.0",
+    "ivue": "^1.2.1",
     "typescript": "^4.5.4",
     "vite-plugin-dynamic-import": "^1.5.0",
     "vite-tsconfig-paths": "^4.3.2",
diff --git a/docs/yarn.lock b/docs/yarn.lock
index 0ab86ce..356e446 100644
--- a/docs/yarn.lock
+++ b/docs/yarn.lock
@@ -2193,10 +2193,10 @@ isexe@^2.0.0:
   resolved "https://registry.yarnpkg.com/isexe/-/isexe-2.0.0.tgz#e8fbf374dc556ff8947a10dcb0572d633f2cfa10"
   integrity sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==
 
-ivue@^1.2.0:
-  version "1.2.0"
-  resolved "https://registry.yarnpkg.com/ivue/-/ivue-1.2.0.tgz#dfcd014c123d82f647d94bcab356179dce2ec3ff"
-  integrity sha512-IGhB63qOmDvp+U2mh3UnGCSstljLtyfPzQOCqqEicpHQpZIcWX/NYKDp84ykErZ0GU9Q1L9nzLH2JbVmued6+A==
+ivue@^1.2.1:
+  version "1.2.1"
+  resolved "https://registry.yarnpkg.com/ivue/-/ivue-1.2.1.tgz#a80b8a0c660c649c9ee644e5968abe6366c87a73"
+  integrity sha512-pBgv8gF1UaT6Rou+NyHB6w7pIhzXQFLvZ3xz6i8ls5HQXHMKHNp5xF/qyTpgt7ug05/LauKjysq6CkIJLP81uA==
 
 js-tokens@^4.0.0:
   version "4.0.0"
diff --git a/src/ivue.ts b/src/ivue.ts
index aa39724..f9e09db 100644
--- a/src/ivue.ts
+++ b/src/ivue.ts
@@ -18,11 +18,20 @@ export interface ExtendWithToRefs<T extends AnyClass> {
 }
 
 /**
- * .toRefs() method type definition converts reactive class properties to composable .value properties.
- */
-export type IVueToRefsFn<T extends AnyClass> = (
-  props?: (keyof InstanceType<T>)[]
-) => IVueRefs<InstanceType<T>>;
+ * Type definition for `.toRefs()` method converts reactive class properties to composable .value properties.
+ * But if unwrap = true is specified, the refs will be unwrapped refs available to be merged with the the root class properties.
+ */
+export interface IVueToRefsFn<T extends AnyClass> {
+  <P extends keyof InstanceType<T>, B extends boolean>(
+    props: P[],
+    unwrap?: B
+  ): B extends true
+    ? Pick<InstanceType<T>, P>
+    : Pick<IVueRefs<InstanceType<T>>, P>;
+  (props: true): InstanceType<T>;
+  (props: false): IVueRefs<InstanceType<T>>;
+  (): IVueRefs<InstanceType<T>>;
+}
 
 /**
  * Converts a class properties to a composable .value Refs using ToRef vue type,
@@ -315,8 +324,8 @@ export function getAllClassProperties(obj: object): Set<string> {
 }
 
 /**
- * `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.
+ * `iref()` is an alias for Vue ref() function but returns an unwrap type without the .value
+ * `iref()` does not alter the behavior of ref(), but simply transforms the type to an unwrap raw value.
  * @param val T
  * @returns {UnwrapRef<T>}
  */
@@ -325,7 +334,7 @@ export const iref = ref 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 type definition.
- * Returns for all properties of an object an unwrapped raw type definition,
+ * Returns for all properties of an object an unwrap raw type definition,
  * unwraps direct Refs & ComputedRefs as well down to their raw types.
  *
  * 2. `iuse(useComposable, arg, arg2, arg3, ...)` for cleaner syntax for #1, it does exactly the same thing but
@@ -337,7 +346,7 @@ export const iref = ref as <T = any>(value?: T) => T;
  * 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>(
+export function iuse<T extends AnyClass | AnyFn | Object | any>(
   classFunctionObject?: T,
   ...args: T extends AnyClass
     ? InferredArgs<T>
@@ -375,13 +384,14 @@ function ivueToRefs<T extends AnyClass>(
   computeds: Computeds
 ): ExtendWithToRefs<T>['toRefs'] {
   return function (
-    props?: (keyof InstanceType<T>)[]
-  ): IVueRefs<InstanceType<T>> {
+    props?: (keyof InstanceType<T>)[] | boolean,
+    unwrap?: boolean
+  ): 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) && props.length) {
+    if (Array.isArray(props)) {
       for (let i = 0; i < props.length; i++) {
         const prop = props[i] as any;
         /** Handle descriptors. */
@@ -442,7 +452,7 @@ function ivueToRefs<T extends AnyClass>(
       allProps = null;
     }
 
-    return result as IVueRefs<InstanceType<T>>;
+    return result as any;
   };
 }