ivue 1.2.4 → 1.3.0

package/docs/docs/components/advanced-usage/ConvertLegacy.vue

@@ -0,0 +1,58 @@
+<script setup lang="ts">
+class Chair {
+    // Defaults that will be common for all the instances
+    static backSupport: boolean = true;
+    static armRests: boolean = true;
+
+    // Instance properties
+    color: string;
+    seatHeight: number;
+    recliningAngle: number;
+    headSupport: boolean;
+    padding: string;
+    seatSize: string;
+    isHeightAdjustable: boolean;
+    isMovable: boolean;
+    type: string;
+
+    constructor(
+        color: string,
+        seatHeight: number,
+        recliningAngle: number,
+        headSupport: boolean,
+        padding: string,
+        seatSize: string,
+        isHeightAdjustable: boolean,
+        isMovable: boolean
+    ) {
+        // Defaults which can be changed by the subclass class.
+        this.color = color;
+        this.seatHeight = seatHeight;
+        this.recliningAngle = recliningAngle;
+        this.headSupport = headSupport || false;
+        this.padding = padding || "3 inch";
+        this.seatSize = seatSize || "16 inch";
+        this.isHeightAdjustable = isHeightAdjustable || false;
+        this.isMovable = isMovable || false;
+        this.type = "Chair";
+        console.log(Chair.printDefaultProps()); // Usage of static method inside constructor
+    } 
+
+    static logObjectProps(): void {
+        console.dir(this);
+    }
+
+    // Static within static usage
+    static printDefaultProps(): void {
+        console.log(`Chair Back Support = ${this.backSupport}`);
+        console.log(`Arm rests support = ${this.armRests}`);
+    }
+
+    adjustableHeight(): void {};
+    adjustAngle(): void {};
+    moveChair(): void {};    
+}
+</script>
+<template>
+  <div>Hello</div>
+</template>

package/docs/docs/pages/advanced-usage.md

@@ -8,4 +8,5 @@
 ## Extend Emits
 ## Extend Slots
 ## Extend Classes
-## Extend Components
+## Extend Components
+## Convert Legacy Classes to Reactive Classes with `ivue` {#legacy-to-reactive}

package/docs/docs/pages/api.md

@@ -28,7 +28,11 @@ Core `ivue(className, ...args)` initializer is able to infer and validate the co
 
 ### `iref()`
 
-Create a regular `vue` Ref but cast the type to the internal unreactive type, because properties auto-unwrap in `reactive()` object that is being created by `ivue` upon initialization.
+Is simply an alias to Vue 3 `ref()` function but casts the type to the internal unreactive type, because properties auto-unwrap in `reactive()` object that is being created by `ivue` upon initialization.
+
+### `ishallowRef()`
+
+Is simply an alias Vue 3 `shallowRef()` function but casts the type to the internal unreactive type, because properties auto-unwrap in `reactive()` object that is being created by `ivue` upon initialization.
 
 ### `iuse()`
 
@@ -77,9 +81,9 @@ This improves performance if `box` has many other properties that we do not need
 
 ## Core Types
 
-### `IVue`
+### `IVue` {#IVue}
 
-### `Use`
+### `Use` {#Use}
 
 
 ## Utility Functions

package/docs/docs/pages/guidelines.md

@@ -75,7 +75,7 @@ class Counter {
   }
 }
 
-/** ✓ Properly intilized IVUE class runner. */
+/** ✓ Properly initialized IVUE class runner. */
 const counter = ivue(Counter, props, emit);
 ```
 

package/docs/docs/pages/how-its-made.md

@@ -7,9 +7,9 @@ The original inspiration for `ivue` comes from `MobX` React state management lib
 
 ##  Epiphany
 
-After building several ports from `MobX` state management library to `VueJS` to reactivity system I realized that Vue itself is far superior in its design and perfomance and can solve the same problem without relying on second hand-library, but for that my evolution of understanding of how JavaScript getters and setters work needed to happen. 
+After building several ports from `MobX` state management library to `VueJS` to reactivity system I realized that Vue itself is far superior in its design and performance and can solve the same problem without relying on second hand-library, but for that my evolution of understanding of how JavaScript getters and setters work needed to happen. 
 
-And one lucky and sunny day driving back from work in an eureka moment of light it occured to me how to use Vue 3 computeds in place of getters in classes (Yes, apparently my brain does coding while driving a car).
+And one lucky and sunny day driving back from work in an eureka moment of light it occurred to me how to use Vue 3 computeds in place of getters in classes (Yes, apparently my brain does coding while driving a car).
 
 `ivue` relies on this very simple discovery of how to elegantly convert getters into Vue 3 computeds.
 
@@ -28,5 +28,5 @@ By default `ivue` does not rely on decorators, though you can use decorators if
 
 ## The Rest is Up To You
 `ivue` is like a small mustard seed core for the big tree trunk of Class Based Reactive applications to be built around it, that's why the path of utter simplicity was chosen.
-Everything else like an Inversion of Control (IOC) system, Traits, Mixins, Decorators can be built around the core `ivue` architecture and is upto the community of enthusiatic open source contributors, please share with us your vision of how you and all of can use `ivue` better.
+Everything else like an Inversion of Control (IOC) system, Traits, Mixins, Decorators can be built around the core `ivue` architecture and is up to the community of enthusiastic open source contributors, please share with us your vision of how you and all of can use `ivue` better.
 

package/docs/docs/pages/introduction.md

@@ -65,7 +65,7 @@ Things like IOC Container, Decorators, Traits, Mixins, etc. were omitted by desi
 
 
 
-## Infinite Vue Class Achitecture
+## Infinite Vue Class Architecture
 
 `ivue` replicates native JavaScript / TypeScript class implementation by extending descriptors (getters and setters) up the whole prototype ancestors chain thus supporting classical inheritance.
 

package/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.3",
+    "ivue": "^1.2.4",
     "typescript": "^4.5.4",
     "vite-plugin-dynamic-import": "^1.5.0",
     "vite-tsconfig-paths": "^4.3.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ivue",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "description": "Infinite Vue – Class Based Architecture for Vue 3",
   "type": "module",
   "exports": {
@@ -26,6 +26,11 @@
     "vue": "^3.0.0",
     "vue-demi": "^0.0.0"
   },
+  "peerDependenciesMeta": {
+    "vue-demi": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@cypress/vite-dev-server": "^5.0.2",
     "@cypress/vue": "^5.0.3",

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { PropType, isReactive } from 'vue';
+import { PropType, isReactive, ref } from 'vue';
 
 import {
   ExtractPropDefaultTypes,
@@ -9,6 +9,7 @@ import {
   ivue,
   iref,
   propsWithDefaults,
+  iuse,
 } from '../ivue';
 
 class Basic {
@@ -431,6 +432,58 @@ describe('ivue', () => {
       expect(notComputedCalls).toBe(3); // Always incrementing
     });
   });
+  describe('core functions', () => {
+    let useComposable = () => {
+      return {
+        x: ref(0),
+        y: ref(0)
+      }
+    }
+    it('iref returns standard ref with .value but unwraps type', () => {
+      const bool = iref(true);
+      const str = iref('string');
+
+      // @ts-expect-error Unwraps type, only to be used within ivue Class or Vue 3 `reactive()` context
+      expect(bool.value).toBe(true);
+      // @ts-expect-error Unwraps type, only to be used within ivue Class or Vue 3 `reactive()` context
+      expect(str.value).toBe('string');
+    });
+
+    it('iuse(Object) returns standard ref with .value but unwraps type', () => {
+      const iuseComposable = iuse(useComposable());
+
+      // @ts-expect-error Unwraps type, only to be used within ivue Class or Vue 3 `reactive()` context
+      expect(iuseComposable.x.value).toBe(0)
+      // @ts-expect-error Unwraps type, only to be used within ivue Class or Vue 3 `reactive()` context
+      expect(iuseComposable.y.value).toBe(0);
+    });
+
+    it('iuse(Class, ...ClassProps) returns standard ref with .value but unwraps type', () => {
+      const iuseComposable = iuse(Item);
+      // @ts-expect-error Unwraps type, only to be used within ivue Class or Vue 3 `reactive()` context
+      expect(iuseComposable._width.value).toBe(5)
+      // @ts-expect-error Unwraps type, only to be used within ivue Class or Vue 3 `reactive()` context
+      expect(iuseComposable.unit.value).toBe('px');
+
+      const iuseComposable2 = iuse(Entity, 100);
+      // @ts-expect-error Unwraps type, only to be used within ivue Class or Vue 3 `reactive()` context
+      expect(iuseComposable2.height.value).toBe(100)
+      // @ts-expect-error Unwraps type, only to be used within ivue Class or Vue 3 `reactive()` context
+      expect(iuseComposable2.width.value).toBe(5);
+    });
+
+    it('iuse(Function, ...FunctionProps) returns standard ref with .value but unwraps type', () => {
+      
+      
+      const iuseComposable = iuse(useComposable);
+
+      // @ts-expect-error Unwraps type, only to be used within ivue Class or Vue 3 `reactive()` context
+      expect(iuseComposable.x.value).toBe(0)
+      // @ts-expect-error Unwraps type, only to be used within ivue Class or Vue 3 `reactive()` context
+      expect(iuseComposable.y.value).toBe(0);
+    });
+  });
+  
 
   describe('util functions', () => {
     it('isClass correctly determines if a value is a class', () => {
@@ -474,7 +527,8 @@ describe('ivue', () => {
         updatePath: '', // String
         updateEntity: false, // Boolean
         updateFieldsTemplate: [], // Array
-        updateFieldsParams: { // Object
+        updateFieldsParams: {
+          // Object
           active: true,
         },
         updateLabel: 'Update Item', // String
@@ -496,23 +550,23 @@ describe('ivue', () => {
       expect(_propsWithDefaults.updateFieldsTemplate.default).toBeTypeOf(
         'function'
       );
-      expect( 
+      expect(
         Array.isArray(
           (_propsWithDefaults.updateFieldsTemplate.default as () => any)()
         )
       ).toBe(true);
-      
+
       // Object
-      expect( 
+      expect(
         (_propsWithDefaults.updateFieldsParams.default as () => any)().active
       ).toBe(true);
-      
+
       // Class
       expect(_propsWithDefaults.runner.default).toBeTypeOf('function');
       expect(isClass((_propsWithDefaults.runner.default as () => any)())).toBe(
         true
       );
-      
+
       // Function
       expect(_propsWithDefaults.fn.default).toBeTypeOf('function');
       expect(isClass((_propsWithDefaults.fn.default as () => any)())).toBe(

package/src/ivue.ts

@@ -1,7 +1,7 @@
 /* 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, toRef } from 'vue';
+import { computed, reactive, ref, shallowRef, toRef } from 'vue';
 import type { Ref as DemiRef } from 'vue-demi';
 
 /** Types */
@@ -19,15 +19,21 @@ export interface ExtendWithToRefs<T extends AnyClass> {
 
 /**
  * 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.
+ * 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.
  */
 export interface IVueToRefsFn<T extends AnyClass> {
-  <P extends keyof InstanceType<T>, B extends boolean>(
+  <P extends keyof InstanceType<T>>(props: P[]): Pick<
+    IVueRefs<InstanceType<T>>,
+    P
+  >;
+  <P extends keyof InstanceType<T>>(props: P[], unwrap: false): Pick<
+    IVueRefs<InstanceType<T>>,
+    P
+  >;
+  <P extends keyof InstanceType<T>>(
     props: P[],
-    unwrap?: B
-  ): B extends true
-    ? Pick<InstanceType<T>, P>
-    : Pick<IVueRefs<InstanceType<T>>, P>;
+    unwrap: true
+  ): Pick<InstanceType<T>, P>;
   (props: true): InstanceType<T>;
   (props: false): IVueRefs<InstanceType<T>>;
   (): IVueRefs<InstanceType<T>>;
@@ -66,9 +72,7 @@ export type Unwrap<T> = T extends Ref | DemiRef
 /**
  * Fully unwraps to bare value types any Vue 3 composable return definition type.
  */
-export type Use<T = any> = Unwrap<
-  T extends AnyFn ? ReturnType<T> : T
->;
+export type Use<T = any> = Unwrap<T extends AnyFn ? ReturnType<T> : T>;
 
 /**
  * Extracts object defined emit types by converting them to a plain interface
@@ -324,17 +328,25 @@ export function getAllClassProperties(obj: object): Set<string> {
 }
 
 /**
- * `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.
+ * `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 {UnwrapRef<T>}
+ * @returns {T}
  */
 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}
+ */
+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 type definition.
- * Returns for all properties of an object an unwrap raw type definition,
+ * 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.
  *
  * 2. `iuse(useComposable, arg, arg2, arg3, ...)` for cleaner syntax for #1, it does exactly the same thing but
@@ -353,21 +365,19 @@ export function iuse<T extends AnyClass | AnyFn | Object | any>(
     : T extends AnyFn
     ? Parameters<T extends (...args: any[]) => any ? T : any>
     : any
-): T extends AnyClass
-  ? InstanceType<T>
-  : T extends AnyFn
-  ? Use<T>
-  : Unwrap<T> {
+): T extends AnyClass ? InstanceType<T> : Use<T> {
   return typeof classFunctionObject === 'function'
     ? isClass(classFunctionObject)
-      ? ivue(
+      ? /** 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)
-      : (classFunctionObject as AnyFn)(
+      : /** 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 Unwrap<T>);
+    : (classFunctionObject as unknown as Unwrap<T>) /** Unwrap any other Object or any type down to its bare types. */;
 }
 
 /**
@@ -385,7 +395,7 @@ function ivueToRefs<T extends AnyClass>(
 ): ExtendWithToRefs<T>['toRefs'] {
   return function (
     props?: (keyof InstanceType<T>)[] | boolean,
-    unwrap?: boolean
+    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> = {};